form(S) 6 January 1993 form(S) Name form - FORM library routines Syntax cc . . . -lform -lcurses #include <form.h> typedef void (*PTF_void) (); FIELD *current_field (form) FORM *form; int field_count (form) FORM *form; int field_index (field) FIELD *field; PTF_void field_init (form) FORM *form; PTF_void field_term (form) FORM *form; int form_driver (form, c) FORM *form; int c; FIELD **form_fields (form) FORM *form; PTF_void form_init (form) FORM *form; 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; int form_page (form) FORM *form; WINDOW *form_sub (form) FORM *form; PTF_void form_term (form) FORM *form; char *form_userptr (form) FORM *form; WINDOW *form_win (form) FORM *form; int free_form (form) FORM *form; FORM *new_form (fields) FIELD **fields; int new_page (field) FIELD *field; int pos_form_cursor (form) FORM *form; int post_form (form) FORM *form; int scale_form (form, rows, cols) FORM *form; int *rows, cols; int set_current_field (form, field) FORM *form; FIELD *field; int set_field_init (form, func) FORM *form; PTF_void func; int set_field_term (form, func) FORM *form; PTF_void func; int set_form_fields (form, fields) FORM *form; FIELD **fields; int set_form_init (form, func) FORM *form; PTF_void func; int set_form_opts (form, opts) FORM *form; OPTIONS opts; int set_form_page (form, page) FORM *form; int page; int set_form_sub (form, window) FORM *form; WINDOW *window; int set_form_term (form, func) FORM *form; PTF_void func; int set_form_userptr (form, userptr) FORM *form; char *userptr; int set_form_win (form, window) FORM *form; WINDOW *window; int set_new_page (field, bool) FIELD *field; int bool; int unpost_form (form) FORM *form; Description FORM routines run on any terminal supported by the curses(S) library. Once you compile your program including 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: newform (fields) creates a new form connected to the designated fields and returns a pointer to the form. freeform (form) disconnects the form from its associated field pointer array and deallocates the space for the form. setnewpage (field,bool) marks the given field to begin a new page of the form. newpage (field) returns a boolean value indicating whether the given field begins a new page of the form. setformfields (form, fields) changes the fields connected to form to fields. formfields (form) returns a pointer to the field pointer array connected to form. fieldcount (form) returns the number of fields connected to form. setformwin (form, window) sets window as the form window of form. formwin (form) returns a pointer to the window associated with form. setformsub (form, window) sets window as the form subwindow of form. formsub (form) returns a pointer to the subwindow associated with form. setcurrentfield (form, field) sets the current field of form to field. currentfield (form) returns a pointer to the current field of form. fieldindex (field) returns the index in the field pointer array to the given field. setformpage (form, page) sets the page number of form to page. formpage (form) returns the current page number of form. scaleform (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. formdriver (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 EUNKNOWNCOMMAND. Use the following set functions to establish application routines that execute automatically at initialization and termination points in your form application. You do not have to specify these routines, but they may be helpful for various tasks. setforminit (form, func) sets an application-defined initialization func to be called when the form is posted and just after a page change. forminit (form) returns a pointer to the initialization function, if any, called when the form is posted and just after a page change. setformterm (form, func) sets an application-defined func to be called when the form is unposted and just before a page change. formterm (form) returns a pointer to the termination function, if any, called when the form is unposted and just before a page change. setfieldinit (form, func) sets an application-defined func to be called when the form is posted and just after the current field changes. fieldinit (form) returns a pointer to the initialization function, if any, called when the form is posted and just after the current field changes. setfieldterm (form, func) sets func to be called when the form is unposted and just before the current field changes. fieldterm (form) returns a pointer to the termination function, if any, called when the form is unposted and just before the current field changes. postform (form) writes the form in its associated subwindow. unpostform (form) erases the form from its associated subwindow. posformcursor (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. setformuserptr (form, userptr) sets the form's user pointer. Every form has an associated user pointer that you can use to store pertinent data. formuserptr (form) returns the form's user pointer. setformopts (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, ONLOVERLOAD and OBSOVERLOAD. formopts (form) returns the form's options setting. formoptson (form, opts) turns on the named options. formoptsoff (form, opts) turns off the named options. See also curses(S), field(S), fieldtype(S), item(S), menu(S), panel(S), tam(S) Diagnostics The following values are returned by one or more routines that return an integer. EBADARGUMENT argument is incorrect EBADSTATE called from inappropriate routine ECONNECTED object is connected ECURRENT field is current field EINVALIDFIELD field is invalid ENOROOM form does not fit in subwindow ENOTCONNECTED object is not connected EOK function returned successfully EPOSTED form is posted EREQUESTDENIED recognized request failed ESYSTEMERROR system error EUNKNOWNCOMMAND unknown command was given to the form driver Standards conformance form is not part of any currently supported standard; it is an extension of AT&T System V provided by the Santa Cruz Operation.