Customizing Key Definitions in UNIX Environments

Techniques for Customizing Your Key Definitions

There are four ways to customize your key definitions:

through the Keys window

To open the Keys window, issue the KEYS command or select ToolsOptionsKeys. If you change any key definitions through the Keys window for the primary SAS windowing environment windows, the definitions are stored in the Sasuser.Profile catalog in the entry DMKEYS.KEYS. Key definitions for other SAS windows are stored in catalog entries named BUILD.KEYS, FSEDIT.KEYS, and so on.

See the online SAS Help and Documentation for more information about the KEYS command and the Keys window.
with the KEYDEF command
The KEYDEF command enables you to redefine individual function keys:
```
keydef keyname <command|~text-string>
```
For example, if you specify keydef F8 dlgpref, then the F8 key will open the Preferences dialog box.

For more information about the KEYDEF command, see the Base SAS section in the online SAS Help and Documentation.
through the Resource Helper (reshelper)

Resource Helper generates SAS resource specifications based on keys and functions that you select. You can use Resource Helper to change the function of any key that is listed in the Keys window. For more information about the Resource Helper, see Setting X Resources with the Resource Helper and Defining Keys with the Resource Helper.

In most cases, Resource Helper is much easier and faster than defining the resources yourself. However, because the X Window System searches for resources in several places, it is possible for Resource Helper to pick up the wrong key symbol for the key you are trying to define. Also, unless the action routine that you assign to your keys is the sas-function-key routine, then Resource Helper does not provide a way to change the key labels in the Keys window. In both of these cases, you will need to define your key resources yourself.
by defining the SAS.keyboardTranslations and SAS.keysWindowLabels resources in your resources file as described in Defining Key Translations.

You can define most of the keys on your keyboard. However, a few keys have dedicated functions that are associated with them. For example, the mouse buttons are dedicated to the cursor and cut-and-paste operations and are not available for user customization.

Defining Key Translations

What Is a Key Translation?

Key customization for the X Window System consists of defining a key sequence and an action to be executed when that key sequence is typed on the keyboard. This customization is known as binding keys to actions; together they are referred to as a translation.

What Is the SAS.keyboardTranslations Resource?

The SAS.keyboardTranslations resource specifies the set of key bindings that SAS uses in all SAS windows. The default value for the SAS.keyboardTranslations resource is determined at run time based on the vendor identification string reported by the X server that you are using as the display. These defaults are listed in the files contained in !SASROOT/X11/resource_files. To modify the default bindings that are supplied by SAS, you must modify the SAS.keyboardTranslations resource.

Note: The X Toolkit Intrinsics translations that are specified in this resource apply to both the user area and the command line of all SAS windows that are affected by this resource. This resource does not affect windows that are controlled by Motif interface resources, such as the Command window, the Open or Import dialog boxes, and some other drop-down menu dialog boxes.

Steps for Creating a Key Definition

To create a key definition, follow these steps:

Determine the keysyms for the keys that you want to define.

Keysyms are the symbols that are recognized by the X Window System for each key on a keyboard. For more information, see Determining Keysyms.
Modify or add the SAS.keyboardTranslations resource in your resource file to include the definitions of the keys that you want to define.

Use a keyboard action routine to define which action you want the key to perform. The definition in the right column in the Keys window will no longer control the function of any keys that are defined with a keyboard action routine other than sas-function-key. The definitions of those keys in the Keys window become labels that have no effect. For more information, see Syntax of the SAS.keyboardTranslations Resource.
Modify or add the SAS.keysWindowLabels resource in your resource file.

The SAS.keysWindowLabels resource specifies the set of valid labels that will appear in the Keys window. Modify this resource only if you want to add new labels or modify existing labels in the left column in the Keys window.

The SAS.keysWindowLabels resource defines only the mnemonics used in the Keys window. For a specific key to perform an action, you must specify a SAS.keyboardTranslations definition for the key. For more information, see Syntax of the SAS.keysWindowLabels Resource.
Start a SAS session and open the Keys window.
In the right column in the Keys window, enter a command name or other description of each key that you have defined.

For examples of key definitions, see Examples: Defining Keys Using SAS Resources.

Determining Keysyms

You can use the xev utility to determine the keysyms that are associated with the keys on your keyboard. The xev utility is distributed with most UNIX operating systems, but if xev is not installed in your operating environment, contact your UNIX system administrator for information about other methods that are available in your UNIX environment. The xev utility writes a message for each X event that occurs. The KeyPress event specifies the keysym for each key that is pressed.

To define keys, follow these steps:

Start the xev utility on the X server for which you want to define keys.

The xev client displays a small Event Tester window that lists the X events that occur. (The xev client generates a large amount of output, so you might want to save the output to a file for later review. You can issue the UNIX script command to save the output to a file.)
Give keyboard focus to the Event Tester window by clicking the mouse pointer on the window, if necessary.
Press the key that you want to define, and watch for the KeyPress event to be listed.

The listing contains a number of items that are separated by commas. One of the fields in the KeyPress event lists the keysym name that is associated with the key that was pressed.
For example, when the 0 key on the keypad of a Dell PC 105 keyboard is pressed, with the NumLock modifier toggled on, it generates the following output:
```
KeyPress event, serial 32, synthetic NO,
  window 0x1a00001, root 0x5d, subw 0x1a00002,
  time 600120687, (37,41), root:(240,458),
  state 0x10, keycode 90 (keysym 0xffb0, KP_0),
  same_screen YES,
  XLookupString gives 1 bytes: (30) "0"
  XmbLookupString gives 1 bytes: (30) "0"
  XFilterEvent returns: False 
```
In this example, the keysym name is KP_0.

Note: SAS defines a set of virtual keysyms with the SAS.defaultVirtualBindings resource. Virtual keysyms all begin with osf, such as osfPageDown, osfClear, and osfPrimaryPaste. If you remap these virtual bindings instead of using the defaults supplied by SAS, you might get unexpected results. If you specify a key translation that does not work, you might be trying to redefine a key that is bound to a virtual keysym. In this case, you must specify the virtual keysym in the SAS.keyboardTranslations resource instead of the keysym that is displayed by the xev utility. To determine the virtual keysym that is bound to a key, you can start the Resource Helper, click Keys, and press the key or key combination that you want to define. Resource Helper will display the virtual keysym name. You can also refer to the key definition files in /Xll/resource_files in the directory where SAS is installed (!SASROOT) and to the UNIX man pages for VirtualBinding or xmbind.

Syntax of the SAS.keyboardTranslations Resource

Note: Most SAS documentation uses angle brackets (<>) to indicate optional syntax. However, in this topic, optional syntax is shown with square brackets ([]). The angle brackets that are shown in this topic are part of the syntax and should be entered exactly as shown.

Here is the syntax of the SAS.keyboardTranslations resource:

SAS.keyboardTranslations: #override \

[modifier] <Key>keysym : action-routine \n\

[modifier] <Key>keysym : action-routine

#override

indicates that this definition should override any existing bindings for the specific keys that you define without affecting any other keys. If you omit the #override directive, the new bindings replace all of the default bindings, and none of the other keys on the keyboard will be available.

Note: For information about the #augment and #replace directives, see the documentation for the X Window System.

modifier

can be one of the following:

Alt
Ctrl
Meta
Shift
Lock
Mod1
Mod2
Mod3
Mod4
Mod5
None
blank space

The list of valid modifiers varies depending on your keyboard. To display a list of valid modifiers for your keyboard, enter the xmodmap UNIX command. For more information, refer to the UNIX man page for xmodmap.

<Key>

is required. It signals the beginning of the keysym.

keysym

is the key symbol recognized by X for the key that you are defining. For more information, see Determining Keysyms.

action-routine

is what you want the key to do. You can specify any action routine described in SAS Keyboard Action Names.

enables the X translation manager to determine where one translation sequence ends and the next one begins. Do not enter \n after the end of the last translation.

prevents the newline character at the end of the line from being interpreted as part of the definition. Using this character is a stylistic convention that allows each translation to be listed on a separate line. Do not enter a backslash after the end of the last translation.

Note: SAS does not prevent you from specifying invalid keys in the SAS.keyboardTranslations resource. In some cases, invalid keys will produce warnings in the shell window.

Syntax of the SAS.keysWindowLabels Resource

Note: The square brackets ([]) in the following syntax indicate that (InternalKeyName) is optional.

Here is the syntax of the SAS.keysWindowLabels resource:

SAS.keyWindowLabels: \

KeyWindowLabel [(InternalKeyName)] \n\

KeyWindowLabel [(InternalKeyName)]

KeyWindowLabel

is the label (1 to 8 characters) that you want to appear in the Keys window.

InternalKeyName

is the character string that is passed to the sas-function-key action routine in the corresponding SAS.keyboardTranslations key binding. (InternalKeyName is used by SAS to correlate Keys window entries to key definitions in the KEYS modules loaded from SAS catalogs or defined in the SAS Keys window.) If the InternalKeyName is not specified, SAS uses the KeyWindowLabel as the InternalKeyName.

\n and \

serves the same purpose as in the SAS.keyboardTranslations resource. For more information, see Syntax of the SAS.keyboardTranslations Resource.

SAS Keyboard Action Names

Note: Most SAS documentation uses angle brackets (<>) to indicate optional syntax. However, in this topic optional syntax is shown with square brackets ([]). The angle brackets that are shown in this topic are part of the syntax and should be entered exactly as shown.

SAS declares a set of keyboard actions during X initialization. You can think of these keyboard actions as simple functions. When the actions are executed, they act on the window that currently has keyboard input focus.

The following list of keyboard actions represents action routines registered by the Motif interface for use with X Toolkit keyboard event translations.

sas-cursor-down()

moves the cursor down one line in the SAS window. The cursor does not wrap when it reaches the bottom of the SAS window interior.

sas-cursor-left()

moves the cursor left one character in the SAS window. The cursor does not wrap when it reaches the left side of the SAS window interior.

sas-cursor-right()

moves the cursor right one character in the SAS window. The cursor does not wrap when it reaches the right side of the SAS window interior.

sas-cursor-up()

moves the cursor up one line in the SAS window. The cursor does not wrap when it reaches the top of the SAS window interior.

sas-delete()

deletes all text in the current field.

sas-delete-begin()

deletes text from the current cursor position to the beginning of the current text field.

sas-delete-char()

deletes the character under the text cursor and leaves the cursor in place.

sas-delete-end()

deletes text from the current cursor position to the end of the current text field.

sas-delete-prev-chr()

deletes the character to the left of the text cursor and moves the cursor back one space.

sas-delete-prev-word()

deletes text to the start of the previous word from the current cursor position. If the cursor is in the interior of a word when the action is invoked, the text from the cursor position to the start of the word is deleted.

sas-delete-word()

deletes text from the current cursor position to the end of the current or next word.

sas-do-command()

accepts one or more text string parameters that are interpreted as SAS commands to be executed when the action is invoked. The action might be invoked with multiple parameters. The parameters are concatenated with semicolon delimiters supplied by the sas-do-command action between the parameters. The assembled SAS command string is then submitted for execution. For example, the following translation syntax can be used to define a HOME, SUBMIT key sequence for all SAS windowing environment windows:

<Key>KP_F3: sas-do-command(HOME;SUBMIT)

sas-function-key("InternalKeyName")

invokes the SAS commands associated with the function key identified by the InternalKeyName label. InternalKeyName is the character string (1 to 8 characters long) that is passed to the keysWindowLabels resource. Enclose InternalKeyName in quotation marks. For a description of internal key names, see Defining Key Translations.

sas-home-cursor()

is the equivalent of the HOME command. It is provided for convenience so that the HOME action could be defined for all SAS windowing environment windows.

sas-insert-char(["InsertionString"])

inserts or overwrites the character entered into the input field under the text cursor. Insert or overstrike behavior is determined by the sas-toggle-insert action, which has a mode that is reflected by the text cursor style displayed; the block cursor indicates overstrike mode, and the underline cursor indicates Insert mode. Normally, sas-insert-char translates the XKeyEvent into the appropriate character and inserts it at the SAS text cursor location. If you specify the parameter, the text string represented by this parameter is inserted at the SAS text cursor location. White space in the string is interpreted by the X Toolkit as a parameter delimiter unless you enclose the string in double quotation marks. See your X Window System documentation for information about embedding quotation marks in the string parameter. To include an escaped quotation mark, use the following syntax:

Shift<Key>KP_1:  sas-insert-char("One\\"1\\"")

This syntax produces the text string One"1" at the SAS text cursor location.

sas-kp-application()

sets the workstation's numeric keypad to allow function key translations to be reinstated. This action only works for those keypad keys that are bound to sas-function-key() actions. Keypad bindings to other actions are not affected by this translation.

sas-kp-numeric()

sets the workstation's keypad to generate numeric characters instead of its previous function key assignment. This action only works for keypad keys that are bound to sas-function-key() actions. Keypad bindings to other actions are not affected by this translation.

sas-move-begin()

moves the cursor to the beginning of the current text field.

sas-move-end()

moves the cursor to the end of the current text field.

sas-new-line()

generates an end-of-line event when invoked. This action is context sensitive. If the action is entered on the SAS command line, the text entered will be submitted for execution. If invoked in the SAS application client area, the action depends on the attributes of the text area under the text cursor. In simplest terms, this action is the general line terminator for an input field.

sas-next-field()

advances the SAS application to the next field in the SAS window client area.

sas-next-word()

skips the text cursor forward to the beginning of the next word in the current text field. If sas-next-word does not find the beginning of a word in the current text field, it advances to the next SAS application field. If you are typing in the SAS command line area of the window, the cursor will not wrap into the SAS window client area.

sas-page-down()

scrolls the current window contents forward by one page.

sas-page-end()

moves the text cursor to the end of the current page.

sas-page-top()

moves the text cursor to the top of the current page.

sas-page-up()

scrolls the window contents backward by one page.

sas-prev-field()

returns the SAS application to the previous field in the SAS window client area.

sas-prev-word()

skips the text cursor backward to the beginning of the previous word in the current text field. If sas-prev-word does not find the beginning of a previous word in the current text field, it returns to the end of the previous SAS application field. If you are typing in the SAS command line area of the window, the cursor will not wrap into the SAS window client area.

sas-to-bottom()

moves the text cursor to the absolute bottom of the window's text range.

sas-to-top()

moves the text cursor to the absolute top of the window's text range.

sas-toggle-insert()

switches the associated window line-editing behavior between insert and overstrike modes. This switching applies only to the SAS command line and the SAS window client area. The current mode is indicated by the cursor style in use. The block cursor indicates overstrike mode, and the underline cursor indicates Insert mode.

sas-xattr-key(<KeyType>[,<KeyParam>])

processes SAS extended attribute keys. The KeyType parameter must be one of the following values: XACOLOR, XAATTR, XACLEAR. For KeyType XACOLOR, the 12 DMS color names are valid parameters; for KeyType XAATTR, the valid values are HIGHLIGHT, REVERSE, BLINK, and UNDERLINE; for XACLEAR, no parameter is required. The BLINK attribute is not supported in the Motif interface. However, if you specify the BLINK attribute, it will be displayed when the catalog is ported to other operating environments.

Examples: Defining Keys Using SAS Resources

Note: Most SAS documentation uses angle brackets (<>) to indicate optional syntax. However, in these examples, optional syntax is shown with square brackets ([]). The angle brackets that are shown in these examples are part of the syntax and should be entered exactly as shown.

In the following example, the sas-do-command action routine specifies that the COMMAND command is to override any existing definition for KP_0.

SAS.keyboardTranslations: #override \n\
    None<Key>KP_0: sas-do-command(COMMAND)

All other keys retain their current definitions.

The following example binds the key sequence CTRL-K to the KEYS command and specifies that CTRL-D deletes the character under the cursor. Commands entered in the Keys window for CTRL-K and CTRL-D will have no effect.

SAS.keyboardTranslations: #override\
    Ctrl<Key>k: sas-do-command(keys)\n\
    Ctrl<Key>d: sas-delete-char()

The following example specifies that the key associated with the keysym hpClearLine performs the command entered beside the MyClrLn label in the Keys window.

SAS.keyboardTranslations: #override \
   <Key>hpClearLine : sas-function-key("ClearLn")
SAS.keysWindowLabels: MyClrLn(ClearLn)

The character string that appears inside the parentheses in the SAS.keysWindowLabels resource must match the string entered as the parameter to the sas-function-key routine. The label (MyClrLn) can be any character string, and the keysym hpClearLine must be a valid keysym for your keyboard.