| 1 |
'\" t |
| 2 |
.\"*************************************************************************** |
| 3 |
.\" Copyright 2018-2024,2025 Thomas E. Dickey * |
| 4 |
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * |
| 5 |
.\" * |
| 6 |
.\" Permission is hereby granted, free of charge, to any person obtaining a * |
| 7 |
.\" copy of this software and associated documentation files (the * |
| 8 |
.\" "Software"), to deal in the Software without restriction, including * |
| 9 |
.\" without limitation the rights to use, copy, modify, merge, publish, * |
| 10 |
.\" distribute, distribute with modifications, sublicense, and/or sell * |
| 11 |
.\" copies of the Software, and to permit persons to whom the Software is * |
| 12 |
.\" furnished to do so, subject to the following conditions: * |
| 13 |
.\" * |
| 14 |
.\" The above copyright notice and this permission notice shall be included * |
| 15 |
.\" in all copies or substantial portions of the Software. * |
| 16 |
.\" * |
| 17 |
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| 18 |
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| 19 |
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| 20 |
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| 21 |
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| 22 |
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| 23 |
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| 24 |
.\" * |
| 25 |
.\" Except as contained in this notice, the name(s) of the above copyright * |
| 26 |
.\" holders shall not be used in advertising or otherwise to promote the * |
| 27 |
.\" sale, use or other dealings in this Software without prior written * |
| 28 |
.\" authorization. * |
| 29 |
.\"*************************************************************************** |
| 30 |
.\" |
| 31 |
.\" $Id: form.3x,v 1.62 2025/11/12 01:27:41 tom Exp $ |
| 32 |
.TH form 3FORM 2025-11-11 "ncurses 6.6" "Library calls" |
| 33 |
.ie \n(.g \{\ |
| 34 |
.ds `` \(lq |
| 35 |
.ds '' \(rq |
| 36 |
.\} |
| 37 |
.el \{\ |
| 38 |
.ie t .ds `` `` |
| 39 |
.el .ds `` "" |
| 40 |
.ie t .ds '' '' |
| 41 |
.el .ds '' "" |
| 42 |
.\} |
| 43 |
. |
| 44 |
.de bP |
| 45 |
.ie n .IP \(bu 4 |
| 46 |
.el .IP \(bu 2 |
| 47 |
.. |
| 48 |
.SH NAME |
| 49 |
\fBform\fP \- |
| 50 |
present user-fillable forms in \fIcurses\fP windows |
| 51 |
.SH SYNOPSIS |
| 52 |
.nf |
| 53 |
\fB#include <form.h> |
| 54 |
.fi |
| 55 |
.SH DESCRIPTION |
| 56 |
The \fBform\fP library provides terminal-independent facilities for composing |
| 57 |
form screens on character-cell terminals. |
| 58 |
The library includes: field |
| 59 |
routines, which create and modify form fields; and form routines, which group |
| 60 |
fields into forms, display forms on the screen, and handle interaction with the |
| 61 |
user. |
| 62 |
.PP |
| 63 |
The \fBform\fP library uses the \fBcurses\fP libraries. |
| 64 |
To use the \fBform\fP library, link with the options |
| 65 |
\fB\-lform \-lcurses\fP. |
| 66 |
.PP |
| 67 |
Your program should set up the locale, e.g., |
| 68 |
.sp |
| 69 |
\fBsetlocale(LC_ALL, "");\fP |
| 70 |
.sp |
| 71 |
so that input/output processing will work. |
| 72 |
.PP |
| 73 |
A curses initialization routine such as \fBinitscr\fP must be called |
| 74 |
before using any of these functions. |
| 75 |
. |
| 76 |
.SS "Current Default Values for Field Attributes" |
| 77 |
. |
| 78 |
The \fBform\fP library maintains a default value for field attributes. |
| 79 |
You |
| 80 |
can get or set this default by calling the appropriate \fBset_\fP |
| 81 |
or retrieval |
| 82 |
routine with a |
| 83 |
.I NULL |
| 84 |
field pointer. |
| 85 |
Changing this default with a |
| 86 |
\fBset_\fP function affects future field creations, but does not change the |
| 87 |
rendering of fields already created. |
| 88 |
. |
| 89 |
.SS "Routine Name Index" |
| 90 |
. |
| 91 |
The following table lists each \fBform\fP routine and the name of |
| 92 |
the manual page on which it is described. |
| 93 |
Routines flagged with \*(``*\*('' |
| 94 |
are \fI\%ncurses\fP-specific, not present in SVr4. |
| 95 |
.PP |
| 96 |
.TS |
| 97 |
L L. |
| 98 |
\fBcurses\fP Routine Name Manual Page Name |
| 99 |
_ |
| 100 |
current_field \fBpage\fP(3FORM) |
| 101 |
data_ahead \fBdata\fP(3FORM) |
| 102 |
data_behind \fBdata\fP(3FORM) |
| 103 |
dup_field \fBfield_new\fP(3FORM) |
| 104 |
dynamic_field_info \fBfield_info\fP(3FORM) |
| 105 |
field_arg \fBfield_validation\fP(3FORM) |
| 106 |
field_back \fBfield_attributes\fP(3FORM) |
| 107 |
field_buffer \fBfield_buffer\fP(3FORM) |
| 108 |
field_count \fBfield\fP(3FORM) |
| 109 |
field_fore \fBfield_attributes\fP(3FORM) |
| 110 |
field_index \fBpage\fP(3FORM) |
| 111 |
field_info \fBfield_info\fP(3FORM) |
| 112 |
field_init \fBhook\fP(3FORM) |
| 113 |
field_just \fBfield_just\fP(3FORM) |
| 114 |
field_opts \fBfield_opts\fP(3FORM) |
| 115 |
field_opts_off \fBfield_opts\fP(3FORM) |
| 116 |
field_opts_on \fBfield_opts\fP(3FORM) |
| 117 |
field_pad \fBfield_attributes\fP(3FORM) |
| 118 |
field_status \fBfield_buffer\fP(3FORM) |
| 119 |
field_term \fBhook\fP(3FORM) |
| 120 |
field_type \fBfield_validation\fP(3FORM) |
| 121 |
field_userptr \fBfield_userptr\fP(3FORM) |
| 122 |
form_driver \fBdriver\fP(3FORM) |
| 123 |
form_driver_w \fBdriver\fP(3FORM)* |
| 124 |
form_fields \fBfield\fP(3FORM) |
| 125 |
form_init \fBhook\fP(3FORM) |
| 126 |
form_opts \fBopts\fP(3FORM) |
| 127 |
form_opts_off \fBopts\fP(3FORM) |
| 128 |
form_opts_on \fBopts\fP(3FORM) |
| 129 |
form_page \fBpage\fP(3FORM) |
| 130 |
form_request_by_name \fBrequestname\fP(3FORM)* |
| 131 |
form_request_name \fBrequestname\fP(3FORM)* |
| 132 |
form_sub \fBwin\fP(3FORM) |
| 133 |
form_term \fBhook\fP(3FORM) |
| 134 |
form_userptr \fBuserptr\fP(3FORM) |
| 135 |
form_win \fBwin\fP(3FORM) |
| 136 |
free_field \fBfield_new\fP(3FORM) |
| 137 |
free_fieldtype \fBfieldtype\fP(3FORM) |
| 138 |
free_form \fBnew\fP(3FORM) |
| 139 |
link_field \fBfield_new\fP(3FORM) |
| 140 |
link_fieldtype \fBfieldtype\fP(3FORM) |
| 141 |
move_field \fBfield\fP(3FORM) |
| 142 |
new_field \fBfield_new\fP(3FORM) |
| 143 |
new_fieldtype \fBfieldtype\fP(3FORM) |
| 144 |
new_form \fBnew\fP(3FORM) |
| 145 |
new_page \fBnew_page\fP(3FORM) |
| 146 |
pos_form_cursor \fBcursor\fP(3FORM) |
| 147 |
post_form \fBpost\fP(3FORM) |
| 148 |
scale_form \fBwin\fP(3FORM) |
| 149 |
set_current_field \fBpage\fP(3FORM) |
| 150 |
set_field_back \fBfield_attributes\fP(3FORM) |
| 151 |
set_field_buffer \fBfield_buffer\fP(3FORM) |
| 152 |
set_field_fore \fBfield_attributes\fP(3FORM) |
| 153 |
set_field_init \fBhook\fP(3FORM) |
| 154 |
set_field_just \fBfield_just\fP(3FORM) |
| 155 |
set_field_opts \fBfield_opts\fP(3FORM) |
| 156 |
set_field_pad \fBfield_attributes\fP(3FORM) |
| 157 |
set_field_status \fBfield_buffer\fP(3FORM) |
| 158 |
set_field_term \fBhook\fP(3FORM) |
| 159 |
set_field_type \fBfield_validation\fP(3FORM) |
| 160 |
set_field_userptr \fBfield_userptr\fP(3FORM) |
| 161 |
set_fieldtype_arg \fBfieldtype\fP(3FORM) |
| 162 |
set_fieldtype_choice \fBfieldtype\fP(3FORM) |
| 163 |
set_form_fields \fBfield\fP(3FORM) |
| 164 |
set_form_init \fBhook\fP(3FORM) |
| 165 |
set_form_opts \fBfield_opts\fP(3FORM) |
| 166 |
set_form_page \fBpage\fP(3FORM) |
| 167 |
set_form_sub \fBwin\fP(3FORM) |
| 168 |
set_form_term \fBhook\fP(3FORM) |
| 169 |
set_form_userptr \fBuserptr\fP(3FORM) |
| 170 |
set_form_win \fBwin\fP(3FORM) |
| 171 |
set_max_field \fBfield_buffer\fP(3FORM) |
| 172 |
set_new_page \fBnew_page\fP(3FORM) |
| 173 |
unfocus_current_field \fBpage\fP(3FORM)* |
| 174 |
unpost_form \fBpost\fP(3FORM) |
| 175 |
.TE |
| 176 |
.SH RETURN VALUE |
| 177 |
Routines that return pointers return |
| 178 |
.I NULL |
| 179 |
on error, |
| 180 |
and set \fBerrno\fP to the corresponding error-code returned by functions |
| 181 |
returning an integer. |
| 182 |
Routines that return |
| 183 |
an integer return one of the following error codes: |
| 184 |
.TP 5 |
| 185 |
.B E_OK |
| 186 |
The routine succeeded. |
| 187 |
.TP 5 |
| 188 |
.B E_BAD_ARGUMENT |
| 189 |
Routine detected an incorrect or out-of-range argument. |
| 190 |
.TP 5 |
| 191 |
.B E_BAD_STATE |
| 192 |
Routine was called from an initialization or termination function. |
| 193 |
.TP 5 |
| 194 |
.B E_CONNECTED |
| 195 |
The field is already connected to a form. |
| 196 |
.TP 5 |
| 197 |
.B E_INVALID_FIELD |
| 198 |
Contents of a field are not valid. |
| 199 |
.TP 5 |
| 200 |
.B E_NOT_CONNECTED |
| 201 |
No fields are connected to the form. |
| 202 |
.TP 5 |
| 203 |
.B E_NOT_POSTED |
| 204 |
The form has not been posted. |
| 205 |
.TP 5 |
| 206 |
.B E_NO_ROOM |
| 207 |
Form is too large for its window. |
| 208 |
.TP 5 |
| 209 |
.B E_POSTED |
| 210 |
The form is already posted. |
| 211 |
.TP 5 |
| 212 |
.B E_REQUEST_DENIED |
| 213 |
The form driver could not process the request. |
| 214 |
.TP 5 |
| 215 |
.B E_SYSTEM_ERROR |
| 216 |
System error occurred (see \fBerrno\fP(3)). |
| 217 |
.TP 5 |
| 218 |
.B E_UNKNOWN_COMMAND |
| 219 |
The form driver code saw an unknown request code. |
| 220 |
.SH NOTES |
| 221 |
The header file \fI\%form.h\fP itself includes \fI\%curses.h\fP. |
| 222 |
.SH PORTABILITY |
| 223 |
These routines emulate the System V forms library. |
| 224 |
They were not supported on |
| 225 |
Version 7 or BSD versions. |
| 226 |
.PP |
| 227 |
A form facility was documented in SVr4.2's |
| 228 |
\fICharacter User Interface Programming\fP document. |
| 229 |
.PP |
| 230 |
It is not part of X/Open Curses. |
| 231 |
.PP |
| 232 |
Aside from \fI\%ncurses\fP, there are few implementations: |
| 233 |
.bP |
| 234 |
systems based on SVr4 source code, e.g., Solaris. |
| 235 |
.bP |
| 236 |
NetBSD curses. |
| 237 |
.PP |
| 238 |
A few functions in this implementation are extensions added for |
| 239 |
\fI\%ncurses\fP, |
| 240 |
but not provided by other implementations, e.g., |
| 241 |
\fBform_driver_w\fP, |
| 242 |
\fBunfocus_current_field\fP. |
| 243 |
.SH AUTHORS |
| 244 |
Juergen Pfeifer. |
| 245 |
Manual pages and adaptation for \fI\%ncurses\fP by Eric |
| 246 |
S. Raymond. |
| 247 |
.SH SEE ALSO |
| 248 |
\fBncurses\fP(3NCURSES) and related pages whose names begin \*(``form_\*('' for |
| 249 |
detailed descriptions of the entry points. |