ncurses 5.1
[ncurses.git] / doc / html / man / form_fieldtype.3x.html
1 <HTML>
2 <BODY>
3 <PRE>
4 <!-- Manpage converted by man2html 3.0.1 -->
5
6 </PRE>
7 <H2>NAME</H2><PRE>
8        <B>form_fieldtype</B> - define validation-field types
9
10
11 </PRE>
12 <H2>SYNOPSIS</H2><PRE>
13        <B>#include</B> <B>&lt;form.h&gt;</B>
14        FIELDTYPE *new_fieldtype(
15            bool (* const field_check)(FIELD *, const void *),
16            bool (* const char_check)(int, const void *));
17        int free_fieldtype(FIELDTYPE *fieldtype);
18        int set_fieldtype_arg(
19            FIELDTYPE *fieldtype,
20            void *(* const make_arg)(va_list *),
21            void *(* const copy_arg)(const void *),
22            void  (* const free_arg)(void *));
23        int set_fieldtype_choice(
24            FIELDTYPE *fieldtype
25            bool (* const next_choice)(FIELD *, const void *),
26            bool (* const prev_choice)(FIELD *, const void *));
27        FIELDTYPE *link_fieldtype(FIELDTYPE *type1,
28                                  FIELDTYPE *type2);
29
30
31 </PRE>
32 <H2>DESCRIPTION</H2><PRE>
33        The function <B>new_fieldtype</B> creates a new field type usable
34        for data validation.  You supply it  with  <I>field</I><B>_</B><I>check</I>,  a
35        predicate  to check the validity of an entered data string
36        whenever the user attempt to leave a field.  The (FIELD *)
37        argument  is passed in so the validation predicate can see
38        the field's buffer, sizes and other attributes; the second
39        argument  is an argument-block structure, about which more
40        below.
41
42        You also supply <B>new_fieldtype</B> with <I>char</I><B>_</B><I>check</I>, a  function
43        to  validate input characters as they are entered; it will
44        be passed the character to be checked and a pointer to  an
45        argument-block structure.
46
47        The  function <B>free_fieldtype</B> frees the space allocated for
48        a given validation type.
49
50        The function <B>set_fieldtype</B> associates  three  storage-man-
51        agement functions with a field type.  The <I>mak</I><B>_</B><I>arg</I> function
52        is automatically applied to the list of arguments you give
53        <B>set_field_type</B>  when  attaching validation to a field; its
54        job is to bundle these into  an  allocated  argument-block
55        object which can later be passed to validation predicated.
56        The other two hook arguments should copy  and  free  argu-
57        ment-block  structures.   They  will be used by the forms-
58        driver code. You must supply  the  <I>mak</I><B>_</B><I>arg</I>  function,  the
59        other  two  are optional, you may supply NULL for them. In
60        this case it is assumed,  that  <I>mak</I><B>_</B><I>arg</I>  doesn't  allocate
61        memory  but simply loads the argument into a single scalar
62        value.
63
64        The   form    driver    requests    <B>REQ_NEXT_CHOICE</B>    and
65        <B>REQ_PREV_CHOICE</B> assume that the possible values of a field
66        form an ordered set, and provide the forms user with a way
67        to  move  through the set.  The <B>set_fieldtype_choice</B> func-
68        tion allows forms programmers to define successor and pre-
69        decessor  functions  for  the field type.  These functions
70        take the field pointer and an argument-block structure  as
71        arguments.
72
73
74 </PRE>
75 <H2>RETURN VALUE</H2><PRE>
76        The pointer-valued routines return NULL on error.
77
78        The  integer-valued  routines  return one of the following
79        codes on error:
80
81        <B>E_OK</B> The routine succeeded.
82
83        <B>E_SYSTEM_ERROR</B>
84             System error occurred (see <B>errno</B>).
85
86        <B>E_BAD_ARGUMENT</B>
87             Routine detected an incorrect or  out-of-range  argu-
88             ment.
89
90        <B>E_CONNECTED</B>
91             The field is already connected to a form.
92
93
94 </PRE>
95 <H2>SEE ALSO</H2><PRE>
96        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="form.3x.html">form(3x)</A></B>.
97
98
99 </PRE>
100 <H2>NOTES</H2><PRE>
101        The header file <B>&lt;form.h&gt;</B> automatically includes the header
102        file <B>&lt;curses.h&gt;</B>.
103
104        All of the <B>(char</B> <B>*)</B> arguments of  these  functions  should
105        actually  be <B>(void</B> <B>*)</B>.  The type has been left uncorrected
106        for strict compatibility with System V.
107
108
109 </PRE>
110 <H2>PORTABILITY</H2><PRE>
111        These routines emulate the System V forms  library.   They
112        were not supported on Version 7 or BSD versions.
113
114
115 </PRE>
116 <H2>AUTHORS</H2><PRE>
117        Juergen  Pfeifer.   Manual  pages  and  adaptation for new
118        curses by Eric S. Raymond.
119
120
121
122
123
124
125
126
127
128
129 </PRE>
130 <HR>
131 <ADDRESS>
132 Man(1) output converted with
133 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
134 </ADDRESS>
135 </BODY>
136 </HTML>