Steps to Adding a List Box Field to a Data Form

To implement a list box field, you must place the desired list of choices in a memory file, define the list box field, and associate the field with the memory file. You do not need to know the details about the memory file facility to use list boxes. If you want more information about what memory files are and how they can be manipulated, see Chapter 45, "Creating and Viewing Memory Files."

Designer: You can create a list box field using the Designer. If you use the Designer to generate your main program, it will create the skeleton text for the memory file and the code to read the memory file. The text file that is created by the Designer's Main Generator is named clist.txt; you will need to edit this text file to add your selections. See the Designer User's Guide for more information.

If you do not use the Designer to generate your main program, you will need to create or edit the memory file that holds the selections; follow the steps outlined below.

Code: The tutorial program fld_lbox.c, listed below, illustrates the code necessary to implement a list box.

#include <vv_clib.h>
     
#include <vv_str.h>
     
#include <vv_memo.h>
     
#include <vv_lbox.h>
     
#include <vv_main.h>









 

 












#define LEN_ADDR  100;




 

 












#define LEN_PHONE  13;




 

 












#define LEN_NAME   20;




 

 












int CDECL main()




 

 












{




 

 












    int row, col;




 

 












    DFORMPTR fmp;




 

 












    MFILEPTR mfp;




 

 












    UCHAR address[LEN_ADDR + 1];




 

 












    UCHAR phone[LEN_PHONE + 1];




 

 












    UCHAR names[LEN_NAME + 1];







/* Data variable for list box choice







*/















    vv_init();




 

 












    vs_clr();









 

 












    /* Define memory file and read information into it            

    mf_size("names.txt", &row, &col);

    mfp = mf_def(row, col);

    mf_rd("names.txt", mfp);












*/















    /* Define the data form                                

    fmp = fm_def(6, 25, 12, 30, LNORMAL, BDR_SLNP);

    sfm_opt(FMWRAP, ON, fmp);












*/















    /* Define fields on the form and initialize the data variables    

    address[0] = phone[0] = names[0] = '\0';

    memo_def(0, 1, "Address: ", FADJACENT, 1, 17, address, fmp, 1,

            LEN_ADDR);

    fld_def(1, 1, "Phone: ", FADJACENT, "(999)999-9999", F_STRING, phone,

            fmp);









*/















    /* Define the list box field and associate it with the memory file    

    lbox_def(2, 1, 8, 25, LEN_NAME, names, "*Names", mfp, fmp);












*/















    fm_proc(0, fmp);







/* Process the form







*/















    fm_free(fmp);







/* Free the form







*/















    mf_free(mfp);












/* Free the memory file







*/















    vv_exit();




 

 












    return(1):




 

 












}




 

 











Use the following steps to create a list box field in code.





Step 1: Write the text for the list box.





The text for the list box is written in an ASCII text file that you construct with any text editor. Each item in the list box must appear on a single file line.





Step 2: Mark the list box text with a keyword.





Many lists can be placed in a single ASCII text file. Each section of the file is marked with a unique keyword. When defining a list box field, you pass the keyword that corresponds to the list of choices that you want to appear for that field. Only the section of the file marked by the keyword is displayed in the list box window. The keyword itself is not displayed.





A keyword must start in the first column (column 0), have the system keyword character as the first character (an asterisk by default), and be the only text on the line. The keyword can be more than one word in length.





Only those lines containing keywords can have the keyword character in the first column.





Below is an example of how the entries for a list box should be in an ASCII text file, where "*Names" is the keyword for the list box choices.















*Names

John Smith

James McDonald

Robert Carlson

Mary Wilson

Ann Jones














Caution: The asterisk keyword character (*) that marks the keyword must appear in the first column of the line.





Step 3: Include the list box header file vv_lbox.h.





To use list boxes, you must #include vv_lbox.h in all modules that use list boxes and in the main module before vv_main.h.





Step 4: Declare and initialize the underlying data variable.





Declare a string data variable of type UCHAR [ ] or UCHAR * to hold the selected list box item. The size of the data variable must be large enough to hold the data length specified for the field plus the null terminator.





Initialize the variable to '\0' or to a valid selection from the list of choices. If the variable is neither '\0' nor a valid choice, then it is an error.





Step 5: Read the ASCII text file into a memory file.





After you have constructed the file of list box items, you must read it in from disk to a memory file. The steps involved are:












1

Define a memory file with mf_def().









2

Read the ASCII file into the memory file with mf_rd().











Defining the Memory File





The memory file definition function, mf_def(), has the following calling convention:















MFILEPTR mf_def(maxrows, maxcols)

int maxrows;        /* Maximum number of rows            */

int maxcols;        /* Maximum number of columns            */














where maxrows is the maximum number of rows the memory file could contain and maxcols is the maximum number of columns. Generally, you should specify the maximum number of columns to be the length of the longest line in your ASCII text file. You can specify maxrows to be the number of lines in the ASCII text file; however, you may want to specify a larger number in case you want to insert more items later.





Reading in the ASCII Text File





The memory file read function, mf_rd(), reads the ASCII text file and places the text into the memory file you defined. The call for mf_rd() is as follows:















int mf_rd(filespec, mfp)

UCHAR *filespec;            /* Disk file name                    */

MFILEPTR mfp;            /* Pointer to memory file structure        */














where filespec is the path (optional) and the filename of the ASCII file containing the list box and mfp is a pointer to the memory file that you just defined.





Step 6: Define the list box field.





Define the list box field after you have the list box structures in a memory file, and after the data form has been defined. The list box field definition function, lbox_def() defines a list box field and associates it with a memory file:















LBOXPTR lbox_def(lbox_rb, lbox_cb, rowq, colq, datalen, datap, kwdp, mfp,

                 dfmp)




 












int lbox_rb;







/* Beginning row in window for list box







*/















int lbox_cb;







/* Beginning column in window for list box







*/















int rowq;







/* Number of visible rows in list box







*/















int colq;







/* Number of visible columns in list box







*/















int datalen;







/* Length of data variable







*/















UCHAR *datap;







/* Pointer to data variable







*/















UCHAR *kwdp;







/* Keyword marking list box items 







*/















MFILEPTR mfp;







/* Memory file holding list box 







*/















DFORMPTR fmp;







/* Pointer to data form







*/














For lbox_rb and lbox_cb, specify the beginning row and column for the list box (the top left corner). The coordinates are relative to the data form.





For rowq and colq, specify the number of visible row and columns in the list box window.





For datalen, specify the number of characters to copy into the underlying data variable. datalen also sets the length of the highlight bar when the width of the window is larger than the specified datalen.





For datap, specify a pointer to the string buffer to contain the list box selection. Make sure that datap is large enough to hold a string of length datalen plus a null terminator.





For kwdp, specify the keyword for the section of the memory file that contains the choices for the list box. You must include the keyword character in the string, e.g., "*Names". You should set the keyword to NULLP for a memory file that contains only a single list of choices and has no keywords.





For mfp, specify a pointer to the memory file. Note that the memory file must be defined before the call to lbox_def().





Step 7: Process the form.





Process the form with fm_proc(). Collect the data. Free the form with fm_free().





Step 8: Free the memory file with mf_free().





When the form is freed, the memory file containing the list box choices is not freed. If you are finished with all of the contents of the memory file, free this memory before returning from your program. To do this, call the memory file free function, mf_free():















void mf_free(mfp)

MFILEPTR mfp;        /* Memory file to free            */














If you have other sections in the memory file marked with keywords, make sure you do not need these sections before freeing the memory file.









Home 

Contents  

Previous 

Next