Writing and Installing Pushbutton Action Functions

Pushbutton action functions take one parameter, a pointer to the current data form. The call is as follows:

int usr_func(dfmp)

DFORMPTR dfmp;        /* Pointer to form with pushbutton    */

The form editor passes the pointer to the form currently being processed. From the form pointer, you have access to the data entered by the user, the status of the form, and the status of items on the form. You can get the pointer to any item on the form and make changes in the options or settings of that item. Functions are also provided to indicate the item you want to move to next and to set the next action code.

Your function should return TRUE on success and FALSE on failure. A return value of FALSE causes form processing to terminate immediately. In this case, the high-level processing function (fm_proc() or fm_rd()) will also make an immediate error return. You should reserve a FALSE return for unrecoverable errors.

To quit processing the form without saving the data that the user has entered, you can call sfm_nextitem() with the action code AC_QUIT. To exit from the form and save the data, you can call sfm_nextitem() with the action code AC_EXIT.

If your function fails, you can set the global error code VV_ERR to provide more information about the error to higher-level routines. You can use the existing error codes or add your own error codes and messages. See Chapter 50, "Debugging and Error Handling," for instructions on adding more error codes and error messages.

Designer: You can attach pushbutton action functions to your pushbuttons when you create them in the Designer.

Code: Specify the name of the pushbutton action function to attach when you call pb_def() to define the pushbutton field.