ncurses 4.2
[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>form</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>form</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>form</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>form</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>form</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        current_field  <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>  data_ahead     <STRONG><A HREF="form_data.3x.html">form_data(3X)</A></STRONG>
42        data_behind    <STRONG><A HREF="form_data.3x.html">form_data(3X)</A></STRONG>  dup_field <STRONG><A HREF="form_field_new.3x.html">form_field_new(3X)</A></STRONG>
43        dynamic_fieldinfo   <STRONG><A HREF="form_field_info.3x.html">form_field_info(3X)</A></STRONG>
44        field_arg <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3X)</A></STRONG>
45        field_back     <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
46        field_buffer   <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
47        field_count    <STRONG><A HREF="form_field.3x.html">form_field(3X)</A></STRONG>
48        field_fore     <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
49        field_index    <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>
50        field_info     <STRONG><A HREF="form_field_info.3x.html">form_field_info(3X)</A></STRONG>
51        field_init     <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
52        field_just     <STRONG><A HREF="form_field_just.3x.html">form_field_just(3X)</A></STRONG>
53        field_opts     <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
54        field_opts_off <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
55        field_opts_on  <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
56        field_pad <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
57        field_status   <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
58        field_term     <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
59        field_type     <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3X)</A></STRONG>
60        form_fields    <STRONG><A HREF="form_field.3x.html">form_field(3X)</A></STRONG>      form_init <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
61        form_opts <STRONG><A HREF="form_opts.3x.html">form_opts(3X)</A></STRONG>       form_opts_off  <STRONG><A HREF="form_opts.3x.html">form_opts(3X)</A></STRONG>
62        form_opts_on   <STRONG><A HREF="form_opts.3x.html">form_opts(3X)</A></STRONG>       form_page <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>
63        form_request_by_name     <STRONG><A HREF="form_requestname.3x.html">form_requestname(3X)</A></STRONG>
64        form_request_name   <STRONG><A HREF="form_requestname.3x.html">form_requestname(3X)</A></STRONG>
65        form_sub  <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>             form_term <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
66        form_userptr   <STRONG><A HREF="form_userptr.3x.html">form_userptr(3X)</A></STRONG>     form_win  <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>
67        free_field     <STRONG><A HREF="form_field_new.3x.html">form_field_new(3X)</A></STRONG>   free_form <STRONG><A HREF="form_new.3x.html">form_new(3X)</A></STRONG>
68        link_field     <STRONG><A HREF="form_field_new.3x.html">form_field_new(3X)</A></STRONG>
69        link_fieldtype <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3X)</A></STRONG>
70        move_field     <STRONG><A HREF="form_field.3x.html">form_field(3X)</A></STRONG> new_field <STRONG><A HREF="form_field_new.3x.html">form_field_new(3X)</A></STRONG>
71        new_form  <STRONG><A HREF="form_new.3x.html">form_new(3X)</A></STRONG>         new_page  <STRONG><A HREF="form_new_page.3x.html">form_new_page(3X)</A></STRONG>
72        pos_form_cursor     <STRONG><A HREF="form_cursor.3x.html">form_cursor(3X)</A></STRONG>
73        post_form <STRONG><A HREF="form_post.3x.html">form_post(3X)</A></STRONG>        scale_form     <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>
74        set_current_field   <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>
75        set_field_back <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
76        set_field_buffer    <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
77        set_field_fore <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
78        set_field_init <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
79        set_field_just <STRONG><A HREF="form_field_just.3x.html">form_field_just(3X)</A></STRONG>
80        set_field_opts <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
81        set_field_pad  <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3X)</A></STRONG>
82        set_field_status    <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
83        set_field_term <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
84        set_field_type <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3X)</A></STRONG>
85        set_field_userptr   <STRONG><A HREF="form_field_userptr.3x.html">form_field_userptr(3X)</A></STRONG>
86        set_fieldtype_arg   <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3X)</A></STRONG>
87        set_fieldtype_choice     <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3X)</A></STRONG>
88        set_form_fields     <STRONG><A HREF="form_field.3x.html">form_field(3X)</A></STRONG>
89        set_form_init  <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
90        set_form_opts  <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3X)</A></STRONG>
91        set_form_page  <STRONG><A HREF="form_page.3x.html">form_page(3X)</A></STRONG>   set_form_sub   <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>
92        set_form_term  <STRONG><A HREF="form_hook.3x.html">form_hook(3X)</A></STRONG>
93        set_form_userptr    <STRONG><A HREF="form_userptr.3x.html">form_userptr(3X)</A></STRONG>
94        set_form_win   <STRONG><A HREF="form_win.3x.html">form_win(3X)</A></STRONG>
95        set_max_field  <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3X)</A></STRONG>
96        set_new_page   <STRONG><A HREF="form_new_page.3x.html">form_new_page(3X)</A></STRONG>
97        unpost_form    <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>