Configuration Guide


Chapter 6 . Key Translation File

A Panther application must allow users to enter ASCII data characters and to indicate certain logical key values to Panther—EXIT, XMIT, PF1, SPF1, and so on. Because physical keyboards vary from system to system, Panther uses a key translation file to translate sequences that users enter on their physical keyboards into logical keys that Panther understands.

The Panther distribution provides key translation files (in the config directory), that support more than 100 terminal types. One of the distributed key files should work for you. However, you might want to create, modify, or examine the key translation file if you:

This chapter describes:


The Role of the Key Translation File

During initialization, Panther reads the key translation file specified by SMKEY (in the smvars file) into memory. The value for SMKEY is determined by the terminal type indicated in your SMTERM or system TERM variable. Refer to Chapter 2, "Application Variables," for more information about setting the SMKEY variable. Now Panther can recognize how your physical keys map to the logical keys.

Panther logical keys are defined as hexadecimal values in the include file smkeys.h. This file is terminal-independent, while key translation files are terminal-dependent. ibmkeys, vt220keys, wy75keys are a few of the available key translation files.

For the most part, ASCII data key, logical values between 1 and hex FF, require no translation and are not included in the key translation file. However, some keyboards do not have the same number of function keys, and most do not have logical keys named HELP or XMIT (Transmit). Therefore, the key translation file specifies a physical key which transmits a unique code or sequence of codes which, in turn, works as a HELP key. Another key works as the XMIT key, and so on. Logical values between hex 100 and hex 1FF are cursor control and editing keys; values greater than hex 1FF are function keys.

So, when you press a key, the keyboard generates either a single ASCII data character, or a sequence of characters beginning with an ASCII control code. Panther converts these characters into logical keys, numbered between 1 and 65535 inclusively, before processing them—hence determining if a data character or control character was received.

If the key input is a control character, Panther searches the key translation file for a sequence beginning with that character. If there is a match, additional characters are read until the entire sequence is found, and returns the logical value. So, Panther is able to interpret XMIT when you press a Do key, or an End key, or whatever physical key is mapped to XMIT in your key translation file.

If a match is found on the initial character, but not the whole sequence, the entire sequence is discarded. If there is no match at all with the entered control character, it is returned unchanged; this is useful for machines such as IBM PCs that use control codes for displayable characters. (For more information about key translation, refer to "Processing Keyboard Input" in Upgrade Guide.)

With a one-to-one mapping there are not enough keys on a commercially available keyboard to represent the entire Panther logical keyboard—and for your application, you may not need to use or map all the logical keys. However, to accommodate its larger logical keyboard, Panther combines two or more physical keys to represent a logical key. For example, on a PC the logical key ZOOM is often mapped to Alt-Z.

Learn Your Key Mapping

You can print out the ASCII key translation file that supports your keyboard. Key translation file names begin with a mnemonic for the type of terminal you are using, and end with keys. For example, vt100keys is the key translation file for a VT100 terminal. All key translation files distributed with Panther adhere to this convention.

If you use Panther on different terminals with varying operating systems and keyboards, then each terminal must have its own key translation file. If necessary, you can create more than one key translation file for a terminal. In this way you can tailor the key mapping for a particular application.

Refer to "Processing Keyboard Input" in Upgrade Guide for a discussion of key processing in Panther applications.


Viewing Key Sequences

As an aid to editing key files, the showkey utility is provided. The showkey utility prints out the key sequence of keys that you enter. To run this utility, type showkey at a system prompt. (This is a Panther executable, and as such, the variables SMVARS and SMBASE must be appropriately defined to run this utility.) The showkey window appears:

In order to assure that you are not mistyping your keystrokes, showkey expects you to enter your keystrokes twice. If you do not press the same key sequence twice, it will not display the generated characters. Type x twice in a monospace font to exit the showkey utility.

If you want to bind the keystroke(s) to a Panther logical key, copy the decoded keystroke text to your key translation file. For example if you wanted to assign Shift-F10 on your keyboard to the logical key which starts the debugger, you would:

  1. Start the showkey utility.
  2. Enter Shift-F10 twice.

The showkey window displays the character sequence that the keystroke transmits. On one platform, the sequence for Shift-F10 was ESC [ 4 5 ~

  1. Bind the key label and character sequence to the debugger hot key:
    DBUG(Shift-F10)= Esc [ 4 5 ~
  2. Run the key2bin utility on your altered key file.
  3. Type xx to exit the utility.

Key Translation File Syntax

Each entry in a key translation file has the format:

logical-key(key-label) = character-sequence

Lines beginning with a pound sign # are treated as comments. They are ignored by the key2bin utility.

logical-key
The mnemonic or the hexadecimal value of a Panther logical key. For example, the logical TRANSMIT key is represented by the mnemonic XMIT or by the hex value 0x104. The mnemonics and hex values for all logical keys are defined in smkeys.h. Refer to Table 6-1 for a list of these mnemonics and values.

You can assign the same logical-key to two (or more) different character-sequences. For example, in a key translation file for the PC, you can make these entries:

HELP(Ctrl-F1) = NUL ^
HELP(Ctrl-Home) = NUL w

When these entries are used with a PC, both Ctrl-F1 and Ctrl-Home will execute HELP.

key-label
The letter, numeral, character, or character string engraved on a physical keytop. One or more physical key labels may be included inside the parentheses, for example (Alt-F1). key-label is optional. It can be accessed at runtime through various library functions and the %K escape in status line messages. (Refer to sm_d_msg_line.) Key labels are often helpful in user messages and prompts. If key-label is not specified, the logical key value is used in screen displays.

character-sequence
The sequence of characters, up to six characters not including blanks, produced by a keystroke. Panther translates character-sequence to be the logical key on the left of the equal sign.

When a physical key is pressed, it transmits a character code which is unique from the code produced by any other key on the keyboard. Each complete character sequence has only one logical value. Although a sequence may include another as a substring.

In character-mode, if you use key sequences that are lead-ins of other sequences, you must assign a timing interval with the video file entry keyword KBD_DELAY. For example, if you have defined one logical value to ESC, another to ESC [ F and have set KBD_DELAY to 5, Panther will wait a half of a second after ESC is pressed to resolve the ambiguity. If during that interval [ F is not received (or any other identifiable sequence that is prefixed with ESC) Panther passes on the logical value of ESC. For more information on keyboard delay, refer to "KBD_DELAY."

Example

The following example is an excerpt from a key translation file:

EXIT (F1) = SOH @ CR
XMIT (Enter) = SOH O CR
TAB = HT
BACK = NUL SI
BKSP = BS
# These are the arrow keys
RARR = ESC [ C
LARR = ESC [ D
UARR = ESC [ A
DARR = ESC [ B
# The next entry uses a hex value rather
# than a mnemonic for logical-key
0x108 = DEL

Key Mnemonics and Hexadecimal Values

Table 6-1is derived from the include file smkeys.h which defines the Panther logical keyboard. Some entries are required by the editor and are indicated with double asterisks (**).

Table 6-1 Panther Logical Keyboard—key mnemonics and hexadecimal values

Logical key mnemonic Hex value Description

CLWIN

0x100

close the current window

SYSMN

0x101

access system menu on active screen/window

CLAPP

0x102

close the application

EXIT

0x103

exit**

XMIT

0x104

transmit**

HELP

0x105

help on field*

FHLP

0x106

help on screen or form

CSHLP

0x107

context help when widget is clicked in Help Mode

BKSP

0x108

backspace*

TAB

0x109

tab*

NL

0x10a

newline*

BACK

0x10b

backtab*

HOME

0x10c

go to first field on screen*

NCARD

0x10d

next tab card

DELE

0x10e

delete character*

INS

0x10f

insert/overwrite character toggle*

LP

0x110

local print (SMLPRINT)

FERA

0x111

clear field*

CLR

0x112

clear all unprotected*

SPGU

0x113

display next page of data (scroll down)

SPGD

0x114

display previous page of data (scroll up)

PCARD

0x115

previous tab card

LSHF

0x116

left shift

RSHF

0x117

right shift

LARR

0x118

left arrow*

RARR

0x119

right arrow*

DARR

0x11a

down arrow*

UARR

0x11b

up arrow*

LWRD

0x11c

left to previous word

RWRD

0x11d

right to next word

REFR

0x11e

refresh screen*

EMOH

0x11f

go to last field on screen

INSL

0x120

insert line*

DELL

0x121

delete line*

ZOOM

0x122

zoom on field*

SFTS

0x123

soft key select

MTGL

0x124

toggle menu mode

VWPT

0x125

viewport

MOUS

0x126

indicate mouse event

MNBR

0x127

access menu bar

CYCL

0x128

cycle through a set of sibling windows

DBUG

0x129

hot key for debugger

WMODE***

0x12a

toggle control code display

WTAB***

0x12b

hard tab

WNL***

0x12c

hard new line

ITSEL

0x12d

item selection screen key

BOLN

0x12e

beginning of line (widget)

EOLN

0x12f

end of line (widget)

MDBL

0x131

mouse double click

OPTDN

0x132

option menu drop down key

BOFD

0x133

beginning of entry field

EOFD

0x134

end of entry field

ADDM

0x135

add mode toggle in list box

EXT

0x136

extend selection to select contiguous list items

EXTD

0x137

extend selection with down arrow in text field or list box

EXTU

0x138

extend selection with up arrow in text field or list box

EXTL

0x139

extend selection with left arrow in text field

EXTR

0x13A

extend selection with right arrow in text field

EXTWL

0x13B

extend selection one word left in text field

EXTWR

0x13C

extend selection one word right in text field

EXTLB

0x13D

extend selection to start of line in text field

EXTLE

0x13E

extend selection to end of line in text field

EXTPU

0x13F

extend selection up one page in text field or list box

EXTPD

0x140

extend selection down one page in text field or list box

EXTFB

0x141

extend selection to start of field or list box

EXTFE

0x142

extend selection to end of field or list box

SLWRD

0x143

select current word

SLALL

0x144

select entire text field

ALSYS

0x83D

access and open system menu

* Recommended entries. **Entries required by prodev. ***Used in wordwrap fields.

Note: The documentation on error messages and error acknowledgment often refers to an error acknowledgment key whose default is the space bar. Because the space bar is a data entry key, it cannot be used as a logical key. Instead, the key is defined as the application behavior variable ER_ACK_KEY. You can change the entry in the SMVARS file, in a setup file, in the system environment, or at runtime with the library function sm_option.

Table 6-2 includes the mnemonics and hexadecimal values for function keys (PF), shifted function keys (SPF), and ALT keys. Table 6-3 includes the mnemonics and hexadecimal values for application function keys (APP).

Table 6-2 Hexadecimal values for function and ALT keys

PF Hex SPF Hex ALT Hex

PF1

0x6101

SPF1*

0x4101

ALTA

0x4103

PF2*

0x6201

SPF2*

0x4201

ALTB

0x4203

PF3*

0x6301

SPF3*

0x4301

ALTC

0x4303

PF4*

0x6401

SPF4*

0x4401

ALTD

0x4403

PF5*

0x6501

SPF5*

0x4501

ALTE

0x4503

PF6*

0x6601

SPF6*

0x4601

ALTF

0x4603

PF7*

0x6701

SPF7

0x4701

ALTG

0x4703

PF8*

0x6801

SPF8

0x4801

ALTH

0x4803

PF9*

0x6901

SPF9

0x4901

ALTI

0x4903

PF10*

0x6a01

SPF10

0x4a01

ALTJ

0x4a03

PF11

0x6b01

SPF11

0x4b01

ALTK

0x4b03

PF12

0x6c01

SPF12

0x4c01

ALTL

0x4c03

PF13

0x6d01

SPF13

0x4d01

ALTM

0x4d03

PF14

0x6e01

SPF14

0x4e01

ALTN

0x4e03

PF15

0x6f01

SPF15

0x4f01

ALTO

0x4f03

PF16

0x7001

SPF16

0x5001

ALTP

0x5003

PF17

0x7101

SPF17

0x5101

ALTQ

0x5103

PF18

0x7201

SPF18

0x5201

ALTR

0x5203

PF19

0x7301

SPF19

0x5301

ALTS

0x5303

PF20

0x7401

SPF20

0x5401

ALTT

0x5403

PF21

0x7501

SPF21

0x5501

ALTU

0x5503

PF22

0x7601

SPF22

0x5601

ALTV

0x5603

PF23

0x7701

SPF23

0x5701

ALTW

0x5703

PF24

0x7801

SPF24

0x5801

ALTX

0x5803

ALTY

0x5903

ALTZ

0x5a03

*Recommended entries.

Table 6-3 Hexadecimal values for application function keys

APP Hex APP Hex

APP0

0x6002

APP32

0x4002

APP1

0x6102

APP33

0x4102

APP2

0x6202

APP34

0x4202

APP3

0x6302

APP35

0x4302

APP4

0x6402

APP36

0x4402

APP5

0x6502

APP37

0x4502

APP6

0x6602

APP38

0x4602

APP7

0x6702

APP39

0x4702

APP8

0x6802

APP40

0x4802

APP9

0x6902

APP41

0x4902

APP10

0x6a02

APP42

0x4a02

APP11

0x6b02

APP43

0x4b02

APP12

0x6c02

APP44

0x4c02

APP13

0x6d02

APP45

0x4d02

APP14

0x6de2

APP46

0x4e02

APP15

0x6f02

APP47

0x4f02

APP16

0x7002

APP48

0x5002

APP17

0x7102

APP49

0x5102

APP18

0x7202

APP50

0x5202

APP19

0x7302

APP51

0x5302

APP20

0x7402

APP52

0x5402

APP21

0x7502

APP53

0x5502

APP22

0x7602

APP54

0x5602

APP23

0x7702

APP55

0x5702

APP24

0x7802

APP56

0x5802

APP25

0x7902

APP57

0x5902

APP26

0x7a02

APP58

0x5a02

APP27

0x7b02

APP59

0x5b02

APP28

0x7c02

APP60

0x5c02

APP29

0x7d02

APP61

0x5d02

APP30

0x7e02

APP62

0x5e02

APP31

0x7f02

APP63

0x5f02

ASCII Character Mnemonics and Hex Values

Table 6-4 lists two- and three-letter ASCII mnemonics for control and extended control characters. It is derived from the include file smascii.h.

Table 6-4 ASCII character mnemonics and hexadecimal values

Mnemonic Hex Mnemonic Hex Mnemonic Hex Mnemonic Hex

NUL

0x00

DLE

0x10

DCS

0x90

SOH

0x01

DC1

0x11

PU1

0x91

STX

0x02

DC2

0x12

PU2

0x92

ETX

0x03

DC3

0x13

STS

0x93

EOT

0x04

DC4

0x14

IND

0x84

CCH

0x94

ENQ

0x05

NAK

0x15

NEL

0x85

MW

0x95

ACK

0x06

SYN

0x16

SSA

0x86

SPA

0x96

BEL

0x07

ETB

0x17

ESA

0x87

EPA

0x97

BS

0x08

CAN

0x18

HTS

0x88

HT

0x09

EM

0x19

HTJ

0x89

LF

0x0a

SUB

0x1a

VTS

0x8a

VT

0x0b

ESC

0x1b

PLD

0x8b

CSI

0x9b

FF

0x0c

FS

0x1c

PLU

0x8c

ST

0x9c

CR

0x0d

GS

0x1d

RI

0x8d

OCS

0x9d

SO

0x0e

RS

0x1e

SS2

0x8e

PM

0x9e

SI

0x0f

US

0x1f

SS3

0x8f

APC

0x9f

SP

0x20

DEL

0x7f


Creating and Modifying a Key Translation File

To create or modify a key translation file:
  1. Access the desired ASCII key translation file (or create a new one) using a text editor.
  2. Edit the ASCII key translation file as required.
  3. Use key2bin to convert the ASCII file to binary format.
  4. If this is a new key translation file, include the path name of the binary file as the value of the SMKEY configuration variable. (The default value for SMKEY is set in the file pointed to by SMVARS. Refer to Chapter 2, "Application Variables," for information on changing configuration variables in setup files.)

Customizing Key Mapping

You can change the mappings of logical keys for the preferences of users or developers by:

Example: Changing the Key Translation File

In the distributed key translation files for the PC, XMIT is mapped to the physical End key, and NL is mapped to the Enter key. The key translation file entries look like this:

XMIT(End) = NUL O
NL(Enter) = CR

NUL O is the character-sequence transmitted by the PC's End key; when

Panther receives this sequence, it carries out its XMIT function. Similarly, CR is transmitted by the PC's Enter key and Panther responds appropriately.

To use the Enter key for XMIT and the End key for NL, you can change the key translation file entries to read:

XMIT(Enter) = CR
NL(End) = NUL O

Using Alternate Key Translation Files

Many applications support more than one type of keyboard. With Panther you can provide this support without recompiling the application for each keyboard. Each terminal must have a working key translation file and video file (for character-mode only). List the path names for the key translation and video files in your application's SMVARS file. Assuming the SMTERM variable is set correctly, Panther selects the correct key translation file from the SMVARS file during initialization.

For example, the following excerpt is from the SMVARS file:

SMKEY = (hp|hp2392) $SMBASE/config/hpkeys.bin
SMKEY = (xterm) $SMBASE/config/xtermkeys.bin