Steps to Adding a Scrollable Region to a Form

Designer: See the Designer User's Guide for more information about adding a scrollable region to a Designer form.

Code: Use the following steps to add a scrollable region to a data form:

The code example listed below creates a data form with a scrollable region. To keep the program simple, the only items on the form are a scrollable region and background text used as a title for the scrollable region. Figure 10.1 illustrates what the scrollable region created during this program would look like. Similar code can be found in the tutorial program sr.c.

#include <vv_sr.h>        /* Include scrollable region header        */

#include <vv_str.h>        /* Include string field header file        */

#include <vv_main.h>        /* Include main header file            */

#define DATAROWQ 25        /* Number of data rows                */



typedef struct            /* Declare structure                */

{

    UCHAR lastname[16];

    UCHAR phone_no[16];

} MYSTRUCT;

 

/* Define array of structures.  Because the array is                 */

/* declared globally, all elements are initialized to zeros.        */



MYSTRUCT myinfo[DATAROWQ];



int main(void)

{

    DFORMPTR dfmp;            /* Declare pointer to form            */

    SRPTR srp;            /* Declare pointer to scrollable region     */



    vv_init();            /* Initialize Vermont Views            */

    

    /* Define a form and background text                        */

    dfmp = fm_def(0, 0, 24, 80, LNORMAL, BDR_DLNP);

    bg_txtdef(4, CENTER_TEXT, "Information Requests", LNORMAL, dfmp);



    /* Define scrollable region                            */

    srp = sr_def(8, 0, 8, 78, LNORMAL, BDR_SLNP, DATAROWQ, myinfo,

                 sizeof(MYSTRUCT), dfmp);



    /* Define last name and phone number fields                     */

    srf_def(1, "Last name:  ", FADJACENT, "!XXXXXXXXXXXXXX", F_STRING,                  myinfo[0].lastname, srp);

    srf_def(35, "Phone number:  ", FADJACENT, "(UUU)UUU-UUUU", F_STRING,

            myinfo[0].phone_no, srp);



    fm_proc(0, dfmp);        /* Process form                     */



    /* Collect data (not shown)                             */



    fm_free(dfmp);            /* Free memory for form              */

    

    vv_exit();            /* Exit Vermont Views system          */

    return(0);

}

Step 1: Include the scrollable region header file vv_sr.h.

To include a scrollable region in a data form, you must include the header file vv_sr.h in the main program and in all modules that reference scrollable regions. You must also include the header files for each field type in the scrollable region. As always, the main header file, vv_main.h, must be included in the main program.

Step 2: Declare a pointer to a scrollable region.

SRPTR is a typedef for a pointer to a scrollable region structure. Declare the variable that will hold the scrollable region pointer as SRPTR.

Step 3: Define a data structure.

The data structure should have one member for each field in a row. For example, if we have a scrollable region with an integer field, a string field, and a decimal field. The data structure definition would be as follows:

typedef struct

{

    int a;

    UCHAR b[FIELD_LENGTH + 1];

    long c;

} ROW_STRUCT;

Caution: The structure must not contain pointers to data. If the structure is to hold data for any string-type fields, these members of the structure must be declared as a character arrays (as shown) instead of pointers to a string.

Designer: Vermont Views uses offsets to read and store data in the structure; therefore, all data for a given row in the scrollable region must be contiguous so each member can be accessed with offsets. If you want to store additional data for each row, you can add it to the end of the data structure.

Code: You can store additional data for each row in the scrollable region data structure. When you define the fields in the scrollable region with srf_def(), pass a pointer to the correct structure member for each field. All other structure members will be ignored by Vermont Views.

Step 4: Define an array of data structures.

The size of the array of data structures should be at least the number of data rows for the scrollable region. If the scrollable region has DATAROWQ data rows, then the array would be defined as follows:

ROW_STRUCT my_region[DATAROWQ];

Step 5: Initialize the members of all data structures in the array.

This step is not shown in the code example, because the array is globally defined, which initializes all bytes to 0.

Since the contents of the data variables are automatically displayed in the visible scrollable fields and INITIALBLANKS has only limited support, you should initialize the array of data structures. For strings, you should either (1) put a null terminator '\0' as the first character in the array or (2) copy a string into the character array.

The following code is suggested for defining and initializing the members of the structure in the array:

ROW_STRUCT my_region[DATAROWQ];

int i;



for(i = 0; i < DATAROWQ; i++)

{

    my_region[i].a = 0;

    my_region[i].b[0] = '\0';

    my_region[i].c = 0L;

}

Step 6: Define the scrollable region with sr_def().

A scrollable region is defined using the scrollable region definition function, sr_def():

SRPTR sr_def(rb, cb, rowq, colq, att, bdrp, datarowq, structp, struct_size, dfmp)

int rb;

/* Form row to begin region

*/

int cb;

/* Form column to begin region

*/

int rowq;

/* Number of rows in region

*/

int colq;

/* Number of columns in region

*/

int att;

/* Video attribute for region background

*/

BORDERPTR bdrp;

/* Pointer to border to use for region

*/

int datarowq;

/* Maximum number of rows of data

*/

PTR structp;

/* Pointer to data structure

*/

int struct_size;

/* Size of data structure

*/

DFORMPTR dfmp;

/* Pointer to form

*/

Naming Tip: Functions that deal with scrollable regions start with the abbreviation "sr_", for scrollable region.

For the arguments rb, cb, rowq, and colq, specify the location and size of the scrollable region. The origin of the scrollable region (the beginning row and column) is based in the form window. Coordinate (0, 0) is the position in the upper-left corner of the window, immediately within the borders and margins, if any. When specifying the size of the scrollable region (rowq and colq), if you want the region to have a border, take into account that two rows and two columns will be used for the border characters.

For att, specify the video attribute you want the background of the scrollable region to have. See the table of available logical attributes in the "Tables" section of the Function Reference. See Chapter 46, "Controlling Color with Logical Attributes," if you would like more information about how to use logical attributes.

For bdrp, specify one of the system-defined pointers to a border as listed in Table 10.1. Appearance of borders is operating system dependent.

For the number of data rows, datarowq, specify the maximum number of rows that you want the user to be able to enter. This number must be greater than or equal to the number of visible data rows in the scrollable region. Be certain, though, that the data arrays defined for fields of the region contain at least datarowq rows.

For structp, specify a pointer to the beginning of the array of data structures. For maximum portability between operating systems, cast the pointer to be of type PTR.

Table 10.1: Border Types

For struct_size, give the size of one data structure (not of the array of structures) in bytes. It is best to use the sizeof operator to determine the size of your structure.

Step 7: Define the scrollable region fields with srf_def().

You should define the fields for only a single row of the scrollable region. They should be defined in the order that you want the user to move through them on any row. The same definitions will apply to each row of the region.

Define each field in the scrollable region row with the scrollable region field definition function, srf_def():

DFIELDPTR srf_def(prompt_cb, prompt, fld_cb, picp, fld_type, datap, srp)

int prompt_cb;        /* Beginning column for prompt    */

UCHAR *prompt;        /* Prompt string                */

int fld_cb;            /* Beginning column for field        */

UCHAR *picp;        /* Picture string                */

int fld_type;        /* Field type                */

--- datap;            /* Pointer to the data array        */

SRPTR srp;            /* Pointer to scrollable region    */

If you want a prompt string that appears on every visible row of the scrollable region, specify the beginning column for the prompt in the scrollable region, and the string. Numbering of columns starts at 0 immediately within the border, if any, of the scrollable region. If you do not want a repeating prompt, specify NULLP for the prompt string.

For fld_cb, specify the column in the scrollable region that you want the field to start on. You can specify FADJACENT to place it immediately after the prompt. Do not specify FABOVE or FBELOW.

For the picture string and field type arguments, follow the rules for any data field depending on what type of data you want to collect. See Chapter 7, "Standard Data Field Types."

For the data variable, pass a pointer to the first structure member in the array that corresponds to the scrollable field.

Note that you do not need to specify the row on which to place the field. Vermont Views places the field on the first row of the scrollable region and automatically generates the additional fields needed for the remaining visible rows in the scrollable region.