L_CHR

Perform single-keystroke input to a list

xcall L_CHR(character, list_id, [data], [disabled], [row], [column], [help_id], [wait_time]
&     [, a_methoddata1, ..., a_methoddata20])

Arguments

character

Returned with the character typed. (a)

list_id

The ID of the list. (n)

data

(optional) The non-window data for the current item. (a)

disabled

(optional) The disabled item status. (n)

row

(optional) The row within the input window (within an item). (n)

column

(optional) The column within an item. (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.

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. (any)

Discussion

L_CHR performs single-keystroke input on a list. It performs essentially the same function in a list as U_CHR does in a window.

This subroutine does not return until a character is typed by the user or a menu entry (other than those listed below for Windows) is selected.

On Windows, L_CHR recognizes the following reserved menu entries. E_PASTE pastes a single character, and the others do nothing when L_CHR is being processed.

E_CLEAR

E_COPY

E_CUT

E_MARK

E_PASTE

Whether or not the data argument is passed must correspond to whether it was passed in the L_CREATE subroutine when the list was created. Data is required here if it was also passed to L_CREATE. If data is passed here but was not passed to L_CREATE, a fatal error occurs.

Disabled is a true/false flag that indicates whether the current item is disabled. Whether or not the disabled argument is passed must correspond to whether it was passed to other list routines such as L_DATA, L_INPFLD, L_INPUT, L_PROCESS, and L_SELECT. See L_PROCESS for information about the disabled item status.

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.

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to L_CHR. L_CHR, in turn, passes them directly to each field’s methods. This allows you to communicate additional information to your input field methods.

On Windows, the user can change the current item in the list with the mouse or the Page Up, Page Down, Home, End, and arrow keys before this subroutine returns. Therefore, if you want any special processing to be done when arriving at or leaving a list item, you will have to write and use an arrive or leave method. (In Windows environments, these keys are “privatized” and unavailable to calling routines unless you use L_RETURNKEY to return the key out of the list. “Privatized” means that they are reserved for the private use of the graphical control, which in this case would be the list.)

If you are using L_SELECT you do not need to call this subroutine because L_SELECT handles list input.