X3270/Keymap

A keymap is a mapping from keys and mouse events to actions. For example, pressing the F1 key on the keyboard may be mapped onto the action PF(1).

There is also a default handler for keyboard input (the Default action), that handles input of text characters.

The keymap resource or the -keymap command-line option specify the name of the keymap to use. Multiple names can also be specified, separated by commas. If there are any conflicts in the entries, the entries from keymaps later in the list replace those from earlier in the list.

If the keymap resource is not defined, the environment variables $KEYMAP and $KEYBD are checked, in that order, for the name.

Mode-specific keymaps
x3270 also supports mode-specific keymaps.

By default, a keymap applies no matter what mode x3270 is in. However, if the current keymap is named foo, and a keymap definition exists for the name foo.3270, then the mappings in foo.3270 will apply only when x3270 is in 3270 mode. Similarly, if there is a keymap definition for foo.nvt, it will apply only when x3270 is in NVT mode.

User keymaps
The string .user is then appended to the keymap name and three more keymaps are searched for: foo.user, foo.user.nvt and foo.user.3270. (The purpose of this is so an administrator can define system-wide definitions for a particular keymap, and individual users can modify and extend them without having to repeat the entire definition.)

Temporary keymaps
The Keymap action allows for a temporary keymap. When Keymap is invoked with a parameter, a keymap by that name will be applied, and its definitions will override any matching definitions in the current keymap. When Keymap is invoked without a parameter, any temporary keymap will be removed.

The intent of this feature is that a system administrator could define a common keymap foo, and then individual users could define their own extensions to keymap foo in their own X11 resource databases.

Where x3270 finds keymap definitions
x3270 finds keymap definitions in two places, which it searches in order:

Keymap files
x3270 first searches for a definition in a file. Keymap files live in the directory defined by the confDir resource. The keymap file for keymap foo would be named keymap.foo. These are ordinary X11 resource database files, e.g., the file keymap.foo would contain the definitions of keymap.foo and optionally, the definitions of keymap.foo.nvt and keymap.foo.3270.

Resources
If there is no keymap file for the keymap, x3270 gets the definition from resources. The resource containing the definition of the keymap named foo is keymap.foo.

User-defined resources
There are a large number of ways that resources for x3270 can be defined:
 * In your X11 server, set via the xrdb command.
 * In the file .Xdefaults in the user's home directory.
 * In the file .Xdefaults-hostname in the user's home directory.
 * The file .x3270pro in the user's home directory.
 * In an x3270 session file.
 * Through a command-line option (-set or -xrm).

Compiled-in keymap resource definitions
x3270 includes a compiled-in definitions for a number of keymaps.
 * base
 * The default keymap.


 * oldclick
 * The mouse-click behavior from release 3.2 and earlier.


 * righttoleft
 * Support for right-to-left languages.


 * sun_k5
 * The Sun Type 5 keyboard.


 * sun_k4
 * The Sun Type 4 keyboard.


 * sun_k3
 * The Sun Type 3 keyboard.


 * hp-k1
 * A particular HP keyboard.


 * hp-pc
 * The HP PC101 workstation keyboard.


 * ibm-xterm
 * The IBM X terminal keyboard.


 * rlx
 * Common 3270/PC mappings, courtesy of Richard Lennox.


 * ow
 * Keymap modifier for OpenWindows.


 * apl
 * APL keymap, automatically added when APL mode is set.


 * not
 * Keymap for the ¬ key, assumed to be above the 6 on a U.S. keyboard.


 * t
 * Helpful modifier to display the translation table with Alt-t.


 * finnish7
 * Modifier for Finnish keyboards.


 * norwegian7
 * Modifier for Norwegian keyboards.


 * oldnorwegian7
 * "Old" Norwegian keyboard modifier.


 * german7
 * Modifier for German keyboards.


 * fr6k
 * Keymap modifier for IBM RS/6000's with French AZERTY keyboards.


 * icelandic
 * Modifier for Icelandic keyboards.

Rules for keymap definitions
x3270 keymaps are Xt translation tables. What follows are some simple examples, but the actual possibilities are much more extensive.

Syntax
The format of a keymap entry is: [:|!][modifier...]&lt;Event>event-name: Action([arg[,...]])...
 * &#58;
 * Indicates that only the specified modifiers can be set.


 * Indicates that the specified modifiers cannot be set.
 * Indicates that the specified modifiers cannot be set.


 * modifier
 * Zero or more modifiers:


 * Ctrl: the Ctrl key.
 * Alt: the Alt key.
 * Meta: the Meta key.
 * Shift: the Shift key.
 * Super: the Super key.
 * Hyper: the Hyper key.
 * Modi: the modifier i key.
 * Buttoni: mouse button i.
 * Event
 * An event type, such as Key, KeyUp, KeyDown, Btn1Down, Btn1Up, Btn2Down, Motion, Enter, Leave, FocusIn, FocusOut, etc.


 * event-name
 * A literal character such as a
 * An ISO 8859-1 symbolic name for a key, such as colon (the : key)
 * An X11 keysym name
 * Action
 * A x3270 action and its arguments.

Multiple-action entries
An entry can execute multiple actions. For example: Ctrlx: String("hello") Newline This entry maps the key Ctrl-x to two actions, String followed by Newline.

Overall syntax
An x3270 keymap is a multi-line resource. This means that every line except the last must end with a backslash (\) to indicate a line continuation, and each entry must be separated by a newline (\n) sequence.

Here is a simple example: x3270.keymap.righttoleft: #override \ Metaf: Toggle(rightToLeftMode)\n\ Altf: Toggle(rightToLeftMode)\n\ Metav: Toggle(reverseInputMode)\n\ Altv: Toggle(reverseInputMode)

Ordering rules
In an x3270 keymap, more-specific definitions must come before less-specific definitions. This is because an event executes the actions for the first rule that it matches (and only for that rule).

For example, if you want to define different actions for the BackSpace key with and without the Shift key pressed, you must define the rule for ShiftBackspace before the rule for BackSpace. This is because an event for BackSpace with Shift pressed will match either rule. So if you put your BackSpace rule first, the event will match it, and never see the more-specific rule after it.

Correct order: ShiftBackSpace: BackSpace\n\ BackSpace: DeleteWord\n\ Incorrect order (second will never fire): BackSpace: DeleteWord\n\ ShiftBackSpace: BackSpace\n\

How to figure out what events are being generated
To find out which key name or sequence of key names is being generated for any given key on your keyboard:
 * Start x3270 with the -trace command-line option.
 * Connect to a host.
 * Press the key(s) in question.
 * Exit x3270.

x3270 will create a trace file called. In that file, several lines of text will be generated for each key you press. For example: 20201002.224905.731 Event ':F1' via base:56 -> PF("1")

In this trace, the key generated the input event F1, which you can paste directly into your keymap definition. It also tells you exactly which keymap entry it matched, if any.

Keymap debugging
There are two x3270 options to aid with keymap debugging. The -trace command-line option causes x3270 to create a trace file,. That file traces (among other things) each keyboard event that x3270 processes. The information traced includes the keymap (and line within the keymap) that matched the event, and the x3270 actions that were run in response.

The menu option Options -> Display Current Keymap displays the current keymap. This tells you exactly which keymap entries are active. Often times it will point out that x3270 isn't using the keymap you thought it was, or that some of your keymap entries are interfering with one another.