I_TXTPOS

Get or set the input position for a multi-line text field

xcall I_TXTPOS(window_id, field_spec, D_LAST)
xcall I_TXTPOS(window_id, field_spec, [D_CHANGE,] row, column)
xcall I_TXTPOS(window_id, field_spec, D_GETNEXT|D_GETLAST, row, column)

Arguments

window_id

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

field_spec

The specification for the multi-line text field. (See Field specifications for information.) (a)

D_LAST

Sets the position for subsequent input to field_spec to the position the cursor last occupied when accepting input.

D_CHANGE

(optional) Specifies that the values passed in row and column are offsets relative to the last position occupied during input (if you pass D_CHANGE), or it specifies that row and column are absolute coordinates relative to the field origin if you omit D_CHANGE (i.e., if you pass row and column without a D_ option).

D_GETNEXT

Returns in row and column the next projected position that will be used for input (or zeros if there is no projected next position).

D_GETLAST

Returns in row and column the last position occupied by the cursor to accept input (or zeros if there has been no previous input).

row

A row within the multi-line text field. (n)

column

A column within the multi-line text field. (n)

Discussion

I_TXTPOS gets or sets the input position for a multi-line text field:

If you pass D_LAST or D_CHANGE, or if you pass row and column without a D_ option, I_TXTPOS sets the cursor position for subsequent input. The next time field_spec is processed through one of Toolkit’s input routines, the cursor will be placed at the specified position. (Note that you can also use gs_inpfld fields to set the cursor position for a multi-line text field. See Notes on gs_inpfld fields for multi-line text fields.)
If you pass D_GETNEXT or D_GETLAST, I_TXTPOS returns (in row and column) the next projected position or the last position that the cursor occupied when an input routine processed field_spec.

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

Note the following when setting the position for subsequent input (D_LAST, D_NEXT, or no D_ option):

If you pass row and column without passing any of the D_ options for I_TXTPOS, do not include a comma placeholder for the omitted D_ option. For example:

xcall i_txtpos(inpid, "mytext", 2, 1)

Field_spec must be set to RETAIN_POSITION (.FIELD) or D_FLD_RETPOS (IB_FIELD and I_FLDMOD). If it is not set to one of these, row and column are treated as zero, even if they are passed as other values.
If row and column lie outside valid bounds for the field, Toolkit automatically limits them to valid values when field_spec is next processed by one of Toolkit’s input routines.

If you use D_GETNEXT, and the field is not set to RETAIN_POSITION (.FIELD) or D_FLD_RETPOS (IB_FIELD or I_FLDMOD), row and column are returned as zero unless you have set them to something else (with I_TXTPOS). In that case, they’ll return the values they were set to, as long as input hasn’t occurred on the field since they were set.

Examples

This example sets the position for the next input of the text field mytext to be the same position as last occupied during input of this field:

xcall i_txtpos(inpid, "mytext", D_LAST)

This example moves the position within the text field down one row from the previous input position (if the text field is set to RETAIN_POSITION or D_FLD_RETPOS):

xcall i_txtpos(inpid, "mytext", D_CHANGE, 1, 0)

The next example moves the position to the beginning of the second row of the text field:

xcall i_txtpos(inpid, "mytext", 2, 1)

The following examples retrieve the next projected input position and the last input position:

xcall i_txtpos(inpid, "mytext", D_GETNEXT, next_row, next_col)

xcall i_txtpos(inpid, "mytext", D_GETLAST, last_row, last_col)