GET_KBRD

The GET_KBRD function returns the next character available from the standard input (IDL file unit 0). Depending on the value of the Wait argument, it will either return immediately or wait until a character is present in the terminal type-ahead buffer.

Note: Use a GUI interface (e.g. WIDGET_BUTTON) instead of GET_KBRD where possible.

Tip: Under Microsoft Windows, the GET_KBRD function can be used to return Windows special characters (in addition to the standard keyboard characters). To get a special character, hold down the Alt key and type the character’s ANSI equivalent on the numeric keypad while GET_KBRD is waiting. Ctrl + key combinations are not supported.

Note: GET_KBRD is intended for use in IDL’s command-line mode. While GET_KBRD will return values for some characters when run from the IDL Workbench (either UNIX or Microsoft Windows), other characters are treated as special cases by the underlying windowing system, and may not be returned by GET_KBRD. In addition, the event-handling mechanism used by the IDL Workbench may not respond to keyboard events in the way that you expect. Use caution when using GET_KBRD within a loop.

Examples

To store the next character typed at the IDL prompt in the variable R, enter:

R = GET_KBRD()

Press any key. To see the character that was typed, enter:

PRINT, R

The following code fragment reads one character at a time and echoes that character’s numeric code (or codes, for keys that generate escape sequences). It quits when a “q” is entered:

REPEAT BEGIN

   A = GET_KBRD(/ESCAPE)

   PRINT, BYTE(A)

ENDREP UNTIL A EQ 'q'

The following code fragment reads one character at a time and echoes that character (or the key’s name, for named keys). It quits when a “q” is entered:

REPEAT BEGIN

   A = GET_KBRD(/KEY_NAME)

   PRINT, A

ENDREP UNTIL A EQ 'q'

Note: The GET_KBRD function can be used to return Windows special characters (in addition to standard keyboard characters), created by holding down the Alt key and entering the character’s ANSI equivalent. For example, to return the paragraph marker (¶), ANSI number 0182, enter:

C = GET_KBRD()

While GET_KBRD is waiting, press and hold the Alt key and type 0182 on the numeric keypad. When the IDL prompt returns, enter:

PRINT, C

IDL prints the paragraph marker,“¶”.

GET_KBRD cannot be used to return control characters or other editing keys (e.g., Delete, Backspace, etc.). These characters are used for keyboard shortcuts and command line editing only. GET_KBRD can be used to return the Enter key.

Syntax

Result = GET_KBRD([Wait] [, /ESCAPE | , /KEY_NAME])

Return Value

Returns a string containing the next available character that is input from the keyboard. If no keywords are specified, the result will always be a one-character string. If the ESCAPE or KEY_NAME keyword is specified, the result may contain multiple characters, as described below.

Arguments

Wait

If Wait is zero, GET_KBRD returns an empty string if there are no characters in the terminal type-ahead buffer. If the Wait argument is either not present or present and non-zero, the function waits for a character to be typed before returning.

Keywords

ESCAPE

This keyword is intended for use with IDL’s UNIX command line interface; it controls how the GET_KBRD function handles escape sequences. If ESCAPE is set and GET_KBRD encounters an escape sequence, the return value will be a string containing the entire sequence. See Escape Sequences below for more information.

KEY_NAME

This keyword is intended for use with IDL’s command line mode; it controls how the GET_KBRD function handles escape sequences. If KEY_NAME is set and GET_KBRD encounters an escape sequence, it reads the complete sequence and compares it to IDL’s table of known function keys. If the escape sequence corresponds to a known function key, the return value will be a string containing the name of the key, or an empty string otherwise. See Escape Sequences below for more information.

Escape Sequences

The command line version of IDL is usually used within the environment provided by a program called a terminal emulator. (The Xterm program is the most common such emulator, but there are others.) When you press an alphanumeric key on the keyboard, the terminal emulator sends the ASCII code for that character to the running program (IDL, in this case). For example, if you press the lowercase a key, the terminal emulator sends IDL the ASCII code for “a” (ASCII 97).

Some keys, including the arrow keys and the function keys on the top row of the keyboard, do not correspond directly to a single ASCII character. Instead, they send an escape sequence that the program can interpret and map to a useful meaning. An escape sequence consists of the ASCII ESC (ASCII 27) character, followed by one or more characters, following a special syntax that lets the reading program determine when a complete sequence has been seen. For example, when you press the up-arrow key, the vast majority of terminal emulators send the three-character sequence ESC[A.

By default, GET_KBRD returns the next available single ASCII character entered at the command line. In this mode, it does not treat escape sequences as special characters. If you call GET_KBRD and press the up-arrow key, GET_KBRD will return the ASCII ESC character and ignore the characters following it. The ESCAPE and KEY_NAME keywords can be used to alter this behavior.

If the ESCAPE keyword is set and GET_KBRD sees an escape sequence, it will read and return the entire escape sequence. For example, if the up-arrow key is pressed, GET_KBRD would (with most terminal emulators) return a string containing the three characters ESC[A (or, more specifically, the three characters defined by the ASCII codes 27 91 65 ).

Note: Escape sequences are not printable characters. This means that in order to see the characters that make up the escape sequence, you must view their byte values. For example, entering the following at the IDL command line, followed by the up-arrow key, may not produce visible output, depending on the terminal emulator in use:

PRINT, GET_KBRD(/ESCAPE)

If you enter the following at the IDL command line, followed by the up-arrow key:

PRINT, BYTE(GET_KBRD(/ESCAPE))

IDL will print

27 91 65

(or the values of the equivalent ASCII characters used by your terminal emulator).

If the KEY_NAME keyword is set and GET_KBRD sees an escape sequence, it will read the entire sequence. If the escape sequence is associated with a known function key, it will return the name of that key. If the sequence is not associated with a known function key, it will return an empty string. In the case of the up-arrow key example, GET_KBRD would return the string UP.

Note: The command HELP, /KEYS, /FULL can be used to see the full set of known keys and the escape sequences they are bound to. The DEFINE_KEY procedure can be used to add additional keys and/or escape sequences.

The ESCAPE and KEY_NAME keywords do not affect the way that GET_KBRD handles non-escape sequence characters. GET_KBRD always returns the single ASCII character seen in those situations.

The ESCAPE and KEY_NAME keywords are only applicable to command line mode. They are accepted, but ignored, when used with graphical mode.

Version History

Original	Introduced
6.2	Wait argument became optional ESCAPE and KEY_NAME keywords introduced