ETI form requests

The ETI form subsystem places the following requests at your application program's disposal.

Page navigation requests

These requests enable your end-user to navigate or move from page to page on a multi-page form.

REQ_NEXT_PAGE -

move to next page

REQ_PREV_PAGE -

move to previous page

REQ_FIRST_PAGE -

move to first page

REQ_LAST_PAGE -

move to last page

• the REQ_NEXT_PAGE request from the last page moves to the first page

• the REQ_PREV_PAGE from the first page moves to the last.

Inter-field navigation requests on the current page

These requests enable your end-user to move from field to field on the current page of a single form.

REQ_NEXT_FIELD -

move to next field

REQ_PREV_FIELD -

move to previous field

REQ_FIRST_FIELD -

move to first field

REQ_LAST_FIELD -

move to last field

REQ_SNEXT_FIELD -

move to sorted next field

REQ_SPREV_FIELD -

move to sorted previous field

REQ_SFIRST_FIELD -

move to sorted first field

REQ_SLAST_FIELD -

move to sorted last field

REQ_LEFT_FIELD -

move left to field

REQ_RIGHT_FIELD -

move right to field

REQ_UP_FIELD -

move up to field

REQ_DOWN_FIELD -

move down to field

• the REQ_NEXT_FIELD request from the last field on a page moves to the first field on that page.

• the REQ_PREV_FIELD request from the first field on a page moves to the last field on that page.

Your end-user may also move from field to field on the form page in row-major order -- left to right, top to bottom. To do so, you use the REQ_SNEXT_FIELD, REQ_SPREV_FIELD, REQ_SFIRST_FIELD, and REQ_SLAST_FIELD requests.

Finally, your end-user can move about in different directions using the REQ_LEFT_FIELD, REQ_RIGHT_FIELD, REQ_UP_FIELD, and REQ_DOWN_FIELD requests. Note that the first character (top left corner) of the field is used to determine where the field is located relative to other fields. This means, for example, that a multi-line field whose first character is on the second row of a form is not on the same row as a field whose first character is on the third row of a form even though the multi-line field may extend below the third row.

Intra-field navigation requests

These requests let your end-user move about inside a field. They may generate implicit scrolling operations on scrollable fields.

REQ_NEXT_CHAR -

move to next character in field

REQ_PREV_CHAR -

move to previous character in field

REQ_NEXT_LINE -

move to next line in field

REQ_PREV_LINE -

move to previous line in field

REQ_NEXT_WORD -

move to next word in field

REQ_PREV_WORD -

move to previous word in field

REQ_BEG_FIELD -

move to beginning of field

REQ_END_FIELD -

move after last character in field

REQ_BEG_LINE -

move to beginning of line

REQ_END_LINE -

move after last character in line

REQ_LEFT_CHAR -

move left in field

REQ_RIGHT_CHAR -

move right in field

REQ_UP_CHAR -

move up in field

REQ_DOWN_CHAR -

move down in field

• The REQ_NEXT_CHAR and REQ_PREV_CHAR requests step forward and backward through the field.

• The REQ_NEXT_LINE and REQ_PREV_LINE requests move the cursor to the beginning of the next and previous line.

• The REQ_NEXT_WORD and REQ_PREV_WORD requests move the cursor to the beginning of the next or previous word.

• The REQ_BEG_FIELD places the cursor at the first non-pad character in the field. The REQ_END_FIELD request places the cursor after the last non-pad character in the field. This lets the user easily add characters to the field. If there is no room, it returns the cursor to the start of the field.

• The REQ_BEG_LINE request places the cursor at the first non-pad character in the current line of the field. The REQ_END_LINE request places the cursor after the last non-pad character in the current line. If there is no room, it returns the cursor to the start of the line.

• The REQ_LEFT_CHAR, REQ_RIGHT_CHAR, REQ_UP_CHAR, and REQ_DOWN_CHAR requests move one character position in the stated direction.

Field editing requests

These requests set the editing mode -- insert or overlay.

REQ_INS_MODE -

begin insert mode

REQ_OVL_MODE -

begin overlay mode

The following requests provide a complete set of field editing requests.

REQ_NEW_LINE -

new line request

REQ_INS_CHAR -

insert blank character at cursor

REQ_INS_LINE -

insert blank line at cursor

REQ_DEL_CHAR -

delete character at cursor

REQ_DEL_PREV -

delete character before cursor

REQ_DEL_LINE -

delete line at cursor

REQ_DEL_WORD -

delete word at cursor

REQ_CLR_EOL -

clear to end of line

REQ_CLR_EOF -

clear to end of field

REQ_CLR_FIELD -

clear entire field

• The effects of REQ_NEW_LINE are as follows:

  • In insert mode -- if the cursor is at the beginning of a field or on the last line of a field, the REQ_NEW_LINE request acts like a REQ_NEXT_FIELD request. Otherwise, the REQ_NEW_LINE request inserts a new line after the current line and moves the text on the current line starting at the cursor position to the beginning of the new line. The cursor is moved to the beginning of the new line.

  • In overlay mode -- if the cursor is at the beginning of a field, the REQ_NEW_LINE request acts like a REQ_NEXT_FIELD request. If the cursor is on the last line of a field, the REQ_NEW_LINE request erases all data from the cursor position to the end of the line and satisfies a REQ_NEXT_FIELD request. Otherwise, the REQ_NEW_LINE request erases all data from the cursor position to the end of the line and moves the cursor to the beginning of the next line.

• The effects of the REQ_DEL_PREV request is as follows:

  • In insert mode -- if the cursor is at the beginning of a field, the REQ_DEL_PREV request behaves like a REQ_PREV_FIELD request. If the cursor is at the beginning of a line other than the first and the text on that line will fit at the end of the preceding line, the text is moved and the current line is deleted. Otherwise, the REQ_DEL_PREV request simply deletes the previous character.

  • In overlay mode -- if the cursor is positioned at the beginning of a field, the REQ_DEL_PREV request behaves like a REQ_PREV_FIELD request. Otherwise, the REQ_DEL_PREV request simply deletes the previous character.

Scrolling requests

Fields can scroll if they have offscreen data. A field can have offscreen data if it was originally created with offscreen rows-the parameter nrow in the new_field library routine was greater than 0-or the field has grown larger than its original size. See ``Dynamically growable fields'' for more details on the growth of fields.

There are two kinds of scrolling fields, vertically scrolling fields and horizontally scrolling fields. Multiline fields with offscreen data scroll vertically and one line fields with offscreen data scroll horizontally. Recall the library routine new_field; a new field created with rows set to one and nrow set to zero will be defined to be a one line field. A new field created with rows + nrow greater than one will be defined to be a multiline field.

The following form driver requests are used on vertically scrolling multiline fields.

REQ_SCR_FLINE -

scroll field forward a line

REQ_SCR_BLINE -

scroll field backward a line

REQ_SCR_FPAGE -

scroll field forward a page

REQ_SCR_BPAGE -

scroll field backward a page

REQ_SCR_FHPAGE -

scroll field forward half a page

REQ_SCR_BHPAGE -

scroll field backward half a page

The following form driver requests are used on horizontally scrolling one line fields.

REQ_SCR_FCHAR -

scroll field forward a character

REQ_SCR_BCHAR -

scroll field backward a character

REQ_SCR_HFLINE -

scroll field forward a line

REQ_SCR_HBLINE -

scroll field backward a line

REQ_SCR_HFHALF -

scroll field forward half a line

REQ_SCR_HBHALF -

scroll field backward half a line

In addition, intra-field navigation requests may generate implicit scrolling on scrollable fields. See ``Intra-field navigation requests''.

Field validation requests

This request supports field validation for those field types that have it.

REQ_VALIDATION -

validate current field

Recall that on current fields, the values returned by functions field_buffer and field_status are sometimes inaccurate. (See ``Setting and reading field buffers'' and ``Setting and reading the field status''.) If, however, you make request REQ_VALIDATION immediately before calling these functions, you can be sure that the values they return are accurate--they agree with what your end-user has entered and appears on the screen.

Choice requests

The following requests enable your user to request the next or previous value of a field type.

REQ_NEXT_CHOICE -

display next field choice

REQ_PREV_CHOICE -

display previous field choice