When the form editor is called, it uses the starting item that you specify in the fm_rd() or mn_rd() call to determine the current item. (Note that a begin-form function can alter this starting number or set a next action code to exit or quit processing of the form.)
Processing continues on the same form until the action code indicates that processing of the form should stop (i.e., while the action code is not AC_QUIT, AC_EXIT, AC_PREVFORM, AC_NEXTFORM, or AC_FMSUSPEND).
The form editor determines the type of the current item and begins processing it. Processing continues until the current item is changed by settings made in begin-field, end-field or event functions.
The form editor then determines the number of the next item to go to and resets the action code if needed. If that item is a valid number and the action code indicates that the user is staying in this form, processing continues. If the item is not a valid number, the system determines, based on the form options, what the next action is. For instance, if the user pressed the Next Item key while on the last item of the form and FMWRAP is ON, the current field number is set to 0. If the user pressed the Next Item key while on the last item of the form and AUTOEXIT is ON, the next action code is set to AC_EXIT.
The form editor performs the actions discussed below. Note that any of the user functions can call sfm_nextitem() (or ssr_nextpos(), if the current item is a scrollable region) to leave the form or to specify a different item to move to next. The form editor checks after each event and after each user function to determine whether the user is leaving the form, and if not, what the next item should be. Also note that begin and end functions are paired: if the begin function is called, the corresponding end function will be called, even if the user is quitting the form.
Before the user can enter data into the form or make a menu selection, the form editor must make sure that the form is visible and call the appropriate activate and begin functions.
Making the form visible: First, the form editor checks to see whether any other forms or windows are covering part or all of this form. If so, and if these windows are not child windows to the form window, the form window is brought to the top. (A child window is a window that is supposed to be displayed on top of its parent window at all times. See Chapter 28, "Advanced Window Management," for more information.)
Calling the : Next, the form editor calls the window activate function, if you have installed one. The activate function returns a value of TRUE if it succeeds, and FALSE if it fails. If the activate function fails, no further processing is performed.
Calling the : Finally, the form editor calls the begin-form function. The begin-form function also returns a FALSE value if it fails, although it may return several different values to indicate success. If the begin-form function fails, the suspend function is called, and no further processing is performed. If the begin-form function returns a value that indicates that it succeeded, but sets the next action code to terminate form processing, both the end-form function and the suspend function are called before processing terminates.
When the form editor first begins processing the form, it assumes that the first item to be processed is the item number specified in the call to fm_proc(), mn_proc(), fm_rd(), or mn_rd(). However, event functions and user functions can alter the processing in a form by calling functions to move to different fields, or to leave the form. After each keystroke or mouse event, and after each user function is called, the form editor must determine whether the user is staying in the same item, moving to a different item on the form, or leaving the form. It does this by checking the next action code in the form structure.
Suspending the form: The form editor first checks for a next action code of AC_FMSUSPEND. If this action code is set, the form is being temporarily suspended. Since the form is being suspended, the form editor validates the current field, but does no further processing on the form. Neither the end-field nor the end-form function is called. If the message window is up, it is taken down. The current field is redisplayed with the inactive attribute, and the window suspend function is called.
Only non-modal forms, menus and windows can be suspended. For more information on suspending forms and on non-modal programming, see Chapter 30, "Differences in Non-Modal Form Processing."
Leaving the form: If the next action code was not AC_FMSUSPEND, the form editor checks for values of AC_QUIT, AC_EXIT, AC_NEXTFORM, or AC_PREVFORM. Any of these values will result in leaving the form, and the form editor will perform the appropriate processing for quitting or exiting the form.
Leaving the current field: If the user is not leaving the form, the form editor determines whether to leave the current field, and if so, which item on the form to move to next.
If the form editor determines that it needs to move to a new item on the form, or when it first enters the form, it must ensure that the item to be processed is visible and call the appropriate begin functions.
Moving into a scrollable region: If the new item is a scrollable region, the form editor checks to see whether the scrollable region needs to be scrolled to make the data in the current field visible. If so, it performs the processing associated with scrolling a scrollable region. It then calls the begin scrollable region function, if one is attached. Since this is the first time the user has moved into the scrollable region, the form editor also performs processing related to moving to a new row in the region.
Moving to a new row in a scrollable region: If the new item is a new field within the current scrollable region, and the new field is on a new row, the end-row scrollable region function is called for the current row. If the region must be scrolled to make the new row visible, the form editor performs the processing associated with scrolling the region. Then the begin-row scrollable region function for the new row is called. Since the user is moving to a new field, the form editor also performs processing related to moving to a new field.
Scrolling the scrollable region: If the scrollable region needs to be scrolled to bring the next field into view, the form editor determines which rows will be scrolled out of view. The fields on these rows are validated; if any field fails validation, the user is moved back into that field and the region does not scroll. After all fields that will be scrolled out of view are validated, the data in these fields is converted and stored in the underlying data variables for these fields. Vermont Views then scrolls the data pointers in the data array, so that the appropriate rows of data are visible. It redisplays the region with the new data, and then calls the user scroll function for the scrollable region.
Moving to a new field on the form: The form editor performs the same processing regardless of whether the new field is in a scrollable region. If the field has a message, the message is displayed. If it is necessary to scroll the form to bring this field into view, Vermont Views scrolls the form, calls the user scroll function for the form, and then updates the form window on the screen. The field is redisplayed in the active attribute, respecting all field options. The begin-field function for the new field is called. If a data field has a choice list which should be automatically displayed, the choice list is displayed. If a menu field has a sub-menu which drops down automatically, the sub-menu is displayed.
Waiting for input: Once in a field, the form editor enters an event loop, waiting for input. When the user presses a key or performs a mouse action, an event is posted. The event loop periodically checks the global event queue for mouse events, and the keyboard buffer for keystroke events.
Processing an event: When an event is found, the form editor begins searching event tables to find the event code. The first table searched is always the system event table, SYSETP. If the event code is found in that table, the appropriate function is called. If the event code is not found, and there is no default event function in that table, the form editor next searches the form event table, FMETP. If the event code is found, the appropriate function is called; if not, and if there is no default event function, the form editor searches the event table pointed to by the item being processed (When you create a field or memo, Vermont Views stores a pointer to the event table in the field structure for you. You can reset this pointer. For more information, see Chapter 39, "Installing Event Functions and Modifying Event Tables"). For example, if the current item is a memo field, the form editor searches the memo event table MEMOETP; if the current item is a radio button, the form editor searches the radio button event table RADIOETP. A complete list of event tables can be found in the Event Tables section of the Function Reference.
Note: If all fields on the form are SKIP, Vermont Views cannot determine which event table to search after the form event table. In this case, Vermont Views searches a special internal event table, which only allows the user to quit from the form.
Making a menu selection or pushing a pushbutton. The user can select a menu item or push a pushbutton by either moving the cursor into the field and pressing the Selection key (by default, the Enter key), by pressing the selection character for the field if selection characters have been enabled for the form, or, in PCDOS only, by clicking the mouse on the field. The corresponding menu action function or pushbutton action function is called.
Typing data into a data field: As the user types, the keystrokes are processed by the default event function in the appropriate event table. The default function inserts the keys into the edit buffer for the field. The form editor will continue to process the current field until the user performs some action to leave the field or the form.
Leaving the current field: The user can choose to move to another field by pressing Enter or the Next Field or Previous Field keys, by pressing the selection character key or key combination for another field if selection characters have been enabled, or, in PCDOS, by clicking the mouse on a different field. If the AUTOMOVE form option is ON, the user can also move to the next field by typing a character in the last position of the current field.
Moving out of the scrollable region: If the new item is a field outside the current scrollable region, the end-row scrollable region function is called for the current row. The end-scrollable region function is also called. Since the user is moving to a new field, the form editor also performs processing related to moving to a new field.
Leaving a field: After any event has been processed, the form editor checks whether it is staying in the same field. If not, and if this is a data form, the system validation function and user validation function for the field are called. If either validation function fails, the user remains in the field. If the validation functions succeed, the end-field function is called. If this is a menu form, there are no validation functions to be called. The end-field function is called immediately.
After the end-field function is called, the form editor redisplays the field in the inactive attribute. If the FORCECONVERT option is ON for a data field, the data is converted and stored in the underlying data variable, and the field is flagged as not altered. If the user is staying in the form, the form editor determines which item to move to next.
The user can leave a data form in one of two ways: by exiting from the form, or by quitting from it. For menu forms, the user can only quit from the form. For data forms, however, the distinction between quitting and exiting is important.
As the user types information into the form, that information is stored in the edit buffers for the fields. The underlying data variables are not updated immediately. If the user exits from a data form, he or she wants to save the data that was entered into the form. Vermont Views will validate the data in the current field, and call the form validation function. Afterwards, Vermont Views will convert the data in the edit buffers and save the data into the underlying data variables.
If the user quits from a data form, he or she does not intend to save the data that was entered into the form. Vermont Views does no further validation on the data in the form. The data is not saved into the underlying data variables. The user has cancelled all the information that was typed into the form.
Note: There are two exceptions to this rule. If a field has the FORCECONVERT option ON, the data is saved into the underlying data variable as soon as the user leaves that field. Also, if the user scrolls a scrollable region, data that is scrolled off the screen is saved into the underlying data variables.
Quitting the form: If the user is leaving the form, the form editor checks the next action code to see if it is set to AC_QUIT. If it is, and if the VERIFYQUIT option is ON for this form, the user is asked to confirm that he or she wants to quit the form. If the user says yes, he or she will leave the form. Since the user is quitting rather than exiting, data validation and conversion will not take place. The form editor then performs processing related to leaving the form.
Exiting the form: If the user is leaving the form and the action code is AC_EXIT, AC_NEXTFORM, or AC_PREVFORM, the user is exiting rather than quitting the form. If the VERIFYEXIT option is ON for this form, the user is asked to confirm that he or she wishes to exit the form. If the user says yes, he or she will leave the form.
For a data form, form validation and data conversion must take place. If any fields on the form have been altered and not validated, the system and user validation functions are called for those fields. If any field fails validation, the user is returned to that field.
If all fields on the form are valid, the form validation function is called. If the form validation function fails, it calls sfm_nextitem() to tell the form editor what item to move to.
If the form validation function succeeds, all fields on the form are flagged as valid and not altered.
Calling the and window suspend functions: After the user has confirmed that he wishes to quit or exit the form, and after data has been validated and converted, Vermont Views calls the end-form function. If the end-form function returns a value indicating that it succeeded, the suspend function is called. Note that the end-form and suspend functions are called even if the user has quit the form.
Taking the form off the screen: If Vermont Views automatically put this form up (during the fm_proc() or mn_proc() call, when the user brought down a sub-menu, or when the user pressed the Next Form or Previous Form key, for example), or if the AUTOUPDN form option is set, the form is taken off the screen. Otherwise, you need to call fm_dn() directly in your code to remove the form from the screen. If the AUTOFREE form option is ON, Vermont Views calls fm_free() to free the form after taking the form off the screen.
