FORMS(3)                NetBSD Library Functions Manual               FORMS(3)

NAME
     form -- form library

LIBRARY
     Curses Form Library (libform, -lform)

SYNOPSIS
     #include <form.h>

DESCRIPTION
     The form library provides a terminal independent form system using the
     curses(3) library.  Before using the form functions the terminal must be
     set up by curses(3) using the initscr() function or similar.  Programs
     using form functions must be linked with the curses(3) library -lcurses.

     The form library provides facilities for defining form fields, placing a
     form on the terminal screen, assign pre and post change operations and
     setting the attributes of both the form and its fields.

   Defining default attributes for forms and fields
     The form library allows any settable attribute or option of both the form
     and field objects to be defined such that any new form or field automati-
     cally inherits the value as default.  Setting the default value will not
     affect any field or form that has already been created but will be
     applied to subsequent objects.  To set the default attribute or option
     the set routine is passed a NULL pointer in the field or form parameter
     when calling the set routine.  The current default value can be retrieved
     by calling the get routine with a NULL pointer for the field or form
     parameter.

     Form Routine Name         Manual Page Name
     current_field             form_page(3)
     data_ahead                form_data(3)
     data_behind               form_data(3)
     dup_field                 form_field_new(3)
     dynamic_field_info        form_field_info(3)
     field_arg                 form_field_validation(3)
     field_back                form_field_attributes(3)
     field_buffer              form_field_buffer(3)
     field_count               form_field(3)
     field_fore                form_field_attributes(3)
     field_index               form_page(3)
     field_info                form_field_info(3)
     field_init                form_hook(3)
     field_just                form_field_just(3)
     field_opts                form_field_opts(3)
     field_opts_off            form_field_opts(3)
     field_opts_on             form_field_opts(3)
     field_pad                 form_field_attributes(3)
     field_status              form_field_buffer(3)
     field_term                form_hook(3)
     field_type                form_field_validation(3)
     field_userptr             form_field_userptr(3)
     form_driver               form_driver(3)
     form_fields               form_field(3)
     form_init                 form_hook(3)
     form_max_page             form_page(3)
     form_opts                 form_opts(3)
     form_opts_off             form_opts(3)
     form_opts_on              form_opts(3)
     form_page                 form_page(3)
     form_sub                  form_win(3)
     form_term                 form_hook(3)
     form_userptr              form_userptr(3)
     form_win                  form_win(3)
     free_field                form_field_new(3)
     free_fieldtype            form_fieldtype(3)
     free_form                 form_new(3)
     link_field                form_field_new(3)
     link_fieldtype            form_fieldtype(3)
     move_field                form_field(3)
     new_field                 form_field_new(3)
     new_fieldtype             form_fieldtype(3)
     new_form                  form_new(3)
     new_page                  form_new_page(3)
     pos_form_cursor           form_cursor(3)
     post_form                 form_post(3)
     scale_form                form_win(3)
     set_current_field         form_page(3)
     set_field_back            form_field_attributes(3)
     set_field_buffer          form_field_buffer(3)
     set_field_fore            form_field_attributes(3)
     set_field_init            form_hook(3)
     set_field_just            form_field_just(3)
     set_field_opts            form_field_opts(3)
     set_field_pad             form_field_attributes(3)
     set_field_printf          form_field_buffer(3)
     set_field_status          form_field_buffer(3)
     set_field_term            form_hook(3)
     set_field_type            form_field_validation(3)
     set_field_userptr         form_field_userptr(3)
     set_fieldtype_arg         form_fieldtype(3)
     set_fieldtype_choice      form_fieldtype(3)
     set_form_fields           form_field(3)
     set_form_init             form_hook(3)
     set_form_opts             form_opts(3)
     set_form_page             form_page(3)
     set_form_sub              form_win(3)
     set_form_term             form_hook(3)
     set_form_userptr          form_userptr(3)
     set_form_win              form_win(3)
     set_max_field             form_field_buffer(3)
     set_new_page              form_new_page(3)
     unpost_form               form_post(3)

RETURN VALUES
     Any function returning a string pointer will return NULL if an error
     occurs.  Functions returning an integer will return one of the following:

     E_OK                      The function was successful.
     E_SYSTEM_ERROR            There was a system error during the call.
     E_BAD_ARGUMENT            One or more of the arguments passed to the
                               function was incorrect.
     E_POSTED                  The form is already posted.
     E_CONNECTED               A field was already connected to a form.
     E_BAD_STATE               The function was called from within an
                               initialization or termination routine.
     E_NO_ROOM                 The form does not fit within the subwindow.
     E_NOT_POSTED              The form is not posted.
     E_UNKNOWN_COMMAND         The form driver does not recognize the request
                               passed to it.
     E_NOT_SELECTABLE          The field could not be selected.
     E_NOT_CONNECTED           The field is not connected to a form.
     E_REQUEST_DENIED          The form driver could not process the request.
     E_INVALID_FIELD           The field is invalid.
     E_CURRENT                 The field is the active one on the form.

SEE ALSO
     curses(3), menus(3)

NOTES
     This implementation of the forms library does depart in behavior subtly
     from the original AT&T implementation.  Some of the more notable depar-
     tures are:

     field wrapping     For multi-line fields the data will be wrapped as it
                        is entered, this does not happen in the AT&T implemen-
                        tation.
     buffer 0           In this implementation, the contents of buffer 0 are
                        always current regardless of whether the field has
                        been validated or not.
     circular fields    In the AT&T implementation fields are circular on a
                        page, that is, a next field from the last field will
                        go to the first field on the current page.  In this
                        implementation a next field request on the last field
                        of a page will result in the forms library positioning
                        the cursor on the first field of the next page.  If
                        the field is the last field in the form then going to
                        the next field will be denied, in the AT&T it would
                        result in the cursor being placed on the first field
                        of the first page.
     buffer returns     In this implementation only the data entered by the
                        user in the form field will be returned, unlike the
                        AT&T library which would return the contents of the
                        field padded to the size of the field with the pad
                        character.
     The TAB character  The handling of the TAB character in fields varies
                        between implementations.  In ncurses attempting to set
                        a field contents with a string containing a TAB will
                        result in an error and will not allow a TAB to be
                        entered into a field.  The AT&T library statically
                        converts tabs to the equivalent number of spaces when
                        the field buffer is set but the form driver will not
                        allow a TAB to be inserted into the field buffer.
                        This implementation allows TAB when setting the field
                        buffer and also will allow TAB to be inserted into a
                        field buffer via the form driver and correctly calcu-
                        lates the cursor position allowing for expansion of
                        the TAB character.
     set_field_printf   This function is a NetBSD extension and must not be
                        used in portable code.
     O_REFORMAT         This field option is a NetBSD extension and must not
                        be used in portable code.

NetBSD 5.0_STABLE              November 24, 2004             NetBSD 5.0_STABLE
