x3270/Keymap

From The x3270 Wiki

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...]<Event>event-name: Action([arg[,...]])...
:
Indicates that only the specified modifiers can 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
Action
A x3270 action and its arguments.

Multiple-action entries

An entry can execute multiple actions. For example:

Ctrl<Key>x: 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 \
 Meta<Key>f: Toggle(rightToLeftMode)\n\
 Alt<Key>f:  Toggle(rightToLeftMode)\n\
 Meta<Key>v: Toggle(reverseInputMode)\n\
 Alt<Key>v:  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 Shift<Key>Backspace before the rule for <Key>BackSpace. This is because an event for BackSpace with Shift pressed will match either rule. So if you put your <Key>BackSpace rule first, the event will match it, and never see the more-specific rule after it.

Correct order:

Shift<Key>BackSpace: BackSpace()\n\
<Key>BackSpace: DeleteWord()\n\

Incorrect order (second will never fire):

<Key>BackSpace: DeleteWord()\n\
Shift<Key>BackSpace: 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:

x3270 will create a trace file called /tmp/x3trc.pid. In that file, several lines of text will be generated for each key you press. For example:

20201002.224905.731 Event ':<KeyPress>F1' via base:56 -> PF("1")

In this trace, the key generated the input event <KeyPress>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, /tmp/x3trc.pid. 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.