int to_ascii_extended(unsigned v_key,
unsigned scancode,
byte* key_state,
wide_character* buffer,
unsigned flags,
handle layout)
This function translates a given virtual key code and keyboard state to the corresponding character(s).
unsigned v_key
The virtual key code to be translated.
unsigned scancode
The hardware scan code of the key to be translated. The high order bit is set when the key is up (not depressed).
byte* key_state
A pointer to a 256 byte array that contains the current keyboard state. Each element (byte) in the array contains the state of one key. If the high-order bit of a byte is set, the key is down (pressed). When set, the low order bit indicates that the key is toggled on. The toggle bit of the caps lock key is relevant only in this function. The toggle state of the num lock and scroll lock keys is ignored.
wide_character* Buffer
A pointer to a buffer to receive the translated character(s).
unsigned flags
Indicates whether a menu is active.
| true | A menu is active. |
| false | No menu is active. |
handle Layout
The handle of the keyboard layout to use to translate the given code. This parameter can be a keyboard layout handle obtained via the function load_keyboard_layout.
int
| -1 | The virtual key is an accent or diacritic key. |
| 0 | The virtual key has no translation for the current state of the keyboard. |
| 1 | One character was copied to the buffer. |
| 2 | Two characters were copied to the buffer. |
More than a single character results when the key of an accent or diacritic character stored in the keyboard layout cannot be combined with the specified virtual key to form a single character.
The specified parameters may not be sufficient to translate the virtual-key code (because a previous accent or diacritic key may be stored in the keyboard layout).
Usually this function performs the translation based on the virtual key code. However, in some cases, bit 15 of the parameter scancode may be used to distinguish between a key press and a key release. The scan code is used for translating ALT+number key combinations.
Although num lock is a toggle key that affects keyboard behaviour, to_ascii_extended ignores the toggle setting (the low order bit) of key_state (virtual_key::num_lock) because the parameter v_key alone is sufficient to distinguish the cursor movement keys (virtual_key::home, virtual_key::insert etc) from the numeric keys (virtual_key::decimal, virtual_key::numeric_pad0 - virtual_key::numeric_pad9).