Customizing Key Definitions in UNIX Environments | SAS 9.1 Companion For Unix Enivronments

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
Tools – Options – Keys
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.

Refer to SAS Help and Documentation for more information on 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, refer to the Base SAS section in 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 listed in the KEYS window. See "Setting X Resources with the Resource Helper" on page 62 and "Defining Keys with the Resource Helper" on page 63 for more information about 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" on page 74.

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 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 supplied by SAS, you must modify the keyboardTranslations resource.

Note

The X Toolkit Intrinsics translations 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 pull-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 recognized by the X Window System for each key on a keyboard. See "Determining Keysyms" on page 75 for more information.
Modify/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. See "Syntax of the SAS.keyboardTranslations Resource" on page 75 for more information.
Modify/add the SAS.keysWindowLabels resource in your resource file. The SAS.keysWindowLabels resource specifies the set of valid labels that will appear in the SAS 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. See "Syntax of the SAS.keysWindowLabels Resource" on page 76 for more information.
Start a SAS session and open the KEYS window.
In the right-hand column in the KEYS window, type a command name or other description of each key that you have defined.

See "Examples: Defining Keys Using SAS Resources" on page 80 for examples of key definitions.

Determining Keysyms

You can use the xev utility to determine the keysyms associated with the keys on your keyboard. xev is distributed with most UNIX operating systems, but if xev is not installed on your operating system, contact your system administrator for information about other methods that are available in your UNIX environment.

xev prints a message for each X event that occurs. The KeyPress event specifies the keysym for each key that is pressed.

Start xev 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 has 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 an HP 9000/700 keyboard is pressed, it generates the following output:
```
 KeyPress event, serial 14, synthetic NO,     window 0x4400001,root 0x23, subw 0x4400002,     time 507920400, (54,37),root:(67,66),     state 0x0, keycode 30 (keysym 0xffb0, KP_0),     same_screen YES,     XLookupString gives 1 characters: "0" 
```
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 displayed by xev . To determine the virtual keysym that is bound to a key, you can start the Resource Helper, select 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 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.

The syntax of the SAS.keyboardTranslations resource is

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. ^[1]

modifier

can be Alt , Ctrl , Meta , Shift , Lock , Mod1 , Mod2 , Mod3 , Mod4 , Mod5 , None ,ora 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. Refer to the man page for xmodmap for more information.

<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. See "Determining Keysyms" on page 75 for more information.

action-routine

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

allows 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. This 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 the (InternalKeyName) is optional.

The syntax of the SAS.keysWindowLabels resource is

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. See "Syntax of the SAS.keyboardTranslations Resource" on page 75 for more information.

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 may 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 quotes. Refer to "Defining Key Translations" on page 74 for a description of internal key names.

sas-home-cursor()

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

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

inserts or overwrites the character typed 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. Refer to your X Window System documentation for information on embedding quotes in the string parameter. To include an escaped quote, use the following syntax:
```
 Shift<Key>KP_1: sas-insert-char("One\"1\"") 
```
This 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 is a context-sensitive action. If the action is typed 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 only applies 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.

^[1] For information on the #augment and #replace directives, refer to the documentation for the X Window System.