Installing a Virtual Form Scrolling Function

You might want to scroll other things along with the user's movement in a virtual form. One example is when creating a spreadsheet with row and column labels, as shown in Figure 14.1. The row and column labels could be created using virtual forms initialized with background text. The virtual form would contain a grid of fields.

When the user moves in the virtual form, you would also want the row and column labels to scroll appropriately. To do this, you would write and install your own virtual form scrolling function. The virtual form scrolling function is called whenever the user scrolls within the virtual form. The system passes to the function the change in the user's row position within the virtual form, the change in the user's column position, and the current form pointer. Your function should return TRUE on success and FALSE if a fatal error occurs. A FALSE return should be reserved for non-recoverable errors, as a FALSE return causes form processing to terminate.

Caution: Do not attempt to exit or quit from the form, suspend the form, or move to another item on the form in your virtual form scrolling function. This function cannot change the processing flow in the current form in any way.

Figure 14.1: Column and Row Labels for a Virtual Data Form

The call for your scrolling function should be as follows:

int my_scrlfp(delta_rowq, delta_colq, dfmp);

int delta_rowq;        /* Change in rows                    */

int delta_colq;        /* Change in column position            */

DFORMPTR fmp;        /* Pointer to current data form        */

A negative number passed for delta_rowq indicates that the user scrolled up. A negative delta_colq indicates that the user scrolled left.

Designer: You can install the virtual form scrolling function from within the Designer. See the Designer User's Guide for more information. You can also install the scrolling function in your code, at any point after reading the form from the Designer library.

General: To install the virtual form scrolling function for the form in code, call the set virtual form scroll function function, sfm_vscrlfp():

void sfm_vscrlfp(scrl_fp, dfmp);

int (*scrl_fp)();        /* Pointer to virtual form scroll function    */

DFORMPTR dfmp;        /* Pointer to data form                */

Note: You can make the pointers to virtual forms used for row and column labels accessible by installing them in the user pointer in the main virtual form. You can then access them from the form pointer passed to the scrolling function.

A better way to implement scrolling row and column labels is to use virtual windows. See Chapter 23, "About Windows," for more details.