--- name: "form_driver" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/form_driver" --- # form\_driver(3) command-processing loop of the form system ## NAME **form\_driver**, **form\_driver\_w** - command-processing loop of the form system ## SYNOPSIS ``` #include ``` **int form\_driver(FORM \****form***, int** *c***);** **int form\_driver\_w(FORM \****form***, int** *c***, wchar\_t** *wc***);** ## DESCRIPTION ### form\_driver **Once a form has been posted (displayed), you should funnel input events to it** **through form\_driver. This routine has three major input cases:** - • **The input is a form navigation request.** **Navigation request codes are constants defined in** *form.h*, **which are distinct from the key- and character codes returned** **by wgetch(3X).** - • **The input is a printable character.** **Printable characters (which must be positive, less than 256) are** **checked according to the program's locale settings.** - • **The input is the KEY\_MOUSE special key associated with an mouse event.** ### form\_driver\_w **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 get\_wch(3X).** **The type must be passed as well,** **to enable the library to determine whether the parameter** **is a wide character or a request.** ### Form Driver Requests **The form driver requests are as follows:** | | | | --- | --- | | **Name** | **Description** | | **REQ\_BEG\_FIELD** | Move to beginning of field. | | **REQ\_BEG\_LINE** | Move to beginning of the line. | | **REQ\_CLR\_EOF** | Clear to end of field from cursor. | | **REQ\_CLR\_EOL** | Clear to end of line from cursor. | | **REQ\_CLR\_FIELD** | Clear the entire field. | | **REQ\_DEL\_CHAR** | Delete character at the cursor. | | **REQ\_DEL\_LINE** | Delete line at the cursor. | | **REQ\_DEL\_PREV** | Delete character before the cursor. | | **REQ\_DEL\_WORD** | Delete blank-delimited word at cursor. | | **REQ\_DOWN\_CHAR** | Move down in field. | | **REQ\_DOWN\_FIELD** | Move down to a field. | | **REQ\_END\_FIELD** | Move to the end of field. | | **REQ\_END\_LINE** | Move to the end of the line. | | **REQ\_FIRST\_FIELD** | Move to the first field. | | **REQ\_FIRST\_PAGE** | Move to the first page. | | **REQ\_INS\_CHAR** | Insert a blank at the cursor. | | **REQ\_INS\_LINE** | Insert a blank line at the cursor. | | **REQ\_INS\_MODE** | Enter insert mode. | | **REQ\_LAST\_FIELD** | Move to the last field. | | **REQ\_LAST\_PAGE** | Move to the last field. | | **REQ\_LEFT\_CHAR** | Move left in 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\_NEXT\_PAGE** | Move to the next page. | | **REQ\_NEXT\_WORD** | Move to the next word. | | **REQ\_OVL\_MODE** | Enter overlay mode. | | **REQ\_PREV\_CHAR** | Move to the previous char. | | **REQ\_PREV\_CHOICE** | Display previous field choice. | | **REQ\_PREV\_FIELD** | Move to the previous field. | | **REQ\_PREV\_LINE** | Move to the previous line. | | **REQ\_PREV\_PAGE** | Move to the previous page. | | **REQ\_PREV\_WORD** | Move to the previous word. | | **REQ\_RIGHT\_CHAR** | Move right in field. | | **REQ\_RIGHT\_FIELD** | Move right to a field. | | **REQ\_SCR\_BCHAR** | Scroll field backward 1 character. | | **REQ\_SCR\_BHPAGE** | Scroll field backward ½ page. | | **REQ\_SCR\_BLINE** | Scroll field backward 1 line. | | **REQ\_SCR\_BPAGE** | Scroll field backward 1 page. | | **REQ\_SCR\_FCHAR** | Scroll field forward 1 character. | | **REQ\_SCR\_FHPAGE** | Scroll field forward ½ page. | | **REQ\_SCR\_FLINE** | Scroll field forward 1 line. | | **REQ\_SCR\_FPAGE** | Scroll field forward 1 page. | | **REQ\_SCR\_HBHALF** | Horizontal scroll field backward ½ line. | | **REQ\_SCR\_HBLINE** | Horizontal scroll field backward 1 line. | | **REQ\_SCR\_HFHALF** | Horizontal scroll field forward ½ line. | | **REQ\_SCR\_HFLINE** | Horizontal scroll field forward 1 line. | | **REQ\_SFIRST\_FIELD** | Move to the sorted first field. | | **REQ\_SLAST\_FIELD** | Move to the sorted last field. | | **REQ\_SNEXT\_FIELD** | Move to the sorted next field. | | **REQ\_SPREV\_FIELD** | Move to the sorted previous field. | | **REQ\_UP\_CHAR** | Move up in field. | | **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.** ### Field Validation **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 set\_field\_type.** **You can validate a field without making any changes to it using** **REQ\_VALIDATION.** **The form driver also validates a field in these cases:** - • **a call to set\_current\_field attempts to move to a different field.** - • **a call to set\_current\_page attempts to move** **to a different page of the form.** - • **a request attempts to move to a different field.** - • **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.** ### Mouse Handling **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\_PREV\_FIELD is generated for a single click,** - **a REQ\_PREV\_PAGE is generated for a double-click and** - **a REQ\_FIRST\_FIELD is generated for a triple-click.** **If you click below the display region of the form:** - **a REQ\_NEXT\_FIELD is generated for a single click,** - **a REQ\_NEXT\_PAGE is generated for a double-click and** - **a REQ\_LAST\_FIELD is generated for a triple-click.** **If you click at an field inside the display area of the form:** - • **the form cursor is positioned to that field.** - • **If you double-click a field,** **the form cursor is positioned to that field** **and E\_UNKNOWN\_COMMAND 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 command should be executed.** - • **If a translation** **into a request was done, form\_driver 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 E\_REQUEST\_DENIED is returned.** ### Application-defined Commands **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 E\_UNKNOWN\_COMMAND. Application-defined commands** **should be defined relative to MAX\_COMMAND, the maximum value of these** **pre-defined requests.** ## RETURN VALUE **form\_driver returns one of the following error codes:** - **E\_OK** **The routine succeeded.** - **E\_BAD\_ARGUMENT** **Routine detected an incorrect or out-of-range argument.** - **E\_BAD\_STATE** **Routine was called from an initialization or termination function.** - **E\_NOT\_POSTED** **The form has not been posted.** - **E\_INVALID\_FIELD** **Contents of field is invalid.** - **E\_NOT\_CONNECTED** **No fields are connected to the form.** - **E\_REQUEST\_DENIED** **The form driver could not process the request.** - **E\_SYSTEM\_ERROR** **System error occurred (see [errno(3)](/errno/3.md)).** - **E\_UNKNOWN\_COMMAND** **The form driver code saw an unknown request code.** ## PORTABILITY **These routines emulate the System V forms library.** **They were not supported on** **Version 7 or BSD versions.** ## AUTHORS **Juergen Pfeifer.** **Manual pages and adaptation for new curses by Eric S. Raymond.** ## SEE ALSO **curses(3X),** **form(3X),** **form\_fieldtype(3X),** **form\_field\_buffer(3X),** **form\_field\_validation(3X),** **form\_variables(3X),** **getch(3X)**