I_FLDINF

Return input field information

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

NSupported in Synergy .NET

xcall I_FLDINF(window_id, [field_spec], [field_number], [empty], [controls], 
&     [selection_id][, enabled])

Arguments

window_id

The ID of the input window containing the field. (n)

field_spec

(optional) The specification for the field whose information I_FLDINF will retrieve. (See Field specifications for information.) (a)

field_number

(optional) The field number supplied/returned. (n)

empty

(optional) The returned empty status. (n)

controls

(optional) The returned field controls. (a)

selection_id

(optional) The returned selection window ID. (n)

enabled

(optional) The returned enabled status. (n)

Discussion

I_FLDINF returns information about an input field. To use it you must .INCLUDE these two distributed .def files in this order:

• WND:system.def
• WND:fldinf.def

Window_id must contain the ID of a loaded input window.

If field_spec is found and non-blank, the input field number is returned in field_spec. (If field_spec is not found, field_number is returned as 0.) If field_spec is blank, field_number must be non-zero and the field specification is returned in field_spec. In either case, empty, controls, and selection_id may optionally be returned.

The field_number argument identifies the ordinal number of the .FIELD statement within the specific window script or the ordinal number of the call to IB_FIELD within the program. This does not necessarily correspond to the position of the field within any input set, nor to a low-level window field number (for example, using W_FLDS). If you want to know a field’s position within the input set, use I_SETINF to find out. If you want the number of the field in a low-level Synergy window, use gs_fnum, contained in the gs_inpfld record within the fldinf.def file (see Notes on gs_inpfld fields for multi-line text fields below).

Empty is returned true if the input field is currently empty.

Controls is the input field control record defined in the gs_inpfld record (in the file fldinf.def). For more information, see the comments in fldinf.def, and see Notes on gs_inpfld fields for multi-line text fields below. Note that to retrieve the strings referenced by the gs_xxx options using the function %I_GETSTRING, you must first call I_FLDINF with the controls argument to load the control structure.

If selection_id is returned with a value of 0, the field is not associated with a selection window.

Enabled is returned true if the input field is currently enabled; false if it is disabled.

Notes on gs_inpfld fields for multi-line text fields

The fields gs_edtrow, gs_edtcol, gs_edtlrow, and gs_edtlcol apply only to multi-line text fields. For all other fields, they will be zero. They are used to establish and record the cursor position within a multi-line text field.

The first two fields, gs_edtrow and gs_edtcol, dictate the cursor position that is to be established when the field next receives focus. If they are zero, the field will exercise the default behavior of awaiting the first keypress from the user before entering edit mode. On Windows platforms, this means that the entire field contents will be highlighted.

If gs_edtrow is non-zero, it specifies the low-level field number of the row to focus. This can be transformed into the ordinal row within the field by subtracting gs_fnum (the first field number) and adding 1. Thus, if an input field’s first field number (gs_fnum) is 4, and gs_edtrow is 6, then when the field receives focus, the cursor will be placed in the third row of that field.

If gs_edtcol is non-zero, it specifies the column within the field where the cursor will be placed. On Windows, the cursor will be placed before this position. On non-Windows, the cursor is placed on that column.

The gs_edtlrow and gs_edtlcol fields use the same coordinate system, but they refer to the last cursor position established within the field. Note that if the user accessed the field but never left the default initial state (in other words, they never entered edit mode), these fields will not be modified from their previous value. These fields are used by the Toolkit in two cases:

• As the reference position for a call to I_TXTPOS when using the D_LAST argument
• To set gs_edtrow and gs_edtcol when exiting a field that has the RETAIN_POSITION qualifier

For fields with the RETAIN_POSITION qualifier, gs_edtrow and gs_edtcol will usually contain the same value as gs_edtlrow and gs_edtlcol, respectively, unless I_TXTPOS has been called since the last input.

Note that I_TXTPOS never changes the value of gs_edtlrow/gs_edtlcol, so D_LAST always refers to the last input position, not the last position established by I_TXTPOS. D_CHANGE, however, refers to gs_edtrow/gs_edtcol, so those changes can be made cumulatively.

Examples

The following example returns the field number for field fld1[2,5] in the input window associated with the window ID (id).

xcall i_fldinf(id, "fld1[2,5]", fldnum)

The next example returns the name of field number three in fldname. If this field has an associated selection window, the selection window ID is returned in selid. Otherwise, selid contains zero upon return.

xcall i_fldinf(id, fldname, 3,,, selid)

The following example includes a calculation that determines the row position of the cursor in a multi-line field.

xcall i_fldinf(id, fldname,,, gs_inpfld)
row_num = gs_edtlrow - gs_fnum + 1