ncurses 4.1
[ncurses.git] / Ada95 / html / form.3x.html
1 <HTML>
2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
3 <PRE>
4        <STRONG>forms</STRONG> - curses extension for programming forms
5
6
7 </PRE>
8 <H2>SYNOPSIS</H2><PRE>
9        <STRONG>#include</STRONG> <STRONG>&lt;form.h&gt;</STRONG>
10
11
12 </PRE>
13 <H2>DESCRIPTION</H2><PRE>
14        The <STRONG>forms</STRONG> library provides terminal-independent facilities
15        for composing form screens  on  character-cell  terminals.
16        The  library  includes:  field  routines, which create and
17        modify form fields; and form routines, which group  fields
18        into forms, display forms on the screen, and handle inter-
19        action with the user.
20
21        The <STRONG>forms</STRONG> library uses the <STRONG>curses</STRONG> libraries, and a  curses
22        initialization  routine  such  as  <STRONG>initscr</STRONG>  must be called
23        before using any of these functions.   To  use  the  <STRONG>forms</STRONG>
24        library, link with the options <STRONG>-lform</STRONG> <STRONG>-lcurses</STRONG>.
25
26
27    <STRONG>Current</STRONG> <STRONG>Default</STRONG> <STRONG>Values</STRONG> <STRONG>for</STRONG> <STRONG>Field</STRONG> <STRONG>Attributes</STRONG>
28        The  <STRONG>forms</STRONG>  library  maintains  a  default value for field
29        attributes.  You can get or set this  default  by  calling
30        the  appropriate  <STRONG>get_</STRONG>  or  <STRONG>set_</STRONG> routine with a <STRONG>NULL</STRONG> field
31        pointer.  Changing  this  default  with  a  <STRONG>set_</STRONG>  function
32        affects  future  field  creations, but does not change the
33        rendering of fields already created.
34
35
36    <STRONG>Routine</STRONG> <STRONG>Name</STRONG> <STRONG>Index</STRONG>
37        The following table lists each <STRONG>form</STRONG> routine and  the  name
38        of the manual page on which it is described.
39
40        l  l  l  l  .   <STRONG>curses</STRONG>  Routine  Name Manual  Page  Name =
41        <STRONG>current_field</STRONG>  <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>  <STRONG>data_ahead</STRONG>     <STRONG><A HREF="form_data.3x.html">form_data(3X)</A></STRONG>
42        <STRONG>data_behind</STRONG>    <STRONG><A HREF="form_data.3x.html">form_data(3X)</A></STRONG>  <STRONG>dup_field</STRONG> <STRONG><A HREF="form_field_new.3x.html">form_field_new(3X)</A></STRONG>
43        <STRONG>dynamic_fieldinfo</STRONG>   <STRONG><A HREF="form_field_info.3x.html">form_field_info(3X)</A></STRONG>
44        <STRONG>field_arg</STRONG> <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3X)</A></STRONG>
45        <STRONG>field_back</STRONG>     <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
46        <STRONG>field_buffer</STRONG>   <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
47        <STRONG>field_count</STRONG>    <STRONG><A HREF="form_field.3x.html">form_field(3X)</A></STRONG>
48        <STRONG>field_fore</STRONG>     <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
49        <STRONG>field_index</STRONG>    <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>
50        <STRONG>field_info</STRONG>     <STRONG><A HREF="form_field_info.3x.html">form_field_info(3X)</A></STRONG>
51        <STRONG>field_init</STRONG>     <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
52        <STRONG>field_just</STRONG>     <STRONG><A HREF="form_field_just.3x.html">form_field_just(3X)</A></STRONG>
53        <STRONG>field_opts</STRONG>     <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
54        <STRONG>field_opts_off</STRONG> <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
55        <STRONG>field_opts_on</STRONG>  <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
56        <STRONG>field_pad</STRONG> <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
57        <STRONG>field_status</STRONG>   <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
58        <STRONG>field_term</STRONG>     <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
59        <STRONG>field_type</STRONG>     <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3X)</A></STRONG>
60        <STRONG>form_fields</STRONG>    <STRONG><A HREF="form_field.3x.html">form_field(3X)</A></STRONG>      <STRONG>form_init</STRONG> <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
61        <STRONG>form_opts</STRONG> <STRONG><A HREF="form_opts.3x.html">form_opts(3X)</A></STRONG>       <STRONG>form_opts_off</STRONG>  <STRONG><A HREF="form_opts.3x.html">form_opts(3X)</A></STRONG>
62        <STRONG>form_opts_on</STRONG>   <STRONG><A HREF="form_opts.3x.html">form_opts(3X)</A></STRONG>       <STRONG>form_page</STRONG> <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>
63        <STRONG>form_request_by_name</STRONG>     <STRONG><A HREF="form_requestname.3x.html">form_requestname(3X)</A></STRONG>
64        <STRONG>form_request_name</STRONG>   <STRONG><A HREF="form_requestname.3x.html">form_requestname(3X)</A></STRONG>
65        <STRONG>form_sub</STRONG>  <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>             <STRONG>form_term</STRONG> <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
66        <STRONG>form_userptr</STRONG>   <STRONG><A HREF="form_userptr.3x.html">form_userptr(3X)</A></STRONG>     <STRONG>form_win</STRONG>  <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>
67        <STRONG>free_field</STRONG>     <STRONG><A HREF="form_field_new.3x.html">form_field_new(3X)</A></STRONG>   <STRONG>free_form</STRONG> <STRONG><A HREF="form_new.3x.html">form_new(3X)</A></STRONG>
68        <STRONG>link_field</STRONG>     <STRONG><A HREF="form_field_new.3x.html">form_field_new(3X)</A></STRONG>
69        <STRONG>link_fieldtype</STRONG> <STRONG><A HREF="link_fieldtype.3x.html">link_fieldtype(3X)</A></STRONG>
70        <STRONG>move_field</STRONG>     <STRONG><A HREF="form_field.3x.html">form_field(3X)</A></STRONG> <STRONG>new_field</STRONG> <STRONG><A HREF="form_field_new.3x.html">form_field_new(3X)</A></STRONG>
71        <STRONG>new_form</STRONG>  <STRONG><A HREF="form_new.3x.html">form_new(3X)</A></STRONG>         <STRONG>new_page</STRONG>  <STRONG><A HREF="form_new_page.3x.html">form_new_page(3X)</A></STRONG>
72        <STRONG>pos_form_cursor</STRONG>     <STRONG><A HREF="form_cursor.3x.html">form_cursor(3X)</A></STRONG>
73        <STRONG>post_form</STRONG> <STRONG><A HREF="form_post.3x.html">form_post(3X)</A></STRONG>        <STRONG>scale_form</STRONG>     <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>
74        <STRONG>set_current_field</STRONG>   <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>
75        <STRONG>set_field_back</STRONG> <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
76        <STRONG>set_field_buffer</STRONG>    <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
77        <STRONG>set_field_fore</STRONG> <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
78        <STRONG>set_field_init</STRONG> <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
79        <STRONG>set_field_just</STRONG> <STRONG><A HREF="form_field_just.3x.html">form_field_just(3X)</A></STRONG>
80        <STRONG>set_field_opts</STRONG> <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
81        <STRONG>set_field_pad</STRONG>  <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
82        <STRONG>set_field_status</STRONG>    <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
83        <STRONG>set_field_term</STRONG> <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
84        <STRONG>set_field_type</STRONG> <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3X)</A></STRONG>
85        <STRONG>set_field_userptr</STRONG>   <STRONG><A HREF="form_field_userptr.3x.html">form_field_userptr(3X)</A></STRONG>
86        <STRONG>set_fieldtype_arg</STRONG>   <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3X)</A></STRONG>
87        <STRONG>set_fieldtype_choice</STRONG>     <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3X)</A></STRONG>
88        <STRONG>set_form_fields</STRONG>     <STRONG><A HREF="form_field.3x.html">form_field(3X)</A></STRONG>
89        <STRONG>set_form_init</STRONG>  <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
90        <STRONG>set_form_opts</STRONG>  <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
91        <STRONG>set_form_page</STRONG>  <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>   <STRONG>set_form_sub</STRONG>   <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>
92        <STRONG>set_form_term</STRONG>  <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
93        <STRONG>set_form_userptr</STRONG>    <STRONG><A HREF="form_userptr.3x.html">form_userptr(3X)</A></STRONG>
94        <STRONG>set_form_win</STRONG>   <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>
95        <STRONG>set_max_field</STRONG>  <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
96        <STRONG>set_new_page</STRONG>   <STRONG><A HREF="form_new_page.3x.html">form_new_page(3X)</A></STRONG>
97        <STRONG>unpost_form</STRONG>    <STRONG><A HREF="form_post.3x.html">form_post(3X)</A></STRONG>
98
99
100 </PRE>
101 <H2>RETURN VALUE</H2><PRE>
102        Routines that return pointers return <STRONG>NULL</STRONG> on error.   Rou-
103        tines  that  return an integer return one of the following
104        error codes:
105
106        <STRONG>E_OK</STRONG> The routine succeeded.
107
108        <STRONG>E_CONNECTED</STRONG>
109             The field is already connected to a form.
110
111        <STRONG>E_SYSTEM_ERROR</STRONG>
112             System error occurred (see <STRONG>errno</STRONG>).
113
114             Routine detected an incorrect or  out-of-range  argu-
115             ment.
116
117        <STRONG>E_POSTED</STRONG>
118             The form is already posted.
119
120        <STRONG>E_BAD_STATE</STRONG>
121             Routine was called from an initialization or termina-
122             tion function.
123
124        <STRONG>E_NO_ROOM</STRONG>
125             Form is too large for its window.
126
127        <STRONG>E_NOT_POSTED</STRONG>
128             The form has not been posted.
129
130        <STRONG>E_UNKNOWN_COMMAND</STRONG>
131             The form driver code saw an unknown request code.
132
133        <STRONG>E_INVALID_FIELD</STRONG>
134             Contents of a field are not valid.
135
136        <STRONG>E_NOT_CONNECTED</STRONG>
137             No fields are connected to the form.
138
139        <STRONG>E_REQUEST_DENIED</STRONG>
140             The form driver could not process the request.
141
142
143 </PRE>
144 <H2>SEE ALSO</H2><PRE>
145        <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG> and 3X pages  whose  names  begin  "form_"  for
146        detailed descriptions of the entry points.
147
148
149 </PRE>
150 <H2>NOTES</H2><PRE>
151        The header file <STRONG>&lt;form.h&gt;</STRONG> automatically includes the header
152        files <STRONG>&lt;curses.h&gt;</STRONG> and <STRONG>&lt;eti.h&gt;</STRONG>.
153
154        In your library list, libform.a  should  be  before  libn-
155        curses.a; that is, you want to say `-lform -lncurses', not
156        the other way around (which would give you  a  link  error
157        using GNU <STRONG><A HREF="ld.1.html">ld(1)</A></STRONG> and many other linkers).
158
159
160 </PRE>
161 <H2>PORTABILITY</H2><PRE>
162        These  routines  emulate the System V forms library.  They
163        were not supported on Version 7 or BSD versions.
164
165
166 </PRE>
167 <H2>AUTHORS</H2><PRE>
168        Juergen Pfeifer.  Manual pages and adaptation for  ncurses
169        by Eric S. Raymond.
170
171
172
173
174 </PRE>
175 </BODY>
176 </HTML>