# 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)
           unfocus_current_field   form_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 inte-
           ger.  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 argument.

           E_BAD_STATE
                Routine was called from an initialization or termination 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(3)).

           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 libncurses.a; that is,
           you  want  to  say  "-lform -lncurses", not the other way around (which
           would give you a link error when using static libraries).

## PORTABILITY

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

           The  menu facility was documented in SVr4.2 in Character User Interface
           Programming (UNIX SVR4.2).

           It is not part of X/Open Curses.

           Aside from ncurses, there are few implementations:

           o   systems based on SVr4 source code, e.g., Solaris.

           o   NetBSD curses.

           A few  functions  in  this  implementation  are  extensions  added  for
           ncurses,   but   not   provided   by   other   implementations,   e.g.,
           form_driver_w, unfocus_current_field.

## 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.1 (patch 20191214).

                                                                          form(3x)