Getting User Input

fm_rd() processes user input for a form that is already displayed on the screen. The call for fm_rd() is as follows:

`int fm_rd(start_item, dfmp)`
`int start_item;`	`/* Item to make active first`	`*/`
`DFORMPTR dfmp;`	`/* Data form to edit`	`*/`

mn_rd() processes user input for a menu that is already displayed on the screen. The call for mn_rd() is as follows:

`int mn_rd(start_item, dfmp)`
`int start_item;`	`/* Item to make active first`	`*/`
`DFORMPTR dfmp;`	`/* Data form to edit`	`*/`

First, the form's activate function is called to perform any initialization required to activate the form. Then the begin-form function is called. Whereas the activate function is called each time the form is made active, the begin-form function is called only once for each call to fm_rd() or mn_rd().

Next, the item on which processing starts is set to the active field attribute. This allows the user to know what field is currently being processed. For a data form, the cursor is placed in the active field. For a menu form, the cursor is hidden.

fm_rd() and mn_rd() contain an event loop that checks for events and processes them as they are found. When the user presses a key or performs a mouse action such as pressing a mouse button, an event is posted. Keystrokes are stored in the keyboard buffer, and mouse actions are stored in a global event queue.

fm_rd() and mn_rd() both call the form editor, which checks the global event queue and the keyboard buffer periodically to see if an event is available. When an event is detected, the appropriate event table(s) are searched and the event function associated with the input is called.

If the form or menu is non-modal, the user can activate another form with a key function or mouse action. The suspend function for the form is called. The form remains suspended until it is reactivated. When the form is reactivated, the form activate function is called, but not the begin-form function.

Processing stays within fm_rd() or mn_rd() until the user requests to leave the form by one of the following:

nExiting the form by pressing the Exit key or by going forward from the last field on an AUTOEXIT form.
nFor data forms: requesting to go to the or previous form page by pressing the Next Form or Previous Form key.
nQuitting the form by pressing the Quit key.
nClicking the mouse on another form, menu or window to make it active.

Note: fm_rd() does not return when the user request to go to the next or previous form. A return from fm_rd() is only made when the user quits a form or exits a form.

If the user presses the Quit key, the form is not validated and the data is not saved.

Form validation occurs if the user exits a data form. The system checks to make sure that each field has been validated. After all fields have been successfully validated, the user form validation function, if installed, is called.

After successfully validating the fields on a data form, fm_convert() is called to convert the user's entries to the proper data variable type and copy the values to the data variables associated with the fields.

sr_convert() is called, if needed, by fm_convert() to validate and convert the data entered in a scrollable region. All visible fields are validated and converted. Fields that are not visible have already been validated and converted.

Form paging occurs if the user requests to page to the previous or next form during field entry on a data form. In this case, fm_rd() does the following:

nExits normally from the current form.
nRemoves the current form from the screen with fm_dn(), unless the form's FMLINKSHOW option is set ON, in which case the form remains on the screen.
nDisplays the next or previous form on the screen with fm_up().
nBegins reading the newly displayed form.

Note that fm_rd() does not return when the user requests to go to a next or previous form. A return from fm_rd() is only made when the user quits a form or exits a form.

For a more detailed description of form processing, see Chapter 29, "How Form and Menu Processing Works."