]> ncurses.scripts.mit.edu Git - ncurses.git/blobdiff - doc/html/man/form_field_validation.3x.html
projects / ncurses.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
ncurses 6.2 - patch 20210626
[ncurses.git] / doc / html / man / form_field_validation.3x.html
diff --git a/doc/html/man/form_field_validation.3x.html b/doc/html/man/form_field_validation.3x.html
index 8150c2c1a7a1921923fc01cd071590cd9f503e60..c278107033aa1cead60fa8dcb101e8005e92b8b7 100644 (file)
--- a/doc/html/man/form_field_validation.3x.html
+++ b/doc/html/man/form_field_validation.3x.html
@@ -1,4 +1,4 @@
-<!-- 
+<!--
   ****************************************************************************
   * Copyright 2018-2019,2020 Thomas E. Dickey                                *
   * Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
   ****************************************************************************
   * Copyright 2018-2019,2020 Thomas E. Dickey                                *
   * Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
@@ -27,7 +27,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: form_field_validation.3x,v 1.27 2020/10/18 00:07:45 tom Exp @
+  * @Id: form_field_validation.3x,v 1.33 2020/12/12 19:57:55 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
@@ -53,10 +53,11 @@
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#include</STRONG> <STRONG>&lt;form.h&gt;</STRONG>
 
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#include</STRONG> <STRONG>&lt;form.h&gt;</STRONG>
 
-       <STRONG>int</STRONG> <STRONG>set_field_type(FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>,</STRONG> <STRONG>FIELDTYPE</STRONG> <STRONG>*</STRONG><EM>type</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
-       <STRONG>FIELDTYPE</STRONG> <STRONG>*field_type(const</STRONG> <STRONG>FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>);</STRONG>
        <STRONG>void</STRONG> <STRONG>*field_arg(const</STRONG> <STRONG>FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>);</STRONG>
        <STRONG>void</STRONG> <STRONG>*field_arg(const</STRONG> <STRONG>FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>);</STRONG>
+       <STRONG>FIELDTYPE</STRONG> <STRONG>*field_type(const</STRONG> <STRONG>FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>);</STRONG>
+       <STRONG>int</STRONG> <STRONG>set_field_type(FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>,</STRONG> <STRONG>FIELDTYPE</STRONG> <STRONG>*</STRONG><EM>type</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
 
 
+       /* predefined field types */
        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ALNUM;</STRONG>
        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ALPHA;</STRONG>
        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ENUM;</STRONG>
        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ALNUM;</STRONG>
        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ALPHA;</STRONG>
        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ENUM;</STRONG>
@@ -67,73 +68,107 @@
 
 
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
-       The  function  <STRONG>set_field_type</STRONG>  declares  a  data  type for a given form
-       field.  This is the type checked by validation functions.   The  prede-
-       fined types are as follows:
+       By  default, no validation is done on form fields.  You can associate a
+       form with with a <EM>field</EM> <EM>type</EM>, making the form library validate input.
+
+
+</PRE><H3><a name="h3-field_arg">field_arg</a></H3><PRE>
+       Returns a pointer to the field's argument block.  The <EM>argument</EM> <EM>block</EM> is
+       an  opaque  structure  containing a copy of the arguments provided in a
+       <STRONG>set_field_type</STRONG> call.
+
+
+</PRE><H3><a name="h3-field_type">field_type</a></H3><PRE>
+       Returns a pointer to the <EM>field</EM> <EM>type</EM> associated  with  the  form  field,
+       i.e., by calling <STRONG>set_field_type</STRONG>.
+
+
+</PRE><H3><a name="h3-set_field_type">set_field_type</a></H3><PRE>
+       The  function  <STRONG>set_field_type</STRONG> associates a field type with a given form
+       field.  This is the type checked by validation functions.   Most  field
+       types  are  configurable,  via arguments which the caller provides when
+       calling <STRONG>set_field_type</STRONG>.
+
+       Several field types are predefined by the form library.
+
+
+</PRE><H3><a name="h3-Predefined-types">Predefined types</a></H3><PRE>
+       It is possible to set up new  programmer-defined  field  types.   Field
+       types  are implemented via the <STRONG>FIELDTYPE</STRONG> data structure, which contains
+       several pointers to functions.
+
+       See the <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG> manual page, which describes functions which
+       can be used to construct a field-type dynamically.
+
+       The predefined types are as follows:
 
        TYPE_ALNUM
 
        TYPE_ALNUM
-            Alphanumeric data.  Requires a third <STRONG>int</STRONG> argument, a minimum field
-            width.
+            Alphanumeric data.  Required parameter:
+
+            <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument, a minimum field width.
 
        TYPE_ALPHA
 
        TYPE_ALPHA
-            Character data.  Requires a third <STRONG>int</STRONG> argument,  a  minimum  field
-            width.
+            Character data.  Required parameter:
+
+            <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument, a minimum field width.
 
        TYPE_ENUM
 
        TYPE_ENUM
-            Accept  one  of  a  specified set of strings.  Requires additional
-            parameters:
+            Accept one of a specified set of strings.  Required parameters:
 
             <STRONG>o</STRONG>   a third <STRONG>(char</STRONG> <STRONG>**)</STRONG> argument pointing to a string list;
 
             <STRONG>o</STRONG>   a fourth <STRONG>int</STRONG> flag argument to enable case-sensitivity;
 
 
             <STRONG>o</STRONG>   a third <STRONG>(char</STRONG> <STRONG>**)</STRONG> argument pointing to a string list;
 
             <STRONG>o</STRONG>   a fourth <STRONG>int</STRONG> flag argument to enable case-sensitivity;
 
-            <STRONG>o</STRONG>   and a fifth <STRONG>int</STRONG> flag argument  specifying  whether  a  partial
-                match  must  be  a  unique one.  If this flag is off, a prefix
-                matches the first of any set of more than  one  list  elements
-                with that prefix.
+            <STRONG>o</STRONG>   a  fifth  <STRONG>int</STRONG> flag argument specifying whether a partial match
+                must be a unique one.  If this flag is off, a  prefix  matches
+                the  first of any set of more than one list elements with that
+                prefix.
 
 
-                The library copies the string list, so you may use a list that
-                lives in automatic variables on the stack.
+            The library copies the string list, so you may  use  a  list  that
+            lives in automatic variables on the stack.
 
        TYPE_INTEGER
 
        TYPE_INTEGER
-            Integer data, parsable to an integer by <STRONG>atoi(3)</STRONG>.   Requires  addi-
-            tional parameters:
+            Integer  data,  parsable  to  an  integer  by  <STRONG>atoi(3)</STRONG>.   Required
+            parameters:
 
             <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument controlling the precision,
 
             <STRONG>o</STRONG>   a fourth <STRONG>long</STRONG> argument constraining minimum value,
 
 
             <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument controlling the precision,
 
             <STRONG>o</STRONG>   a fourth <STRONG>long</STRONG> argument constraining minimum value,
 
-            <STRONG>o</STRONG>   and  a  fifth <STRONG>long</STRONG> constraining maximum value.  If the maximum
-                value is less than or equal to the minimum value, the range is
-                simply  ignored.   On  return,  the  field buffer is formatted
-                according to the <STRONG>printf</STRONG> format specification ".*ld", where the
-                "*" is replaced by the precision argument.
+            <STRONG>o</STRONG>   a fifth <STRONG>long</STRONG> constraining maximum value.  If the maximum value
+                is  less  than  or  equal  to  the minimum value, the range is
+                simply ignored.
+
+            On return, the field buffer is formatted according to  the  <STRONG>printf</STRONG>
+            format  specification  ".*ld",  where  the  "*" is replaced by the
+            precision argument.
 
 
-                For details of the precision handling see <STRONG>printf(3)</STRONG>.
+            For details of the precision handling see <STRONG>printf(3)</STRONG>.
 
        TYPE_NUMERIC
 
        TYPE_NUMERIC
-            Numeric data (may have a decimal-point part).  This requires addi-
-            tional parameters:
+            Numeric  data  (may  have   a   decimal-point   part).    Required
+            parameters:
 
             <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument controlling the precision,
 
             <STRONG>o</STRONG>   a fourth <STRONG>double</STRONG> argument constraining minimum value,
 
             <STRONG>o</STRONG>   and a fifth <STRONG>double</STRONG> constraining maximum value.  If your system
 
             <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument controlling the precision,
 
             <STRONG>o</STRONG>   a fourth <STRONG>double</STRONG> argument constraining minimum value,
 
             <STRONG>o</STRONG>   and a fifth <STRONG>double</STRONG> constraining maximum value.  If your system
-                supports  locales, the decimal point character must be the one
-                specified by your locale.  If the maximum value is  less  than
+                supports locales, the decimal point character must be the  one
+                specified  by  your locale.  If the maximum value is less than
                 or equal to the minimum value, the range is simply ignored.
 
                 or equal to the minimum value, the range is simply ignored.
 
-                On  return,  the  field  buffer  is formatted according to the
-                <STRONG>printf</STRONG> format specification ".*f", where the "*"  is  replaced
-                by the precision argument.
+            On return, the field buffer is formatted according to  the  <STRONG>printf</STRONG>
+            format  specification  ".*f",  where  the  "*"  is replaced by the
+            precision argument.
 
 
-                For details of the precision handling see <STRONG>printf(3)</STRONG>.
+            For details of the precision handling see <STRONG>printf(3)</STRONG>.
 
        TYPE_REGEXP
 
        TYPE_REGEXP
-            Regular  expression  data.  Requires a regular expression <STRONG>(char</STRONG> <STRONG>*)</STRONG>
-            third argument.  The data  is  valid  if  the  regular  expression
-            matches it.
+            Regular expression data.  Required parameter:
+
+            <STRONG>o</STRONG>   a third argument, a regular expression <STRONG>(char</STRONG> <STRONG>*)</STRONG>  string.   The
+                data is valid if the regular expression matches it.
 
             Regular expressions are in the format of <STRONG>regcomp</STRONG> and <STRONG>regexec</STRONG>.
 
 
             Regular expressions are in the format of <STRONG>regcomp</STRONG> and <STRONG>regexec</STRONG>.
 
@@ -146,22 +181,22 @@
             trailing spaces around the digits.
 
        TYPE_IPV4
             trailing spaces around the digits.
 
        TYPE_IPV4
-            An  Internet  Protocol  Version 4 address.  This requires no addi-
-            tional argument.  The library checks whether or not the buffer has
-            the form a.b.c.d, where a,b,c and d are numbers between 0 and 255.
-            Trailing blanks in the buffer are ignored.  The address itself  is
+            An Internet Protocol Version 4 address.  Required parameter:
+
+            <STRONG>o</STRONG>   none
+
+            The  form  library  checks  whether or not the buffer has the form
+            <EM>a.b.c.d</EM>, where <EM>a</EM>, <EM>b</EM>, <EM>c</EM>, and <EM>d</EM> are numbers in the range 0  to  255.
+            Trailing  blanks in the buffer are ignored.  The address itself is
             not validated.
 
             This is an ncurses extension; this field type may not be available
             in other curses implementations.
 
             not validated.
 
             This is an ncurses extension; this field type may not be available
             in other curses implementations.
 
-       It is possible to set up new programmer-defined field types.   See  the
-       <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG> manual page.
-
 
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
-       The functions <STRONG>field_type</STRONG> and <STRONG>field_arg</STRONG> return <STRONG>NULL</STRONG> on error.  The func-
-       tion <STRONG>set_field_type</STRONG> returns one of the following:
+       The  functions  <STRONG>field_type</STRONG>  and  <STRONG>field_arg</STRONG>  return  <STRONG>NULL</STRONG> on error.  The
+       function <STRONG>set_field_type</STRONG> returns one of the following:
 
        <STRONG>E_OK</STRONG> The routine succeeded.
 
 
        <STRONG>E_OK</STRONG> The routine succeeded.
 
@@ -170,7 +205,7 @@
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG>.
+       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG>, <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG>.
 
 
 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
@@ -179,8 +214,8 @@
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
-       These  routines emulate the System V forms library.  They were not sup-
-       ported on Version 7 or BSD versions.
+       These  routines  emulate  the  System  V  forms library.  They were not
+       supported on Version 7 or BSD versions.
 
 
 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
@@ -195,7 +230,14 @@
 <ul>
 <li><a href="#h2-NAME">NAME</a></li>
 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 <ul>
 <li><a href="#h2-NAME">NAME</a></li>
 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
-<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
+<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
+<ul>
+<li><a href="#h3-field_arg">field_arg</a></li>
+<li><a href="#h3-field_type">field_type</a></li>
+<li><a href="#h3-set_field_type">set_field_type</a></li>
+<li><a href="#h3-Predefined-types">Predefined types</a></li>
+</ul>
+</li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 <li><a href="#h2-NOTES">NOTES</a></li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 <li><a href="#h2-NOTES">NOTES</a></li>
ncurses, with patches starting at ncurses-5.6; new users should use https://github.com/ThomasDickey/ncurses-snapshots/