ncurses 6.1 - patch 20190713
[ncurses.git] / doc / html / man / form_driver.3x.html
index a029ea21c6ffd83799256a741ce7fc1ee58f12f4..f815be827f588f52df08ed657d5e587715fdba5e 100644 (file)
@@ -1,6 +1,6 @@
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2010,2015 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2018,2019 Free Software Foundation, Inc.              *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: form_driver.3x,v 1.25 2015/12/05 21:06:26 tom Exp @
+  * @Id: form_driver.3x,v 1.32 2019/01/20 20:31:42 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
+<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
 <TITLE>form_driver 3x</TITLE>
-<link rev=made href="mailto:bug-ncurses@gnu.org">
+<link rel="author" href="mailto:bug-ncurses@gnu.org">
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 </HEAD>
 <BODY>
 <H1 class="no-header">form_driver 3x</H1>
 <PRE>
-<STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG>                                         <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG>
+<STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG>                                                <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG>
 
 
 
 
 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
-       <STRONG>form_driver</STRONG>,  <STRONG>form_driver_w</STRONG>  -  command-processing loop of
-       the form system
+       <STRONG>form_driver</STRONG>, <STRONG>form_driver_w</STRONG> - command-processing loop of the form system
 
 
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 </PRE><H3><a name="h3-form_driver">form_driver</a></H3><PRE>
-       Once a form has been posted (displayed), you should funnel
-       input  events to it through <STRONG>form_driver</STRONG>.  This routine has
-       three major input cases:
+       Once a form has been posted (displayed), you should funnel input events
+       to it through <STRONG>form_driver</STRONG>.  This routine has three major input cases:
 
-       <STRONG>o</STRONG>   The input is a form  navigation  request.   Navigation
-           request codes are constants defined in <STRONG>&lt;form.h&gt;</STRONG>, which
-           are  distinct  from  the  key-  and  character   codes
-           returned by <STRONG><A HREF="wgetch.3x.html">wgetch(3x)</A></STRONG>.
+       <STRONG>o</STRONG>   The input is a form navigation request.  Navigation  request  codes
+           are constants defined in <STRONG>&lt;form.h&gt;</STRONG>, which are distinct from the key-
+           and character codes returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>.
 
-       <STRONG>o</STRONG>   The input is a printable character.  Printable charac-
-           ters (which must  be  positive,  less  than  256)  are
-           checked according to the program's locale settings.
+       <STRONG>o</STRONG>   The input is a printable character.   Printable  characters  (which
+           must  be positive, less than 256) are checked according to the pro-
+           gram's locale settings.
 
-       <STRONG>o</STRONG>   The input is the KEY_MOUSE special key associated with
-           an mouse event.
+       <STRONG>o</STRONG>   The input is the KEY_MOUSE special key  associated  with  an  mouse
+           event.
 
 
 </PRE><H3><a name="h3-form_driver_w">form_driver_w</a></H3><PRE>
-       This extension simplifies the use  of  the  forms  library
-       using  wide characters.  The input is either a key code (a
-       request) or a wide character returned by <STRONG><A HREF="get_wch.3x.html">get_wch(3x)</A></STRONG>.  The
-       type  must  be  passed  as  well, to enable the library to
-       determine whether the parameter is a wide character  or  a
+       This extension simplifies the use of the forms library using wide char-
+       acters.  The input is either a key code (a request) or a wide character
+       returned  by  <STRONG><A HREF="curs_get_wch.3x.html">get_wch(3x)</A></STRONG>.   The type must be passed as well, to enable
+       the library to determine whether the parameter is a wide character or a
        request.
 
 
@@ -89,7 +85,7 @@
        The form driver requests are as follows:
 
        <EM>Name</EM>               <EM>Description</EM>
-       -------------------------------------------------------------------------
+       ---------------------------------------------------------------------
        REQ_BEG_FIELD      Move to the beginning of the field.
        REQ_BEG_LINE       Move to the beginning of the line.
        REQ_CLR_EOF        Clear to end of field from cursor.
        REQ_LAST_FIELD     Move to the last field.
        REQ_LAST_PAGE      Move to the last field.
        REQ_LEFT_CHAR      Move left in the field.
-
        REQ_LEFT_FIELD     Move left to a field.
        REQ_NEW_LINE       Insert or overlay a new line.
        REQ_NEXT_CHAR      Move to the next char.
        REQ_NEXT_CHOICE    Display next field choice.
+
        REQ_NEXT_FIELD     Move to the next field.
        REQ_NEXT_LINE      Move to the next line.
        REQ_NEXT_PAGE      Move to the next page.
        REQ_UP_FIELD       Move up to a field.
        REQ_VALIDATION     Validate field.
 
-       If  the  second  argument  is  a  printable character, the
-       driver places it in the current position  in  the  current
-       field.   If  it is one of the forms requests listed above,
-       that request is executed.
+       If  the  second argument is a printable character, the driver places it
+       in the current position in the current field.  If  it  is  one  of  the
+       forms requests listed above, that request is executed.
+
+
+</PRE><H3><a name="h3-Field-validation">Field validation</a></H3><PRE>
+       The  form  library  makes  updates  to  the window associated with form
+       fields rather than directly to the field buffers.
+
+       The form driver provides low-level control over  updates  to  the  form
+       fields.   The  form driver also provides for validating modified fields
+       to ensure that the contents meet whatever  constraints  an  application
+       may attach using <STRONG>set_field_type</STRONG>.
+
+       You  can  validate  a  field  without  making  any  changes to it using
+       <STRONG>REQ_VALIDATION</STRONG>.  The form driver also validates a field in these cases:
+
+       <STRONG>o</STRONG>   a call to <STRONG>set_current_field</STRONG> attempts to move to a different field.
+
+       <STRONG>o</STRONG>   a call to <STRONG>set_current_page</STRONG> attempts to move to a different page  of
+           the form.
+
+       <STRONG>o</STRONG>   a request attempts to move to a different field.
+
+       <STRONG>o</STRONG>   a request attempts to move to a different page of the form.
+
+       In each case, the move fails if the field is invalid.
+
+       If  the  modified  field  is valid, the form driver copies the modified
+       data from the window associated with the field to the field buffer.
 
 
 </PRE><H3><a name="h3-Mouse-handling">Mouse handling</a></H3><PRE>
-       If the second argument is the KEY_MOUSE special  key,  the
-       associated mouse event is translated into one of the above
-       pre-defined requests.  Currently only clicks in  the  user
-       window  (e.g., inside the form display area or the decora-
-       tion window) are handled.
+       If the second argument is the KEY_MOUSE  special  key,  the  associated
+       mouse  event  is translated into one of the above pre-defined requests.
+       Currently only clicks in the user window (e.g., inside the form display
+       area or the decoration window) are handled.
 
        If you click above the display region of the form:
 
 
           a REQ_LAST_FIELD is generated for a triple-click.
 
-       If you click at an field inside the display  area  of  the
-       form:
+       If you click at an field inside the display area of the form:
 
           <STRONG>o</STRONG>   the form cursor is positioned to that field.
 
-          <STRONG>o</STRONG>   If  you  double-click  a  field, the form cursor is
-              positioned to that field and  <STRONG>E_UNKNOWN_COMMAND</STRONG>  is
-              returned.  This return value makes sense, because a
-              double click usually means that  an  field-specific
-              action  should be returned.  It is exactly the pur-
-              pose of this return value to signal that an  appli-
-              cation specific command should be executed.
+          <STRONG>o</STRONG>   If  you  double-click  a field, the form cursor is positioned to
+              that field and <STRONG>E_UNKNOWN_COMMAND</STRONG> is returned.  This return value
+              makes sense, because a double click usually means that an field-
+              specific action should be returned.  It is exactly  the  purpose
+              of this return value to signal that an application specific com-
+              mand should be executed.
 
-          <STRONG>o</STRONG>   If   a   translation   into  a  request  was  done,
-              <STRONG>form_driver</STRONG> returns the result of this request.
+          <STRONG>o</STRONG>   If a translation into a request was  done,  <STRONG>form_driver</STRONG>  returns
+              the result of this request.
 
-       If you clicked outside the user window or the mouse  event
-       could   not   be   translated   into  a  form  request  an
-       <STRONG>E_REQUEST_DENIED</STRONG> is returned.
+       If  you clicked outside the user window or the mouse event could not be
+       translated into a form request an <STRONG>E_REQUEST_DENIED</STRONG> is returned.
 
 
 </PRE><H3><a name="h3-Application-defined-commands">Application-defined commands</a></H3><PRE>
-       If the second argument is neither printable nor one of the
-       above  pre-defined form requests, the driver assumes it is
-       an application-specific command and returns <STRONG>E_UNKNOWN_COM-</STRONG>
-       <STRONG>MAND</STRONG>.  Application-defined commands should be defined rel-
-       ative to <STRONG>MAX_COMMAND</STRONG>, the  maximum  value  of  these  pre-
-       defined requests.
+       If the second argument is neither printable nor one of the  above  pre-
+       defined form requests, the driver assumes it is an application-specific
+       command and returns  <STRONG>E_UNKNOWN_COMMAND</STRONG>.   Application-defined  commands
+       should  be  defined relative to <STRONG>MAX_COMMAND</STRONG>, the maximum value of these
+       pre-defined requests.
 
 
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
        <STRONG>E_OK</STRONG> The routine succeeded.
 
        <STRONG>E_BAD_ARGUMENT</STRONG>
-            Routine  detected  an incorrect or out-of-range argu-
-            ment.
+            Routine detected an incorrect or out-of-range argument.
 
        <STRONG>E_BAD_STATE</STRONG>
-            Routine was called from an initialization or termina-
-            tion function.
+            Routine was called from an initialization or termination function.
 
        <STRONG>E_NOT_POSTED</STRONG>
             The form has not been posted.
        <STRONG>E_INVALID_FIELD</STRONG>
             Contents of field is invalid.
 
+       <STRONG>E_NOT_CONNECTED</STRONG>
+            No fields are connected to the form.
+
        <STRONG>E_REQUEST_DENIED</STRONG>
             The form driver could not process the request.
 
        <STRONG>E_SYSTEM_ERROR</STRONG>
-            System error occurred (see <STRONG>errno</STRONG>).
+            System error occurred (see <STRONG>errno(3)</STRONG>).
 
        <STRONG>E_UNKNOWN_COMMAND</STRONG>
             The form driver code saw an unknown request code.
 
 
 </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="curs_getch.3x.html">curs_getch(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_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG>, <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(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>, <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
 
 
 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
-       The header file <STRONG>&lt;form.h&gt;</STRONG> automatically includes the header
-       files <STRONG>&lt;curses.h&gt;</STRONG>.
+       The  header  file  <STRONG>&lt;form.h&gt;</STRONG>  automatically  includes  the  header files
+       <STRONG>&lt;curses.h&gt;</STRONG>.
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
-       These routines emulate the System V forms  library.   They
-       were not supported on Version 7 or BSD versions.
+       These routines emulate the System V forms library.  They were not  sup-
+       ported on Version 7 or BSD versions.
 
 
 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
-       Juergen  Pfeifer.   Manual  pages  and  adaptation for new
-       curses by Eric S. Raymond.
+       Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric S.
+       Raymond.
 
 
 
-                                                        <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG>
+                                                               <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG>
 </PRE>
 <div class="nav">
 <ul>
 <li><a href="#h3-form_driver">form_driver</a></li>
 <li><a href="#h3-form_driver_w">form_driver_w</a></li>
 <li><a href="#h3-Form-driver-requests">Form-driver requests</a></li>
+<li><a href="#h3-Field-validation">Field validation</a></li>
 <li><a href="#h3-Mouse-handling">Mouse handling</a></li>
 <li><a href="#h3-Application-defined-commands">Application-defined commands</a></li>
 </ul>