U_CHR

Accept one character from the terminal

xcall U_CHR(character, [window_id], [row, col], [help_id][, wait_time])

Arguments

character

Returned with the character that was input. (a)

window_id

(optional) The ID of the window in which to perform input. This is required if echo is on. (n)

row, col

(optional) The window row and column positions this subroutine will be reading from. (n)

help_id

(optional) The help identifier. (a)

wait_time

(optional) The time-out limit for I/O processing to be completed before returning to the calling routine. (n)

D_FOREVER or -1

Never time out.

D_GLOBAL or -2

Use the global value (see g_wait_time). (default)

D_IMMEDIATE or 0

Time out immediately.

Wait up to n seconds (where n is a positive value) for I/O processing to be complete.

Discussion

U_CHR accepts one character of input from the terminal. If you are performing input to a list item, use the L_CHR subroutine instead of U_CHR. While waiting for character input, this subroutine will do any menu or shortcut processing.

On Windows, U_CHR recognizes the following reserved menu entries on Windows. E_PASTE pastes a single character if echo is on. The others do nothing when U_CHR is being processed.

E_CLEAR

E_COPY

E_CUT

E_MARK

E_PASTE

If echo is on (in other words, if the D_ECHO state for E_STATE is on), you must pass window_id. If echo is off, window_id is optional. In that case, U_CHR accepts a character (in character) without displaying it.

If you pass row, you must also pass col. If you omit both, U_CHR uses the current display location in the window. Note that if echo is on, the display location (whether it’s the default or a location set by row and col) must be visible. If not, Toolkit will generate a fatal error.

If g_select is set on return, a menu entry has been selected, and g_entnam contains the name of the selected entry. If the internal name of the selected menu entry begins with “U_,” the EUTILS_METHOD subroutine is called and the input is redone. If the internal name of the selected menu entry is “O_HELP,” the EHELP_METHOD subroutine is called with help_id as its argument.

You will need to clear g_select after you satisfy the event.

On return, the field gi_sts (defined in inpctl.def) will be set with the status. If a printable character was entered, gi_sts will be NORMAL_INPUT (zero) and the character received will be in character. If a control character (ASCII value 1-31) was input, gi_sts will be non-zero and the control character will be in character. If any other character was input, gi_sts will be non-zero, and character will be a null (binary zero).

If the operation times out, g_select is set to true and g_entnam set to the entry name specified in g_time_entry, which is defined in tkctl.def. See g_time_entry.