DEFINE_KEY Procedure

Reference Guide > D Routines > DEFINE_KEY Procedure

Programs a function key with a string value or with an action. Also programs a control key with an action (UNIX only).

Usage

DEFINE_KEY, key[, value]

Input Parameters

key — The name of a function key to be programmed. Must be a scalar string. PV-WAVE maintains an internal list of function key names and the escape sequences they send.

note

Under UNIX, if key is not already on PV-WAVE’s internal list, you must use the Escape keyword to specify the escape sequence; otherwise, key alone will suffice. The section "Standard Function Keys Under UNIX" describes the standard key definitions; however, available function keys and the escape sequences they send vary from keyboard to keyboard.

value — (optional) The scalar string that key will be programmed with. Afterwards, pressing the programmed key results in value being entered as if it had been typed manually at the keyboard. If value is not present, and no function is specified for the key with one of the keywords, the key is cleared, and nothing will happen when it is pressed.

Keywords

Most of the following keywords work under UNIX only.

Back_Character — (UNIX only) Programs key to move the current cursor position left one character.

Back_Word — (UNIX only) Programs key to move the current cursor position left one word.

Delete_Character — (UNIX only) Programs key to delete the character to the left of the current cursor.

Delete_Forward_Char — (UNIX only) — Programs key to delete the character to the right of the cursor.

Delete_Line — (UNIX only) Programs key to delete all characters to the left of the current cursor.

Delete_To_EOL — (UNIX only) Programs key to delete all characters to the right of the cursor.

Delete_Word — (UNIX only) Programs key to delete the word to the left of the current cursor.

End_of_Line — (UNIX only) Programs key to move the current cursor to the end of the line.

Enter_Line — (UNIX only) Programs key to enter the current line. This is the action normally performed by the <Return> key.

Escape — (UNIX only) Specifies the escape sequence that corresponds to key. Escape must be a scalar string. See "Defining New UNIX Function Keys" for further details.

Forward_Character — (UNIX only) Programs key to move the current cursor position right one character.

Forward_Word — (UNIX only) Programs key to move the current cursor position right one word.

Insert_Overstrike_Toggle — (UNIX only) Programs key to toggle between insert and overstrike mode. When characters are typed into the middle of a line, insert mode causes the trailing characters to be moved to the right to make room for the new ones, while overstrike mode causes the new characters to overwrite the existing ones.

Match_Previous — Programs key to prompt the user for a string, and searches the saved command buffer for the most recently issued command containing that string. If a match is found, the command becomes the current command; otherwise the last command entered is used.

note	Under UNIX, the default match key is the up caret “^” key when pressed in column 1.

Next_Line — (UNIX only) Programs key to move forward one command in the saved command buffer and make it the current command.

Noecho — If nonzero, and value is present, Noecho specifies that when key is pressed, its value should be entered without being echoed. This is useful for defining keys that perform actions such as erasing the screen. If Noecho is specified, the Terminate keyword is assumed to be present and nonzero also.

Previous_Line — (UNIX only) Programs key to move back one command in the saved command buffer and make it the current command.

Redraw — (UNIX only) Programs key to redraw the current line.

Start_of_Line — (UNIX only) Programs key to move the current cursor to the start of the line.

Terminate — If nonzero, and value is present, Terminate specifies that pressing key terminates the current input operation after its value is entered. It acts as an implicit <Return> added to the end of value.

Discussion

The SETUP_KEYS procedure should be used once at the beginning of the session to enter the keys for the current keyboard.

It is convenient to include commonly used key definitions in a startup file so that they will always be available.

note	For a discussion of startup files, see the PV‑WAVE User’s Guide.

To see information on the currently defined keys, enter:

INFO, /Keys

Defining Control Keys

To define a control key, use the circumflex character (^) before any character A through Z, either upper or lowercase. For example:

DEFINE_KEY, '^F', /Forward_key

This command defines <Control>-F to move the cursor one character to the right.

You cannot bind a control key to a string, and some control keys are used for process management. For example, <Control>-C is usually used to interrupt a UNIX process and <Control>-Z is used to suspend a UNIX process. These special characters are listed in the PV‑WAVE User’s Guide.

note	The UNIX stty command can be used to rebind tty control characters or to eliminate them altogether. Refer to the stty man page for more information.

Defining New UNIX Function Keys

To add a definition for a function key that is not built into PV-WAVE’s default list of recognized keys, use the Escape keyword to specify the escape sequence it sends. For example, to add a function key named <HELP> which sends the escape sequence <Escape> [28~, use the command:

DEFINE_KEY, 'HELP', Escape = '\033[28~'

This command adds the <HELP> key to the list of keys understood by PV-WAVE. Since only the key name and escape sequence were specified, pressing the <HELP> key will do nothing. The value parameter, or one of the keywords provided to specify command line editing functions, could have been included in the above statement to program it with an action.

Once a key is defined using the Escape keyword, it is contained in the internal list of function keys. It can then be subsequently re-defined without specifying the escape sequence.

However, if the SETUP_KEYS procedure is used to define the function keys found on the keyboard, it is not necessary to specify the Escape keyword. For example, the following statements program the <F2> key on a Sun keyboard to redraw the current line:

SETUP_KEYS

DEFINE_KEY, 'F2', /Redraw

Standard Function Keys Under UNIX

Under UNIX, PV-WAVE can handle arbitrary function keys. Standard UNIX key definitions are listed in UNIX Key Definitions.

note	SunOS users, the function keys R8, R10, R12, and R14 (the arrow buttons) are reserved and cannot be set with DEFINE_KEY. Also, the L1 — L10 keys are reserved for use by the window manager and cannot be set with DEFINE_KEY.

Table 5-6: UNIX Key Definitions
Editing Key	Function
<Control> <A>	Move cursor to start of line.
<Control> <B>	Move cursor left one word.
<Control> <D>	EOF if current line is empty, EOL otherwise.
<Control> <E>	Move to end of line.
<Control> <F>	Move cursor right one word.
<Control> <N>	Move back one line in recall buffer.
<Control> <R>	Redraw current line.
<Control> <U>	Delete from current position to start of line.
<Control> <W>	Delete previous word.
<Backspace>, <Delete>	Delete previous character.
<Escape> <I>	Overstrike/Insert mode toggle.
<Escape> <Delete>	Delete previous word.
Up Arrow	Move back one line in recall buffer.
Down Arrow	Move forward one line in recall buffer.
Left Arrow	Move left one character.
Right Arrow	Move right one character.
<R13>	Move cursor left one word (Sun keyboard).
<R15>	Move cursor right one word (Sun keyboard).
text	If first character, recall first line containing text; if text is blank, recall previous line.
other characters	Insert the character at the current cursor position.

Standard Function Keys Under Windows

Standard key definitions for PV‑WAVE running under Windows are listed in Windows Key Definitions:

Table 5-7: Windows Key Definitions
Editing Key	Function
<Control> <A>	Move cursor to start of line.
<Control> <B>	Move cursor left one word.
<Control> <D>	EOF if current line is empty, EOL otherwise.
<Control> <E>	Move to end of line.
<Control> <F>	Move cursor right one word.
<Control> <N>	Move back one line.
<Control> <R>	Redraw current line.
<Control> <U>	Delete from current position to start of line.
<Control> <W>	Delete previous word.
<Backspace>, <Delete>	Delete previous character.
Escape <Delete>	Delete previous word.
<Control>text	If the line is empty, find the last command matching text.
Up Arrow	Move back one line.
Down Arrow	Move forward one line.
Left Arrow	Move left one character.
Right Arrow	Move right one character.
Insert/Overstrike	Toggle between insert and overstrike mode.
Page Down	Move forward one line.
Page Up	Move back one line.
End	Move to the end of the current line.
Home	Move to the start of the current line.
Insert	Toggle between insert and overstrike mode.

Example

You can define the <F12> key to execute INFO, /Keys with the statement:

DEFINE_KEY, /Terminate, 'F12', 'INFO, /Keys'

the INFO, /Keys command produces output that includes the line:

F12 <\03[P> = INFO, /Keys <Terminate>

showing the new key definition.