FORM(S) UNIX System V FORM(S)
Name
form - FORM library routines
Syntax
#include <form.h>
cc [ flags ] files -lform -lcurses [ libraries ]
FORM * new_form (fields)
FIELD ** fields;
int free_form (form)
FORM * form;
int set_new_page (field, bool)
FIELD * field;
int bool;
int new_page (field)
FIELD * field;
int set_form_fields (form, fields)
FORM * form;
FIELD ** fields;
FIELD ** form_fields (form)
FORM * form;
int field_count (form)
FORM * form;
int set_form_win (form, window)
FORM * form;
WINDOW * window;
WINDOW * form_win (form)
FORM * form;
int set_form_sub (form, window)
FORM * form;
WINDOW * window;
WINDOW * form_sub (form)
FORM * form;
int set_current_field (form, field)
FORM * form;
FIELD * field;
FIELD * current_field (form)
FORM * form;
int field_index(field)
FIELD * field;
int set_form_page (form, page)
FORM * form;
int page;
int form_page (form)
FORM * form;
int scale_form (form, rows, cols)
FORM * form;
int * rows, cols;
typedef void (* PTF_void) ();
int set_form_init (form, func)
FORM * form;
PTF_void func;
PTF_void form_init (form)
FORM * form;
int set_form_term (form, func)
FORM * form;
PTF_void func;
PTF_void form_term (form)
FORM * form;
int set_field_init (form, func)
FORM * form;
PTF_void func;
PTF_void field_init (form)
FORM * form;
int set_field_term (form, func)
FORM * form;
PTF_void func;
PTF_void field_term (form)
FORM * form;
int post_form (form)
FORM * form;
int unpost_form (form)
FORM * form;
int pos_form_cursor (form)
FORM * form;
int form_driver (form, c)
FORM * form;
int c;
int set_form_userptr (form, userptr)
FORM * form;
char * userptr;
char * form_userptr (form)
FORM * form;
int set_form_opts (form, opts)
FORM * form;
OPTIONS opts;
OPTIONS form_opts (form)
FORM * form;
int form_opts_on (form, opts)
FORM * form;
OPTIONS * opts;
int form_opts_off (form, opts)
FORM * form;
OPTIONS * opts;
Description
FORM routines run on any terminal supported by curses(S),
the low-level library. Once you compile your program
#includeing the FORM header file <form.h>, you should link
it with the form and curses library routines.
Functions
The following is a list of FORM routines. For a complete
description of each, see the Programmer's Guide.
new_form (fields) creates a new form connected to the
designated fields and returns a pointer to the form.
free_form (form) disconnects the form from its associated
field pointer array and deallocates the space for the form.
set_new_page (field,bool) marks the given field to begin a
new page of the form.
new_page (field) returns a boolean value indicating whether
or not the given field begins a new page of the form.
set_form_fields (form, fields) changes the fields connected
to form to fields.
form_fields (form) returns a pointer to the field pointer
array connected to form.
field_count (form) returns the number of fields connected to
form.
set_form_win (form, window) sets window as the form window
of form.
form_win (form) returns a pointer to the window associated
with form.
set_form_sub (form, window) sets window as the form
subwindow of form.
form_sub (form) returns a pointer to the subwindow
associated with form.
set_current_field (form, field) sets the current field of
form to field.
current_field (form) returns a pointer to the current field
of form.
field_index(field) returns the index in the field pointer
array to the given field
set_form_page (form, page) sets the page number of form to
page.
form_page (form) returns the current page number of form.
scale_form (form, rows, cols) returns the smallest window
size necessary for form. rows and cols are pointers to the
locations used to return the number of rows and columns for
the form.
The workhorse of the forms subsystem, form_driver (form, c),
checks if the character c is a form request or data. If it
is a request, the form driver executes the request and
reports the result. If it is data (a printable ASCII
character), it enters the data into the current position in
the current field. If it is not recognized, the form driver
assumes it is an application-defined command and returns
E_UNKNOWN_COMMAND.
The following set_ functions enable you to establish
application routines to be executed automatically at
initialization and termination points in your form
application. You need not specify any application-defined
initialization or termination routines at all, but they may
be helpful for displaying messages or page numbers and other
chores.
set_form_init (form, func) sets an application-defined
initialization func to be called when the form is posted and
just after a page change.
form_init (form) returns a pointer to the initialization
function, if any, called when the form is posted and just
after a page change.
set_form_term (form, func) sets an application-defined func
to be called when the form is unposted and just before a
page change.
form_term (form) returns a pointer to the termination
function, if any, called when the form is unposted and just
before a page change.
set_field_init (form, func) sets an application-defined func
to be called when the form is posted and just after the
current field changes.
field_init (form) returns a pointer to the initialization
function, if any, called when the form is posted and just
after the current field changes.
set_field_term (form, func) sets func to be called when the
form is unposted and just before the current field changes.
field_term (form) returns a pointer to the termination
function, if any, called when the form is unposted and just
before the current field changes.
post_form (form) writes the form in its associated
subwindow.
unpost_form (form) erases the form from its associated
subwindow.
pos_form_cursor (form) moves the form window cursor to the
location required by the form driver to resume form
processing. This is sometimes helpful after you write a
message or page number.
Every form has an associated user pointer that you can use
to store pertinent data. set_form_userptr (form, userptr)
sets the form's user pointer.
form_userptr (form) returns the form's user pointer.
set_form_opts (form, opts) turns on the named options for
the form and turns off all its remaining options. Options
are boolean values. Currently, there are two form options,
O_NL_OVERLOAD and O_BS_OVERLOAD.
form_opts (form) returns the form's options setting.
form_opts_on (form, opts) turns on the named options.
form_opts_off (form, opts) turns off the named options.
See Also
curses(S), field(S), fieldtype(S), item(S), panel(S),
menu(S), tam(S)
Diagnostics
The following values are returned by one or more routines
that return an integer. For specific information on which
routines return which value, see the Programmer's Guide.
E_OK function returned successfully
E_CONNECTED object is connected
E_SYSTEM_ERROR system error
E_BAD_ARGUMENT argument is incorrect
E_CURRENT field is current field
E_POSTED form is posted
E_INVALID_FIELD field is invalid
E_NOT_CONNECTED object is not connected
E_NO_ROOM form does not fit in subwindow
E_BAD_STATE called from inappropriate routine
E_UNKNOWN_COMMAND unknown command was given to the form
driver
E_REQUEST_DENIED recognized request failed
(printed 6/20/89)