6. The New_Keyboard group of Modules

Most of the New Keyboard handling code is in the "plugin/kbd_unicode" subdirectory.

6.1. Functions in plugin/kbd_unicode/serv_xlat.c

These are the functions defined in plugin/kbd_unicode/serv_xlat.c.

6.1.1. compute_keynum

The task of compute_keynum() is to 'collect' keyboard bytes (e.g. 0xe0 prefixes) until it thinks it has assembled an entire keyboard event. The entire keyboard event is then returned, otherwise NUM_VOID is returned.

6.1.2. translate_key

translate_key takes a keysym event and calculates the appropriate bios translation.

As a side effect translate_key updates the apropriate pieces of state to reflect the current keyboard state.

Calling translate_key twice on the same data is likely to be hazardous.

6.1.3. put_rawkey

This function sends a raw keycode byte, e.g. read directly from the hardware, to DOS. It is both queued for the port60h emulation and processed for the BIOS keyboard buffer, using the national translation tables etc.

For DOS applications using int16h we will therefore not have to load KEYB.EXE, others (e.g. games) need their own drivers anyway.

This function is used if we are at the console and config.rawkeyboard=on.

6.1.4. move_keynum

This does all the work of sending a key event to DOS. Either pressing a key releasing one. The key to move is the key specified by keynum.

keynum - the keynum from keynum.h indicating a physical key make - TRUE for key press, FALSE for release

Applications using int16h will always see the appropriate ASCII code for the given keyboard key and the current keyboard state. All the chracter translation is done for you to keep from reporting inconsistent key events.

An emulated hardware scancode is also sent to port60h.

Note that you have to send both MAKE (press) and BREAK (release) events. If no BREAK codes are available (e.g. terminal mode), send them immediately after the MAKE codes.

6.1.5. keysym_to_keynum

Allows peeking into the keytables. This returns the keynum a given keysym sits on.

6.1.6. move_key

This does all the work of sending a key event to DOS. Either pressing a key releasing one. The key to move is the key that is labeled with the specified keysym.

key - the keysym, one of the KEY_ constants from new-kbd.h make - TRUE for key press, FALSE for release

Applications using int16h will always see the appropriate ASCII code for the given keyboard key and the current keyboard state. All the chracter translation is done for you to keep from reporting inconsistent key events.

An emulated hardware scancode is also sent to port60h.

Note that you have to send both MAKE (press) and BREAK (release) events. If no BREAK codes are available (e.g. terminal mode), send them immediately after the MAKE codes.

6.1.7. put_symbol

This does all the work of sending a key event to DOS. sym -- The unicode value of the symbol you want to send

Applications using int16h will always see the symbol passed here, if it is representable in the current dos character set. The appropriate scancodes are generated automatically to keep the keyboard code consistent.

An emulated hardware scancode is also sent to port60h.

Note that you have to send both MAKE (press) and BREAK (release) events. If no BREAK codes are available (e.g. terminal mode), send them immediately after the MAKE codes.

6.1.8. put_modified_symbol

This does all the work of sending a key event to DOS. sym -- The unicode value of the symbol you want to send modifiers -- modifiers like alt etc you what to change your symbol with.

This function is a concession to the reality, in which key events are a composed of active modifiers, and a key label.

This function behaves as put_symbol does, except before pressing the key it adds the specified modifiers to the modifiers it would normally use.

For cases where the symbol can only be created by an alt# combination or by pressing a dead key (Basically any case where more than one key is requried, after setting the shiftstate) it gives up and just sends the symbol.

Note that you have to send both MAKE (press) and BREAK (release) events. If no BREAK codes are available (e.g. terminal mode), send them immediately after the MAKE codes.

6.1.9. get_shiftstate

This simply reads the keyboard server's shift state.

This is intended to be used in conjunction with set_shiftstate to sync up a shiftstate with a source of key events.

With the addition of this function the keyboard inteface is clean enough so if needed a completly different translation engine can be dropped in to support a totally different environment (windows or whatever).

6.1.10. set_shiftstate

This simply sets the keyboard server's shift state.

If there are shiftstate bits you want to keep fixed simply grab them with get_shiftstate, before calling this function.

This changes the keyboard flags by generating the appropriate shift key make/break codes that normally come along with such changes. So this function should be safe in any context.

Note also that you can't simply write to the shiftstate variable instead of using this function.

6.2. Functions in plugin/kbd_unicode/keyb_clients.c

These are the functions defined in plugin/kbd_unicode/keyb_clients.c.

6.2.1. keyb_client_init

Figures out which keyboard client to use and initialises it.

First it calls the probe method to see if it should use the client, Then it call init to set that client up.

If probe or init fails it trys another client.

Eventually falling back to Keyboard_none a dummy client, which does nothing.

6.3. Functions in plugin/kbd_unicode/keyb_none.c

These are the functions defined in plugin/kbd_unicode/keyb_none.c.

6.3.1. none_probe

Succeed if we can run the dummy keyboard client, (we always can).

6.4. Functions in plugin/kbd_unicode/keyb_raw.c

These are the functions defined in plugin/kbd_unicode/keyb_raw.c.

6.4.1. raw_keyboard_init

Initialize the keyboard for RAW mode.

6.4.2. raw_keyboard_reset

Reset the keyboard shiftstate to match the keyboard LED's

6.5. Functions in plugin/term/keyb_slang.c

These are the functions defined in plugin/term/keyb_slang.c.

6.5.1. setup_pc_scancode_mode

Initialize the keyboard in pc scancode mode. This functionality is ideal but rarely supported on a terminal.

6.5.2. exit_pc_scancode_mode

Set the terminal back to a keyboard mode other programs can understand.

6.5.3. do_pc_scancode_getkeys

Set the terminal back to a keyboard mode other programs can understand.

6.5.4. slang_keyb_init()

Code is called at start up to set up the terminal line for non-raw mode.

6.5.5. slang_keyb_probe()

Code is called at start up to see if we can use the slang keyboard.