L_INPFLD

Perform single-field input within a list

xcall L_INPFLD(list_id, field_name, data_location, [data], [disabled], [input_column], 
&     [select_column], [text_column], [init_char] [, a_methoddata1, ..., a_methoddata20])

Arguments

list_id

The ID of the list. (n)

field_name

The field to process. (a)

data_location

Where to place the input data. (a or n)

data

(optional) The non-window list item data. (a)

disabled

(optional) The disabled item status. (n)

input_column

(optional) The input column ID. (n)

select_column

(optional) The selection column ID. (n)

text_column

(optional) The text column ID. (n)

init_char

(optional) The first character to input (specified as a decimal value). (n)

a_methoddata1 through a_methoddata20

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

Discussion

L_INPFLD performs the same function as the input subroutine I_INPFLD, except L_INPFLD performs the function for a field contained within a list. See I_INPFLD for information on the arguments you can pass to L_INPFLD and the menu entries recognized by L_INPFLD.

Whether or not the data argument is passed must correspond to whether it was passed in the L_CREATE call 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.

By default, Toolkit does not ensure that the size of data_location matches the size of field_name or that it is even large enough for field_name. However, bounds checking can check for the following conditions. (See g_dtkbounds for more information.)

If g_dtkbounds is set to 1, Toolkit generates a fatal error if data_location is not large enough for field_name.
If g_dtkbounds is set to 2 or greater, Toolkit generates a fatal error if data_location is not large enough for field_name (as it does if g_dtkbounds is set to 1), and it generates a nonfatal error if data_location is large enough, but isn’t the exact size of field_name.

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_CHR, L_DATA, L_INPUT, L_PROCESS and L_SELECT. See L_PROCESS for more information about the disabled item status.

On Unix and OpenVMS init_char, if passed, is converted to its alpha (ASCII) equivalent and placed into the field as if it were the first character entered by the user. Init_char is ignored on Windows.

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

When this subroutine returns, either field entry has been completed or a menu entry has been selected.

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

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 must 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.)