[Top] [Prev] [Next] [Contents] [Index]

Using Downloadable Keyboard Description Files

NCDware provides a mechanism for experienced system administrators to configure terminals to work with keyboards that are not explicitly supported in the NCD X server, such as some international keyboards.

This appendix describes how to use a keyboard description file downloaded from the host during terminal booting to support such keyboard usage. Keyboard description files may be available from the NCD FTP site or from other vendors.

To use an unsupported keyboard, you need to:

  1. Find or prepare a keyboard description file describing the behavior of the keyboard. See the content and format descriptions later in this appendix. Make sure that the file is world-readable.

  2. Make sure that the directory containing the keyboard description file is accessible through the file-service-table parameter (Setup -> Change Setup Parameters -> File Service -> File Service Table). For information about this parameter, see Chapter 5, Configuring Network Services.

  3. Configure the terminal to read the keyboard description file during booting. In a remote configuration file, set the xserver-keyboard-description-file parameter to the name of the keyboard definition file (Setup -> Change Setup Parameters -> Input Devices -> Keyboard Description File).

  4. Plug in the keyboard.

  5. Reboot the terminal. The first time you boot the terminal after using a new keyboard description file, check the Messages hide box in the Console to make sure that the file was read without error.

Creating a Keyboard Definition File

This section describes how to manually create or edit a keyboard description file.

You can also create a keyboard description file for the keyboard attached to the terminal from Change Setup Parameters. In the Input hide box, click on Write Keyboard Description File. In the dialog box that appears, type the pathname of the file and click on OK.

A keyboard description file is an ASCII file containing statements defining keyboard behavior. The statements describe the following keyboard characteristics:

Scancode table Used by the keyboard driver to map hardware scancodes of range [0..255] into X keycodes of range [8..254]. Also used to make one keyboard imitate another.
Keycode table Used by applications to convert X keycodes into keysyms. Also used by the X server when internal dead-key processing is enabled. Keycodes are the codes assigned to the physical keys. Keysyms are the actions taken when keys are pressed. Dead-keys are keys pressed before other key presses (such as an accent and a vowel) to produce an accented vowel letter, as required in many European languages.
Dead-key sequences Sequences of keys intercepted by the keyboard driver and replaced by another key.
Modifiers table Keys that are treated as modifiers, such as Shift, Lock, Control, Mod1-5. Typical values are:
Shift Shift_L Shift_R
Lock Caps_Lock Control_R
Control Control_L
The following values vary depending on the keyboard:
Mod1 Alt_L Alt_R Meta_L Meta_R
Mod4 Num_Lock
Mod5 Mode_switch
Clicking list Keys that click through the base speaker when pressed.
Locking list Keys that lock when pressed, requiring a second press to release, usually used with modifier keys. By default, all keysyms containing the name "lock" are locking keys.
Latching list Keys that are treated as locking until the next key is released, usually used with modifier keys. By default, the Mode_switch keysym latches.
Repeating list Keys that autorepeat.
LED actions table Maps LED number to the state that causes that LED to light.

The format of a keyboard definition file is similar to an xmodmap file:

Table 17-8 summarizes the statements permitted in a keyboard definition file. A statement consists of one or more keywords and values. The values permitted in the statements are defined in Table 17-9.

Table 17-8 Keyboard Description File Statements
Statement (Keyword/Value)
name QUOTEDSTRING Specifies the name of the keyboard; typically, the first line in the file.
include QUOTEDSTRING Reads in other files needed to assemble a keyboard description from other files such as deadkeys.kbd or a personal keyboard file such as my.kbd.
initialize Sets keyboard state tables to known values:
scancode SCANCODE = KEYCODE scancode LISTofSCANCODE = LISTofKEYCODE Sets values in the scancode-to-keycode table used by the keyboard driver. By default, scancodes are used as keycode values. Individual scancodes can be replaced by individual values. Destination keycodes must be in the range 8 to 254 for X operations. LISTofSCANCODE and LISTofKEYCODE must be separated by blanks and must be equal in length and represent a one-to-one correspondence of scancode to keycode. Scancodes are in a range of 0 to 255.
keycode KEYCODE = LISTofKEYSYM Sets a row in the keycode-to-keysym table that X applications use to convert keycodes into keysyms. The list of keysyms can contain 0, 1, 2, 3, or 4 keysyms. Keycodes must be in a range of 8 to 254.
keysym KEYSYM = LISTofKEYSYM Changes an existing keyboard configuration by replacing a keysym that is currently bound to a keycode with one or more new keysyms. It is usually placed at the end of the keyboard definition file.
deadkey KEYSYM LISTofKEYSYM = KEYSYM Specifies a sequence of keys to press to generate another key when local dead-key processing is enabled. For more information about this statement, see "Specifying Dead-Key Processing".
modifier MODIFIER = LISTofKEYSYM modifier add MODIFIER = LISTofKEYSYM Specifies the list of keys associated with an X modifier. All of the keycodes containing any of the keysyms are set, added to, or removed from the indicated modifier list. The modifier list is actually constructed at the end of all keyboard file processing so that it can use the final keysym table values.
modifier remove MODIFIER = LISTofKEYSYM Removes a key from the modifier list.
modifier clear MODIFIER Clears the existing list.
click = LISTofKEYSYM Specifies keys that should click when pressed and clears any already existing list of clickable keys.
click add = LISTofKEYSYM Specifies additional keys that should click without clearing the click list.
click remove = LISTofKEYSYM Removes a key from the click list.
click clear Clears the existing list.
lock = LISTofKEYSYM Specifies keysyms that should ignore release events, requiring a second press for release. By default, all keys with keysyms with the word "lock" are locking.
lock add = LISTofKEYSYM Specifies additional keys that should lock without clearing the lock list.
lock remove = LISTofKEYSYM Removes a key from the lock list.
latch = LISTofKEYSYM Specifies keysyms that are treated as latching, with a release that is delayed until the next key is released. By default, the Mode_switch key is latched.
latch add = LISTofKEYSYM Specifies additional keys that should latch without clearing the latch list.
latch remove = LISTofKEYSYM Removes a key from the latch list.
repeat = LISTofKEYSYM Specifies keys that should repeat automatically when pressed.
repeat add = LISTofKEYSYM Specifies additional keys that should repeat without clearing the repeat list.
repeat remove = LISTofKEYSYM Removes a key from the repeat list.
led NUMBER = LED ACTION Specifies when keyboard LEDs should light up. NUMBER is the LED number (1, 2, 3, or 4) and LED ACTION is one of the following:
"x1" "x2" "x3" "x4"
"control" "num" "warn" "net"
"shift" "caps" "mod1" "mod2"
"mod3" "mod4" "mod5"
led map NUMBER = NUMBER Changes the mapping of the LEDs for keyboards in which the LEDS are not in sequential number.
led invert NUMBER Reverses the sense of the LED for keyboards with inverted LED sense.
led total NUMBER Sets the maximum number of LEDs that the keyboard supports.
led enable Enables the led commands if they have been disabled.
led disable Disables led commands to the keyboard.
setup = Setup key + modifiers Displays the NCDware Console. To disable this command, do not define a Setup key and modifiers (setup = ).
debug = Debug key + modifiers Aborts the X server, placing the terminal in the control of the Boot Monitor. To disable this command, do not define a debug key and modifiers (debug = ).

Table 17-9 Permitted Values in Keyboard Description Files
QUOTEDSTRING An ASCII string of characters within quotes ("")
NUMBER A positive integer
KEYSYM A string representing an X keysym name
LISTofKEYSYM Any of the following: KEYSYM
LISTofKEYSYM can also be an empty list.
MODIFIER Any of the following:
"shift" "mod2"
"control" "mod3"
"lock" "mod4"
"mod1" "mod5"

Specifying Dead-Key Processing

The following keyboard description file statement specifies a sequence of keys to press to generate another key when local dead-key processing is enabled:


The range of LISTofKEYSYM is 1, 2. The resulting keysym must have been defined before this command so that the resulting table can be correctly populated.

In this mode, the keyboard driver looks at each key press as it is entered, intercepting keysyms for sequences of keys that match those specified in the dead-key statement. The first keysym on the left of the equals sign (=) is usually either the keysym Multi_key (for Digital-style triple-key compose sequences) or one of the dead-accent keysyms listed in Table 17-10.

Table 17-10 Dead-Key Accent Keysyms
Old Digital Versions:
New X11R6 Standard Versions:
Dring_acent dead_abovering dead_macron
Dcircumflex_accent dead_circumflex dead_breve
Dcedilla_accent dead_cedilla dead_abovedot
Dacute_accent dead_acute dead_doubleacute
Dgrave_accent dead_grave dead_caron
Dtilde dead_tilde dead_ogonek
Ddieresis dead_dieresis dead_iota

The keysyms for accented vowels produced using dead-keys differ from those used when the accent is a standalone character (degree, asciicircum, cedilla, acute, grave, asciitilde, and dieresis).

When you type a dead keysym, the keyboard driver delays processing of the keyboard events until it either completes a dead-key sequence or encounters a non-modifier keysym that does not match a sequence containing the keys typed so far. If no match is found, the bell rings and the delayed keyboard events are processed separately. Otherwise, if a full sequence is recognized, the keyboard driver replaces the recognized sequence with events that generate the keysym specified on the right (except when the keysym isn't on the keyboard).

The Shift, Lock, and Mode_switch bits in the modifier mask of the replacement event are synthesized as necessary to obtain the desired keysym; all other bits in the modifier mask are the same as in the final event in the recognized sequence.

When conflicts arise over whether the keyboard driver should complete one sequence or continue to process for a longer superset, the driver completes the shorter set.

[Top] [Prev] [Next] [Contents] [Index]

Send comments, suggestions, or questions about this document to the NCD Technical Publications Department by Internet e-mail. Write to us at techpubs@ncd.com.
Copyright © 1997, NCD Inc. All rights reserved.