NAME

form_driver — form library

LIBRARY

Curses Form Library (libform, -lform)

SYNOPSIS

#include <form.h>

int
form_driver(FORM *form, int request);

DESCRIPTION

The form_driver() is the heart of the forms library, it takes commands in the request parameter that is either a request to the driver to perform some action or is a character to be inserted into the current field. The form driver will attempt to insert any printable character passed to it into the current field. This may or may not succeed depending on the state of the current field. If the character passed is not printable then the driver attempts to process it as a driver request. If the character passed is not a valid request then the driver will return an unknown command error.

PARAMETERS

The forms driver recognizes the following requests:

REQ_NEXT_PAGE

Change to the next page in the form.

REQ_PREV_PAGE

Change to the previous page in the form.

REQ_FIRST_PAGE

Select the first page in the form.

REQ_LAST_PAGE

Go to the last page in the form.

REQ_NEXT_FIELD

Move to the next field in the form field array.

REQ_PREV_FIELD

Move to the previous field in the form field array.

REQ_FIRST_FIELD

Go to the first field in the form field array.

REQ_LAST_FIELD

Go to the last field in the form field array.

REQ_SNEXT_FIELD

Move to the next sorted field on the form.

REQ_SPREV_FIELD

Move to the previous sorted field on the form.

REQ_SFIRST_FIELD

Go to the first field in the sorted list.

REQ_SLAST_FIELD

Move to the last field in the sorted list.

REQ_LEFT_FIELD

Go one field to the left on the form page.

REQ_RIGHT_FIELD

Go one field to the right on the form page.

REQ_UP_FIELD

Go up one field on the form page.

REQ_DOWN_FIELD

Go down one field on the form page.

REQ_NEXT_CHAR

Move one char to the right within the field

REQ_PREV_CHAR

Move one char to the left within the current field.

REQ_NEXT_LINE

Go down one line in the current field.

REQ_PREV_LINE

Go up one line in the current field.

REQ_NEXT_WORD

Go forward one word in the current field

REQ_PREV_WORD

Go backward one word in the current field.

REQ_BEG_FIELD

Move the cursor to the beginning of the current field.

REQ_END_FIELD

Move the cursor to the end of the current field.

REQ_BEG_LINE

Move the cursor to the beginning of the line in the current field.

REQ_END_LINE

Move the cursor to the end of the line.

REQ_LEFT_CHAR

Move the cursor left one character

REQ_RIGHT_CHAR

Move the cursor right one character

REQ_UP_CHAR

Move the cursor up one line.

REQ_DOWN_CHAR

Move the cursor down one line.

REQ_NEW_LINE

Insert a new line at the current cursor position.

REQ_INS_CHAR

Insert a blank character at the current cursor position

REQ_INS_LINE

Open a blank line at the current cursor position.

REQ_DEL_CHAR

Delete the character at the current cursor position.

REQ_DEL_PREV

Delete the character to the left of the current cursor position.

REQ_DEL_LINE

Delete the current line.

REQ_DEL_WORD

Delete the word at the current cursor position.

REQ_CLR_EOL

Clear the field from the current cursor position to the end of the current line.

REQ_CLR_EOF

Clear the field from the current cursor position to the end of the field.

REQ_CLR_FIELD

Clear the field.

REQ_OVL_MODE

Enter overlay mode, characters added to the field will replace the ones already there.

REQ_INS_MODE

Enter insert mode, characters will be inserted at the current cursor position. Any characters to the right of the cursor will be moved right to accommodate the new characters.

REQ_SCR_FLINE

Scroll the field forward one line.

REQ_SCR_BLINE

Scroll the field backward one line.

REQ_SCR_FPAGE

Scroll the field forward one field page.

REQ_SCR_BPAGE

Scroll the field backward one field page.

REQ_SCR_FHPAGE

Scroll the field forward half one field page.

REQ_SCR_BHPAGE

Scroll the field backward half one field page.

REQ_SCR_FCHAR

Scroll the field horizontally forward one character

REQ_SCR_BCHAR

Scroll the field horizontally backward one character

REQ_SCR_HFLINE

Scroll the field horizontally forward one field line.

REQ_SCR_HBLINE

Scroll the field horizontally backward one field line.

REQ_SCR_HFHALF

Scroll the field horizontally forward half a field line.

REQ_SCR_HBHALF

Scroll the field horizontally backward half a field line.

REQ_VALIDATION

Request the contents of the current field be validated using any field validation function that has been set for the field. Normally, the field is validated before the current field changes. This request allows the current field to be validated.

REQ_PREV_CHOICE

Select the previous choice in an enumerated type field.

REQ_NEXT_CHOICE

Select the next choice in an enumerated type field.

RETURN VALUES

Functions returning pointers will return NULL if an error is detected. The functions that return an int will return one of the following error values:

E_OK

The function was successful.

E_REQUEST_DENIED

The forms driver request could not be fulfilled

E_UNKNOWN_COMMAND

The passed character is not a printable character and is not a valid forms driver request.

E_BAD_ARGUMENT

A bad argument was passed to the forms driver.

E_INVALID_FIELD

The form passed to the driver has no valid attached fields.

E_NOT_POSTED

The given form is not currently posted to the screen.

E_BAD_STATE

The forms driver was called from within an init or term function.

E_INVALID_FIELD

The character passed to the forms driver fails the character validation for the current field.

SEE ALSO

curses(3), forms(3)

NOTES

Field sorting is done by location of the field on the form page, the fields are sorted by position starting with the top-most, left-most field and progressing left to right. For the purposes of sorting, the fields top left corner is used as the sort criteria. The header <form.h> automatically includes both <curses.h> and <eti.h>.