Steps to Creating a Data Form

Our first data entry program is vvbasics.c and is listed here. It creates a data form with a field for entering a person's name, a field for entering a phone number, and some background text. Figure 6.1 illustrates how the form appears on the screen when it is first displayed.

vvbasics.c is a tutorial program. Try compiling, linking, and running this program. You will find it helpful to run the program before reading the explanation.

Figure 6.1: vvbasics Form

This program illustrates the steps to creating and using data forms in your programs. They are as follows:

1. Include the header files for the field types in your data form; include vv_main.h as the last Vermont Views header file.
   
   
2. Declare a pointer to a form structure.
   
   
3. Declare and initialize the data variables for the field(s).
   
   
4. Define a data form with fm_def().
   
   
5. Define the items on the form (data fields, memo fields, pushbuttons, scrollable regions, and so on).
   
   
6. Process the form with fm_proc().
   
   
7. Transfer the data from the field data variables to a data record or otherwise use the entered data.
   
   
8. Free the memory allocated for the form with fm_free().
   
   
9. Free the memory allocated for the data variables.

The following sections detail the above steps and provide further information about how the user interface works.

#include <vv_str.h>            /* Include for string fields            */

#include <vv_main.h>            /* Include global system declarations    */



#ifdef LINT_ARGS

int CDECL main(void);

#else

int CDECL main();

#endif 



int CDECL main()

{

    UCHAR *lastname, *phone_no;    /* Declare data variables            */

    DFORMPTR fmp;                /* Declare pointer to form            */



    vv_init();                /* Initialize Vermont Views            */

    vs_clr();                /* Clear the screen                */



    /* Allocate blank string for lastname and phone number                */

    /* This must precede the fld_def() for the fields                    */

    lastname = mem_stblank(14);

    phone_no = mem_stblank(13);



    /* Define the form and the two fields                            */

    fmp = fm_def(8, 0, 7, 80, (UCHAR)LNORMAL, BDR_DLNP);

    fld_def(1, 1, "Last name:       ", FADJACENT, "!XXXXXXXXXXXXX",

            F_STRING,(PTR)lastname, fmp);

    fld_def(3, 1, "Phone number:    ", FADJACENT, "(UUU)UUU-UUUU",

            F_STRING,(PTR)phone_no, fmp);



    /* Process the form                                        */

    fm_proc(0, fmp);



    /* Transfer or use data (not shown)                            */



    fm_free(fmp);                /* Free memory allocated for form        */

    mem_free((PTR)lastname);        /* Free memory allocated for data        */

    mem_free((PTR)phone_no);



    csr_mv(vs_rowq() - 1, 0);        /* Move the cursor to the last row        */

    vv_exit();                /* Exit Vermont Views                */



    return(0);

}

Step 1: Include the header files for each field type in your data form.

Include the header files for each field type in your data form. In this case, only string fields are used in the form; therefore, only vv_str.h needs to be #included.

As always, vv_main.h must be included in the main program as the last Vermont Views header file.

Step 2: Declare a pointer to a form structure.

Declare a variable of type DFORMPTR. DFORMPTR is a typedef for a pointer to a data form structure.

Naming Tip: In Vermont Views, data forms and menus are both implemented using the same form structure. To avoid confusion, DFORMPTR dfmp is used when referring to data forms, MFORMPTR mfmp is used when referring to menu forms, and FORMPTR fmp is used when either a data or menu form can be used.

Step 3: Declare, allocate storage for, and initialize the data variables.

If you want to collect information typed by the user in the field, you must declare the data variables in which you want to store information. The type of the data variable depends on what kind of information you are collecting from the field. (Alternatively, you can have fields with no underlying data variable, but then you are responsible for writing code that displays and collects information in that field.)

By default, the current values of the data variables are converted to strings (edit buffers) and displayed in the fields when a form is displayed. Therefore, you should initialize the data variables to the values you want initially displayed in the field.

Also, memory must be allocated for the string data variables. This step can be done earlier in the program, for instance, immediately after calling vv_init(). However, it must be done before fld_def() is called.

A function is provided that both allocates string variables and initializes the string to blanks. This function is mem_stblank():

UCHAR *mem_stblank(length)

int length;        /* Length of string to allocate        */

mem_stblank() allocates a string of the specified length (plus an additional space for the null terminator '\0') and sets all positions in the string to spaces. A pointer to the string is returned.

A function is provided that allocates and initializes a block of memory from the heap. This function is mem_get():

PTR mem_get(size)

UINT size;        /* Number of bytes to allocate        */

mem_get() allocates the specified number of bytes from the heap, initializes to null, and returns a pointer to the allocated memory. If you use mem_get() to allocate memory for string data variables, you must remember to add an additional byte for the null terminator.

Caution: String data variables must be long enough to hold the data entered by the user in the field plus the null terminator or memory will be corrupted.

Step 4: Define a data form with fm_def().

A data form is defined using the form definition function, fm_def():

DFORMPTR fm_def(rb, cb, rowq, colq, att, bdrp)

int rb;        /* Beginning row of form window            */

int cb;        /* Beginning column of form window            */

int rowq;        /* Number of rows in form window            */

int colq;        /* Number of columns in form window            */

UCHAR att;        /* Video attribute for form window            */

BORDERPTR bdrp;      /* Pointer to border to use for form window    */

Naming Tip: All functions that deal with data forms contain the abbreviation "fm" for form.

More:

Specifying the fm_def() Arguments

Defaults Set by fm_def()

Defining a Form Larger Than a Window

Defining Data Fields and Prompt Text with fld_def()