There is also a default handler for keyboard input, that handles input of text characters.
The keymap resource or the -keymap commad-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.
wc3270 also supports mode-specific keymaps.
By default, a keymap applies no matter what mode wc3270 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 wc3270 is in 3270 mode. Similarly, if there is a keymap definition for foo.nvt, it will apply only when wc3270 is in NVT mode.
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 in effect will be removed.
Where wc3270 finds keymap definitions
wc3270 finds keymap definitions in three places, which it searches in order:
wc3270 includes a compiled-in definition for the default keymap, called base.
If there is no compiled-in definition for a keymap, wc3270 will look for a resource definition. The resource containing the definition of the keymap named foo is keymap.foo.
Resources are defined in two places:
If there is no compiled-in definition and no resource definition, wc3270 will look for the keymap named foo in the file named foo.wc3270km. It will look for this file first in the current user's Documents\wc3270 folder, then in the common Documents\wc3270 folder, and then in the current directory.
Rules for keymap definitions
Keymaps in resources
If a keymap is defined in a resource, it must be defined as a multi-line resource. For example:
wc3270.keymap.foo: \ Ctrl<Key>q: PrintText()\n\ Ctrl<Key>w: NextWord()\n\ Ctrl<Key>x: Disconnect()
Note that the first line ends with a
\. The "middle" lines end with the sequence
\n\, and the last line has no special ending.
Keymaps in files
When a keymap is defined in a file, none of the special line endings are needed. In a file, the above example would be:
Ctrl<Key>q: PrintText() Ctrl<Key>w: NextWord() Ctrl<Key>x: Disconnect()
The format of a keymap entry is:
[modifier...]<Key>keyname: Action([arg[,...]]) ... [modifier...]<Key>keyname [modifier...]<Key>keyname: Action([arg[,...]]) ...
- Zero or more keyboard modifiers:
|Ctrl||Either of the Ctrl modifier keys|
|LeftCtrl||The left Ctrl modifier key|
|RightCtrl||The right Ctrl modifier key|
|Alt||Either of the Alt modifier keys|
|LeftAlt||The left Alt modifier key|
|RightAlt||The right Alt modifier key|
|Shift||The Shift key|
|Enhanced||The Windows enhanced modifier (explained below)|
- A literal character such as a
- A Windows VKEY name (without the VK_ prefix) such as NUMPAD5 (the 5 key on the numeric keypad) or NEXT (the Page Down key) -- note that not all VKEYs are supported by wc3270
- An ISO 8859-1 symbolic name for a key, such as colon (the : key)
- A Unicode code point, e.g., U+0041 for A
- A wc3270 action and its arguments.
An entry that uses the Ctrl modifier is not case sensitive. For example, the following two keymap entries are the same:
Ctrl<Key>x: String("foo") Ctrl<Key>X: String("foo")
All other entries (those without any modifiers, and those using modifiers other than Ctrl) are case-sensitive. So the following entry would match x pressed with the Alt key, but not X pressed with the Alt key:
An entry can match a sequence of keys. For example:
Ctrl<Key>a <Key>r: Reset()
This entry matches the Ctrl-a key, followed by the r key.
Left and Right modifier keys
An entry that matches on a Left or Right modifier (LeftAlt, LeftCtrl, RightAlt, RightCtrl) takes precedence over an entry with an unqualified modifier (Alt, Ctrl).
An entry can execute multiple actions. For example:
Ctrl<Key>x: String("hello") Newline()
If for some reason the same match appears in more than one entry, the first one will be used. This will be indicated in the output of Show(Keymap) with the unused entry(ies) replaced by the text superceded by xxx.
The Enhanced modifier
Syntactically, the Enhanced modifier looks like a modifier key, but it is actually an extra attribute that Windows includes with certain keys. For example, the Enter key on the main keyboard is reported as the VKEY RETURN, but the Enter key on the numeric keypad is reported as the VKEY RETURN with the Enhanced modifier. To define separate actions for the two Enter keys, you could define a keymap like this:
Enhanced<Key>RETURN: Enter() <Key>RETURN: Newline()
Note that Enhanced is not a synonym for "keypad". For example, the VKEY for the 1 key on the keypad is NUMPAD1. So trying to match on Enhanced<Key>1 will not work.
The RightCtrl Key
A common keymap question is how to create an entry that matches the right-side Ctrl key itself, as opposed to using RightCtrl as a modifier. Here is the trick:
How to figure out what keys 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 wc3270 with the -trace command-line option.
- Connect to a host.
- Press the key(s) in question.
- Exit wc3270.
wc3270 will create a trace file called
/tmp/x3trc.pid.txt on your desktop.
In that file, several lines of text will be generated for each key you press. For example:
20200926.232517.915 KeyDown vkey 0x70 (F1) scan 0x3b char U+0000 state 0x0 (none) 20200926.232517.915 [xk 0x700000] <Key>F1 ->lookup_key(0x00700000, 0x0) 20200926.232517.915 CB(default)[#3] started 20200926.232517.915 CB(default)[#3.1] IDLE -> RUNNING (child task to be pushed next) 20200926.232517.915 Macro[#3.2] IDLE -> RUNNING (fresh push) 20200926.232517.915 lazya_flush: 11 slots 20200926.232517.915 Macro[#3.2] RUNNING -> IDLE (about to resume) 20200926.232517.915 Macro[#3.2] running 20200926.232517.915 Macro[#3.2] IDLE -> RUNNING (executing) 20200926.232517.915 Macro[#3.2] 'PF(1)' 20200926.232517.915 default -> PF("1")
In this trace, the key generated the input event <Key>F1, which you can paste directly into your keymap definition.
There are two wc3270 options to aid with keymap debugging.
The -trace command-line option causes wc3270 to create a
/tmp/x3trc.pid.txt on your desktop.
That file traces (among other things) each keyboard event that wc3270 processes.
The information traced includes the keymap (and line within the keymap)
that matched the event, and the wc3270 actions that were run in response.
The Show(Keymap) action at the wc3270> prompt displays the current keymap. This tells you exactly which keymap entries are active. Often times it will point out that wc3270 isn't using the keymap you thought it was, or that some of your keymap entries are interfering with one another.