X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fform_driver.3x;h=9b9d9382702ac098646df62d8a3982ec412a71bb;hp=4084eac08aaf5dded19ed599a0fe41ddddc2fc25;hb=95b3f94ec8b2da797e3e9a18fb49320daa5ab221;hpb=02f02dcd4464143580e783ae32c822d8eb8cdcbf diff --git a/man/form_driver.3x b/man/form_driver.3x index 4084eac0..9b9d9382 100644 --- a/man/form_driver.3x +++ b/man/form_driver.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 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 * @@ -26,16 +27,18 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_driver.3x,v 1.24 2015/08/02 18:21:11 tom Exp $ +.\" $Id: form_driver.3x,v 1.38 2021/12/25 21:49:32 tom Exp $ .TH form_driver 3X "" .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .SH NAME -\fBform_driver\fR \- command-processing loop of the form system +\fBform_driver\fP, +\fBform_driver_w\fP \- command-processing loop of the form system .SH SYNOPSIS -\fB#include \fR -.br +\fB#include \fP +.sp \fBint form_driver(FORM *\fP\fIform\fP\fB, int \fP\fIc\fP\fB);\fP .br \fBint form_driver_w(FORM *\fP\fIform\fP\fB, int \fP\fIc\fP\fB, wchar_t \fP\fIwch\fP\fB);\fP @@ -43,11 +46,12 @@ .SH DESCRIPTION .SS form_driver Once a form has been posted (displayed), you should funnel input events to it -through \fBform_driver\fR. This routine has three major input cases: +through \fBform_driver\fP. This routine has three major input cases: .bP The input is a form navigation request. Navigation request codes are constants defined in \fB\fP, -which are distinct from the key- and character codes returned by \fBwgetch\fP(3X). +which are distinct from the key- and character codes returned +by \fBwgetch\fP(3X). .bP The input is a printable character. Printable characters (which must be positive, less than 256) are @@ -67,9 +71,9 @@ is a wide character or a request. The form driver requests are as follows: .TS l l -_ _ _ +_ _ l l. -\fIName\fR \fIDescription\fR +\fBName\fP \fBDescription\fP 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. @@ -131,8 +135,37 @@ REQ_VALIDATION Validate field. .TE .PP 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 +in the current position in the current field. +If it is one of the forms requests listed above, that request is executed. +.SS Field validation +The form library makes updates to the window associated +with form fields rather than directly to the field buffers. +.PP +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 \fBset_field_type\fP. +.PP +.PP +You can validate a field without making any changes to it using +\fBREQ_VALIDATION\fP. +The form driver also validates a field in these cases: +.bP +a call to \fBset_current_field\fP attempts to move to a different field. +.bP +a call to \fBset_current_page\fP attempts to move +to a different page of the form. +.bP +a request attempts to move to a different field. +.bP +a request attempts to move to a different page of the form. +.PP +In each case, the move fails if the field is invalid. +.PP +If the modified field is valid, the form driver copies the modified +data from the window associated with the field +to the field buffer. .SS Mouse handling .PP If the second argument is the KEY_MOUSE special key, the associated @@ -167,7 +200,7 @@ the form cursor is positioned to that field. .bP If you double-click a field, the form cursor is positioned to that field -and \fBE_UNKNOWN_COMMAND\fR is returned. +and \fBE_UNKNOWN_COMMAND\fP is returned. This return value makes sense, because a double click usually means that an field-specific action should be returned. @@ -175,20 +208,21 @@ It is exactly the purpose of this return value to signal that an application specific command should be executed. .bP If a translation -into a request was done, \fBform_driver\fR returns the result of this request. +into a request was done, \fBform_driver\fP returns the result of this request. .RE .PP -If you clicked outside the user window or the mouse event could not be translated -into a form request an \fBE_REQUEST_DENIED\fR is returned. +If you clicked outside the user window +or the mouse event could not be translated +into a form request an \fBE_REQUEST_DENIED\fP is returned. .SS Application-defined commands .PP 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 \fBE_UNKNOWN_COMMAND\fR. Application-defined commands -should be defined relative to \fBMAX_COMMAND\fR, the maximum value of these +command and returns \fBE_UNKNOWN_COMMAND\fP. Application-defined commands +should be defined relative to \fBMAX_COMMAND\fP, the maximum value of these pre-defined requests. .SH RETURN VALUE -\fBform_driver\fR returns one of the following error codes: +\fBform_driver\fP returns one of the following error codes: .TP 5 .B E_OK The routine succeeded. @@ -205,26 +239,33 @@ The form has not been posted. .B E_INVALID_FIELD Contents of field is invalid. .TP 5 +.B E_NOT_CONNECTED +No fields are connected to the form. +.TP 5 .B E_REQUEST_DENIED The form driver could not process the request. .TP 5 .B E_SYSTEM_ERROR -System error occurred (see \fBerrno\fR). +System error occurred (see \fBerrno\fP(3)). .TP 5 .B E_UNKNOWN_COMMAND The form driver code saw an unknown request code. . .SH SEE ALSO -\fBcurses\fR(3X), -\fBform\fR(3X), -\fBform_variables\fR(3X), -\fBgetch\fR(3X). +\fBcurses\fP(3X), +\fBform\fP(3X), +\fBform_fieldtype\fP(3X), +\fBform_field_buffer\fP(3X), +\fBform_field_validation\fP(3X), +\fBform_variables\fP(3X), +\fBgetch\fP(3X). .SH NOTES -The header file \fB\fR automatically includes the header files -\fB\fR. +The header file \fB\fP automatically includes the header files +\fB\fP. .SH PORTABILITY -These routines emulate the System V forms library. They were not supported on +These routines emulate the System V forms library. +They were not supported on Version 7 or BSD versions. .SH AUTHORS -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.