# form 3x

    form(3x)                                                       form(3x)

## NAME

           form - curses extension for programming forms

## SYNOPSIS

           #include <form.h>

## DESCRIPTION

           The  form library provides terminal-independent facilities
           for composing form screens  on  character-cell  terminals.
           The  library  includes:  field  routines, which create and
           modify form fields; and form routines, which group  fields
           into forms, display forms on the screen, and handle inter-
           action with the user.

           The form library uses the curses libraries.   To  use  the
           form library, link with the options -lform -lcurses.

           Your program should set up the locale, e.g.,

                setlocale(LC_ALL, "");

           so that input/output processing will work.

           A  curses  initialization  routine such as initscr must be
           called before using any of these functions.

### Current Default Values for Field Attributes

           The form library  maintains  a  default  value  for  field
           attributes.   You  can  get or set this default by calling
           the appropriate set_ or  retrieval  routine  with  a  NULL
           field pointer.  Changing this default with a set_ function
           affects future field creations, but does  not  change  the
           rendering of fields already created.

### Routine Name Index

           The  following  table lists each form routine and the name
           of the manual page on which it is described.

           curses Routine Name    Manual Page Name
           -------------------------------------------------
           current_field          form_page(3x)
           data_ahead             form_data(3x)
           data_behind            form_data(3x)
           dup_field              form_field_new(3x)
           dynamic_field_info     form_field_info(3x)
           field_arg              form_field_validation(3x)
           field_back             form_field_attributes(3x)
           field_buffer           form_field_buffer(3x)
           field_count            form_field(3x)
           field_fore             form_field_attributes(3x)
           field_index            form_page(3x)
           field_info             form_field_info(3x)
           field_init             form_hook(3x)
           field_just             form_field_just(3x)
           field_opts             form_field_opts(3x)
           field_opts_off         form_field_opts(3x)
           field_opts_on          form_field_opts(3x)
           field_pad              form_field_attributes(3x)
           field_status           form_field_buffer(3x)
           field_term             form_hook(3x)
           field_type             form_field_validation(3x)

           field_userptr          form_field_userptr(3x)
           form_driver            form_driver(3x)
           form_driver_w          form_driver(3x)*
           form_fields            form_field(3x)
           form_init              form_hook(3x)
           form_opts              form_opts(3x)
           form_opts_off          form_opts(3x)
           form_opts_on           form_opts(3x)
           form_page              form_page(3x)
           form_request_by_name   form_requestname(3x)
           form_request_name      form_requestname(3x)
           form_sub               form_win(3x)
           form_term              form_hook(3x)
           form_userptr           form_userptr(3x)
           form_win               form_win(3x)
           free_field             form_field_new(3x)
           free_fieldtype         form_fieldtype(3x)
           free_form              form_new(3x)
           link_field             form_field_new(3x)
           link_fieldtype         form_fieldtype(3x)
           move_field             form_field(3x)
           new_field              form_field_new(3x)
           new_fieldtype          form_fieldtype(3x)
           new_form               form_new(3x)
           new_page               form_new_page(3x)
           pos_form_cursor        form_cursor(3x)
           post_form              form_post(3x)
           scale_form             form_win(3x)
           set_current_field      form_page(3x)
           set_field_back         form_field_attributes(3x)
           set_field_buffer       form_field_buffer(3x)
           set_field_fore         form_field_attributes(3x)
           set_field_init         form_hook(3x)
           set_field_just         form_field_just(3x)
           set_field_opts         form_field_opts(3x)
           set_field_pad          form_field_attributes(3x)
           set_field_status       form_field_buffer(3x)
           set_field_term         form_hook(3x)
           set_field_type         form_field_validation(3x)
           set_field_userptr      form_field_userptr(3x)
           set_fieldtype_arg      form_fieldtype(3x)
           set_fieldtype_choice   form_fieldtype(3x)
           set_form_fields        form_field(3x)
           set_form_init          form_hook(3x)
           set_form_opts          form_field_opts(3x)
           set_form_page          form_page(3x)
           set_form_sub           form_win(3x)
           set_form_term          form_hook(3x)
           set_form_userptr       form_userptr(3x)
           set_form_win           form_win(3x)
           set_max_field          form_field_buffer(3x)
           set_new_page           form_new_page(3x)
           unpost_form            form_post(3x)

## RETURN VALUE

           Routines that return pointers return NULL  on  error,  and
           set  errno  to  the  corresponding  error-code returned by
           functions returning an integer.  Routines that  return  an
           integer return one of the following error codes:

           E_OK The routine succeeded.

           E_BAD_ARGUMENT
                Routine  detected  an incorrect or out-of-range argu-
                ment.

           E_BAD_STATE
                Routine was called from an initialization or termina-
                tion function.

           E_CONNECTED
                The field is already connected to a form.

           E_INVALID_FIELD
                Contents of a field are not valid.

           E_NOT_CONNECTED
                No fields are connected to the form.

           E_NOT_POSTED
                The form has not been posted.

           E_NO_ROOM
                Form is too large for its window.

           E_POSTED
                The form is already posted.

           E_REQUEST_DENIED
                The form driver could not process the request.

           E_SYSTEM_ERROR
                System error occurred (see errno).

           E_UNKNOWN_COMMAND
                The form driver code saw an unknown request code.

## NOTES

           The header file <form.h> automatically includes the header
           files <curses.h> and <eti.h>.

           In your library list, libform.a  should  be  before  libn-
           curses.a; that is, you want to say `-lform -lncurses', not
           the other way around (which would give you  a  link  error
           using most linkers).

## PORTABILITY

           These  routines  emulate the System V forms library.  They
           were not supported on Version 7 or BSD versions.

## AUTHORS

           Juergen Pfeifer.  Manual pages and adaptation for  ncurses
           by Eric S. Raymond.

## SEE ALSO

           curses(3x) and related pages whose names begin "form_" for
           detailed descriptions of the entry points.

           This describes ncurses version 6.0 (patch 20150808).

                                                                   form(3x)