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
Page navigation requests are cyclic so that
-
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
All field navigation requests are cyclic on the current page
so that
-
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.
and so forth.
The order of the fields in the field array
passed to
new_form
determines the
order in which the fields are visited using the
REQ_NEXT_FIELD,
REQ_PREV_FIELD,
REQ_FIRST_FIELD, and
REQ_LAST_FIELD requests.
NOTE:
Remember that the order of fields in the form array
is simply the order in which fields are processed during
form processing.
This order
bears no necessary relation to the order of the fields as they are
displayed on the form 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 effect of these requests is as follows:
-
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
In insert mode (the default),
all text is inserted at the current cursor position, while
all existing text starting at the current cursor position is moved to the right.
In overlay mode, text entered by your end-user overlays (replaces)
existing text in the field.
In both modes, the cursor is
advanced one character position as each character is entered.
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 and REQ_DEL_PREV
requests depend on several factors such as
the current mode
(insert or overlay) and the cursor position within the 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.
Because
the requests REQ_NEW_LINE and REQ_DEL_PREV
automatically do a request
REQ_NEXT_FIELD or REQ_PREV_FIELD as described,
they are said to be overloaded field editing requests.
See the remarks on options O_NL_OVERLOAD and O_BS_OVERLOAD
in
``Setting and fetching form options''.
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
In the descriptions above,
a page is defined to be the number of visible rows of the field
as displayed on the form.
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 the descriptions above,
a line is defined to be the width of the field
as displayed on the form.
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
NOTE:
In general, the ETI
form driver automatically performs validation on a field
before the user leaves it.
(If your user leaves a field, it is valid.)
However, before your user
terminates interaction with the form,
you should make the REQ_VALIDATION request
to validate the 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
TYPE_ENUM is the only generic field type
that supports these choice requests.
In addition,
programmer-defined field types
may support these requests.
See
``Setting the field type to ensure validation''
and
``Creating and manipulating programmer-defined field types''
for information on these field types.
Next topic:
Application-defined commands
Previous topic:
A sample key virtualization routine
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004