ncurses 6.0 - patch 20161112
[ncurses.git] / man / form.3x
index 51c1e8c15d5afb58b18522e9c82df2890a2baa66..c21f857b3a4540b8312690e5b7a5a86238840e89 100644 (file)
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc.                        *
+.\" Copyright (c) 1998-2015,2016 Free Software Foundation, Inc.              *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: form.3x,v 1.13 1999/07/10 21:53:03 tom Exp $
+.\" $Id: form.3x,v 1.28 2016/10/29 22:26:35 tom Exp $
 .TH form 3X ""
 .SH NAME
-\fBform\fR - curses extension for programming forms
+\fBform\fR \- curses extension for programming forms
 .SH SYNOPSIS
 \fB#include <form.h>\fR
 .br
@@ -40,26 +40,34 @@ 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 interaction with the
 user.
-
-The \fBform\fR library uses the \fBcurses\fR libraries, and a curses
-initialization routine such as \fBinitscr\fR must be called before using any of
-these functions.  To use the \fBform\fR library, link with the options
-\fB-lform -lcurses\fR.
-
+.PP
+The \fBform\fR library uses the \fBcurses\fR libraries.
+To use the \fBform\fR library, link with the options
+\fB\-lform \-lcurses\fR.
+.PP
+Your program should set up the locale, e.g.,
+.sp
+     \fBsetlocale(LC_ALL, "");\fP
+.sp
+so that input/output processing will work.
+.PP
+A curses initialization routine such as \fBinitscr\fR must be called
+before using any of these functions.
+.
 .SS Current Default Values for Field Attributes
-
+.
 The \fBform\fR library maintains a default value for field attributes.  You
 can get or set this default by calling the appropriate \fBset_\fR
 or retrieval
 routine with a \fBNULL\fR field pointer.  Changing this default with a
 \fBset_\fR function affects future field creations, but does not change the
 rendering of fields already created.
-
+.
 .SS Routine Name Index
-
+.
 The following table lists each \fBform\fR routine and the name of
 the manual page on which it is described.
-
+.
 .TS
 l l
 l l .
@@ -69,7 +77,7 @@ current_field \fBform_page\fR(3X)
 data_ahead     \fBform_data\fR(3X)
 data_behind    \fBform_data\fR(3X)
 dup_field      \fBform_field_new\fR(3X)
-dynamic_fieldinfo      \fBform_field_info\fR(3X)
+dynamic_field_info     \fBform_field_info\fR(3X)
 field_arg      \fBform_field_validation\fR(3X)
 field_back     \fBform_field_attributes\fR(3X)
 field_buffer   \fBform_field_buffer\fR(3X)
@@ -88,6 +96,7 @@ field_term    \fBform_hook\fR(3X)
 field_type     \fBform_field_validation\fR(3X)
 field_userptr  \fBform_field_userptr\fR(3X)
 form_driver    \fBform_driver\fR(3X)
+form_driver_w  \fBform_driver\fR(3X)*
 form_fields    \fBform_field\fR(3X)
 form_init      \fBform_hook\fR(3X)
 form_opts      \fBform_opts\fR(3X)
@@ -101,11 +110,13 @@ form_term \fBform_hook\fR(3X)
 form_userptr   \fBform_userptr\fR(3X)
 form_win       \fBform_win\fR(3X)
 free_field     \fBform_field_new\fR(3X)
+free_fieldtype \fBform_fieldtype\fR(3X)
 free_form      \fBform_new\fR(3X)
 link_field     \fBform_field_new\fR(3X)
 link_fieldtype \fBform_fieldtype\fR(3X)
 move_field     \fBform_field\fR(3X)
 new_field      \fBform_field_new\fR(3X)
+new_fieldtype  \fBform_fieldtype\fR(3X)
 new_form       \fBform_new\fR(3X)
 new_page       \fBform_new_page\fR(3X)
 pos_form_cursor        \fBform_cursor\fR(3X)
@@ -135,66 +146,71 @@ set_form_userptr  \fBform_userptr\fR(3X)
 set_form_win   \fBform_win\fR(3X)
 set_max_field  \fBform_field_buffer\fR(3X)
 set_new_page   \fBform_new_page\fR(3X)
+unfocus_current_field  \fBform_page\fR(3X)
 unpost_form    \fBform_post\fR(3X)
 .TE
 .SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error.  Routines that return
+Routines that return pointers return \fBNULL\fR 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:
 .TP 5
-\fBE_OK\fR
+.B E_OK
 The routine succeeded.
 .TP 5
-\fBE_CONNECTED\fR
-The field is already connected to a form.
-.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
 Routine detected an incorrect or out-of-range argument.
 .TP 5
-\fBE_POSTED\fR
-The form is already posted.
-.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
 Routine was called from an initialization or termination function.
 .TP 5
-\fBE_NO_ROOM\fR
-Form is too large for its window.
-.TP 5
-\fBE_NOT_POSTED\fR
-The form has not been posted.
-.TP 5
-\fBE_UNKNOWN_COMMAND\fR
-The form driver code saw an unknown request code.
+.B E_CONNECTED
+The field is already connected to a form.
 .TP 5
-\fBE_INVALID_FIELD\fR
+.B E_INVALID_FIELD
 Contents of a field are not valid.
 .TP 5
-\fBE_NOT_CONNECTED\fR
+.B E_NOT_CONNECTED
 No fields are connected to the form.
 .TP 5
-\fBE_REQUEST_DENIED\fR
+.B E_NOT_POSTED
+The form has not been posted.
+.TP 5
+.B E_NO_ROOM
+Form is too large for its window.
+.TP 5
+.B E_POSTED
+The form is already posted.
+.TP 5
+.B E_REQUEST_DENIED
 The form driver could not process the request.
-.SH SEE ALSO
-\fBcurses\fR(3X) and 3X pages whose names begin "form_" for detailed
-descriptions of the entry points.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.TP 5
+.B E_UNKNOWN_COMMAND
+The form driver code saw an unknown request code.
 .SH NOTES
 The header file \fB<form.h>\fR automatically includes the header files
 \fB<curses.h>\fR and \fB<eti.h>\fR.
-
+.PP
 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 using GNU \fBld\fR(1) and many other linkers).
+you want to say `\-lform \-lncurses', not the other way around (which would
+give you a link error using most linkers).
 .SH PORTABILITY
 These routines emulate the System V forms library.  They were not supported on
 Version 7 or BSD versions.
+.PP
+A few functions are extensions added for ncurses, e.g.,
+\fBform_driver_w\fP,
+\fBunfocus_current_field\fP.
 .SH AUTHORS
 Juergen Pfeifer.  Manual pages and adaptation for ncurses by Eric
 S. Raymond.
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+.SH SEE ALSO
+\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
+descriptions of the entry points.
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).