I_INPFLD

Process an input field

xcall I_INPFLD(window_id, field_spec, data_location, [input_column] [, select_column]
&     [, text_column], [decimal_value], {reserved} [, a_methoddata1, ..., a_methoddata20])

Arguments

window_id

The ID of the input window to process. (n)

field_spec

The specification for the field to process. (See Field specifications for information.) (a)

data_location

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

input_column

(optional) The input column ID. (n)

select_column

(optional) The selection column ID. (n)

text_column

(optional) The text editing column ID. (n)

decimal_value

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

{reserved}

Placeholder. Add an additional comma if specifying any a_methoddata arguments.

a_methoddata1 through a_methoddata20

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

Discussion

I_INPFLD enables a single input field to accept user input. All other fields are not modifiable and, on Windows, do not have a frame. If you want to process a set of input fields, see I_INPUT. If you want to process input for a list item, see L_INPFLD.

If either window_id or field_spec is invalid, a fatal error occurs.

Data_location is loaded according to the input field’s definition, directly from the field, regardless of any input set associations. By default, Toolkit does not ensure that the size of data_location matches the size of the referenced field (field_spec) or that it is even large enough for the field. However, bounds checking can check for these 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 the field.
If g_dtkbounds is set to 2 or greater, Toolkit generates a fatal error if data_location is not large enough (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 the field.

If a non-reserved menu entry is selected and the call to I_INPFLD returns, g_select will be true and g_entnam will hold the name of the menu entry. You will need to clear g_select after you satisfy the event.

The default behavior for each environment’s handling of columns is controlled by the g_plc_col_args flag, which is defined in the distributed tkctl.def file. See g_plc_col_args for information.

I_INPFLD will also call EHELP_METHOD and EUTILS_METHOD on menu selections whose internal names are “O_HELP” or begin with “U_”, respectively.

If a time-out occurs, g_select is set to true and g_entnam is set to the entry name specified in tkctl.def for g_time_entry. By default, g_time_entry is defined as “O_TIMEOUT”.

If passed, decimal_value is converted to its alpha (ASCII) equivalent on UNIX and OpenVMS and placed into the window as if it were the first character entered by the user. Decimal_value is ignored on Windows.

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to I_INPFLD. I_ INPFLD, in turn, passes them directly to %ICHANGE_METHOD, %IDISPLAY_METHOD, and %IEDITFMT_METHOD. This allows you to communicate additional information to your change, display, and edit format methods.

I_INPFLD on Windows

On Windows, if any of the column arguments (input_column, select_column, or text_column) are passed, Toolkit will not, by default, place or remove the specified columns. These columns usually contain reserved menu entries that are automatically supported by the Windows environments. You can override this default behavior as noted below.

I_INPFLD recognizes the following menu entries on Windows, which are described in Appendix B: Reserved Menu Entries:

E_CLEAR

E_COPY

E_CUT

E_MARK

E_MODE

E_PASTE

I_CANCEL

Regardless of the available menu entries, the left and right arrow keys and the home, end, and delete keys are processed within I_INPFLD. Additionally, the up and down arrow keys are reserved and processed within I_INPFLD for multi-line edit controls, radio buttons, and selection fields. Therefore, with the following exception, these keys are never returned to the calling subroutine. However, when a single-line input field has focus, the up and down arrow keys and the home, end, and delete keys can be mapped to menu entries.

To edit a field that already contains data, the user can use the “E_” entries above. These “E_” entries are the same text editing functions supported by the T_EDIT subroutine.

When the menu entry I_CANCEL is selected, any input being performed will be canceled, and the field will be reset to its state prior to the start of the input, its initial state. (Note, however, that an EENTRST_METHOD can override I_CANCEL.)

I_INPFLD on UNIX and OpenVMS

On UNIX and OpenVMS, field editing and movement within the field can be automatically performed during input processing if the appropriate reserved menu entries are present on a loaded input_column, select_column, or text_column.

If the input_column is present and non-zero, that column will be placed on the menu and removed on exit. If the select_column is present and non-zero, it will be placed on the menu when a field with a selection window is processed. If the text_column is present and non-zero, it will be placed on the menu when a text field is processed.

I_INPFLD recognizes the following menu entries on UNIX and OpenVMS, which are described in Appendix B: Reserved Menu Entries:

E_LEFT	S_UP	I_CANCEL
E_RIGHT	S_DOWN	O_HELP
E_EMOV	S_LEFT	U_xxx
E_BMOV	S_RIGHT
E_MODE
E_CDEL
E_LCLR
E_XUP
E_XDOWN

To edit a field that already contains data, the user can use the “E_” entries above. These “E_” entries are a subset of the text editing functions supported by the T_EDIT subroutine. The entries that begin with “S_” are for selection windows.

Insert mode is the default for editing. Text field editing is very similar to text window editing, except that the text field’s input is terminated when the user presses Enter unless g_txt_rtrn is true. When editing text fields (dimensioned alpha fields) all menu entries for T_EDIT are recognized.

When the menu entry I_CANCEL is selected, any input being performed is canceled, and the field is reset to its initial state (prior to the start of the input).

Note that I_INPFLD does not invoke arrive or leave methods on UNIX or OpenVMS.

E_XUP and E_XDOWN operate differently than E_UP and E_DOWN when the cursor is already on the first or last row of a field. See the I_INPUT Discussion for more information.