Steps to Adding a Choice List to a Data Field

To implement choice list entry for a field, you must place the desired list of choices in a memory file and install the choice list in a field. You do not need to know the details about the memory file facility to use choice lists. 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 attach the choice list to the field in 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 Steps 2, 3, and 4 below.

You can also attach a choice list to a field or memo in your code, at any point after you have read the form from the Designer library.

Code: Use the following steps to install a choice list for a data field.

Step 1: Write the text for the choice list.

The text for the choice list is written in an ASCII text file that you construct with any text editor.

• nEach item in a choice list must appear on a single file line.
  
  
• nIf you want the first letter of the choice item to appear in the first position in the field, place the first character of the choice in the first column of the line. This is a prerequisite if you want first character selection.
  
  
• nMake sure the length of the entry fits into the data field or tickertape memo buffer length. The remainder of the line can contain a comment or explanation of the choice item. When a choice is selected for data entry, only as many characters as will fit in the data field or tickertape memo buffer will be transferred to the field.

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

Many choice lists can be placed in a single ASCII text file. Each section of the file is marked with a keyword. When attaching the choice list to a field, you pass the keyword that corresponds to the choice list that you want to appear for that field. Only the section of the file marked by the keyword is displayed in the choice list 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 a choice list should appear in an ASCII text file, named choices.txt, where "*PART CODES" and "*SHIPPING CODES" are keywords for two choice lists.

*PART CODES

A001    Air Brush, small

A002    Air Brush, large

B001    Paint Brush, 1 inch

B002    Paint Brush, 1-1/2 inch

*SHIPPING CODES

UPS    UPS Ground Shipment

UPS2    UPS two-day (Blue)

UPS1    UPS one-day (Red)

FXO    Federal Express Overnight

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

This example is from the tutorial program cl_data.c. In this program, the fields are only four characters long. Therefore, only the first four characters in each line represent the valid entries for the fields. The remainder of the line is explanatory information about the choices.

Step 3: Include the choice list header file vv_clist.h.

To use choice lists, you must #include vv_clist.h in all modules that use choice lists and in the main module before vv_main.h.

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

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

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 choice list and mfp is a pointer to the memory file that you just defined.

Step 5: Install a choice list in the field.

After you have the choice list structures in a memory file, you install a choice list for a specific field with the set field choice list function, sf_clist():

int sf_clist(keyword, options, mfp, fldp)

UCHAR *keyword;

/* Keyword marking choice list items 

*/

int options;

/* Choice list options

*/

MFILEPTR mfp;

/* Memory file holding choice list

*/

FIELDPTR fldp;

/* Field to assign choice list

*/

For the argument keyword you should specify the keyword for the section of the memory file that contains the choice list for the field in question. You must include the keyword character in the string, e.g., "*PART CODES". You should set the keyword to NULLP for a memory file that contains only a single choice list and has no keywords.

The options argument allows you to set any of the choice list options to ON. Choice list options are listed in Table 12.1. If you do not want to set any options on, specify 0. The default is for automatic placing and sizing of the choice list window. All other options are OFF.

In the code example below, the following line:

sf_clist("*PART CODES", CLWRAP | CLCHSELECT | CLCONFIRM,

           list_mfp, part_fldp);

installs a choice list, whose items are listed under the keyword *PART CODES in the memory file list_mfp, in the part field. Wrap, first character selection, and character confirmation are set ON for the choice list.

You can attach a choice list to a tickertape memo field. Specify a pointer to the memo field as the fldp parameter in the call to sf_clist().

Step 6: Process the form.

Process the form with fm_proc().

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

When the form is freed, the choice lists associated with any fields on the form are also freed. However, the memory file containing the choice list 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.

The tutorial program cl_data.c, listed below, illustrates the code necessary to install a choice list for two fields.

#include <vv_str.h>

#include <vv_clist.h>

#include <vv_main.h>

int main(void);

{

    MFILEPTR list_mfp; 

    DFORMPTR dfmp;

    DFIELDPTR ship_fldp, part_fldp;

    UCHAR *shipcode;

    UCHAR *part_num;

    vv_init();

    shipcode = mem_stblank(4);

/* Allocate memory for data 

*/

    part_num = mem_stblank(4);

    /* Define form

*/

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

    /* Define memory file, read file from disk

*/

    list_mfp = mf_def(20, 35);

    mf_rd("cl_data.txt", list_mfp);

    /* Define two fields and attach choice list to each

*/

    part_fldp = fld_def(0, 0, "Part code ", FADJACENT,

            "XXXX", F_STRING, part_num, dfmp);

    sf_clist("*PART CODES", CLWRAP | CLCHSELECT | CLCONFIRM,

            list_mfp, part_fldp);

    ship_fldp = fld_def(1, 0, "Shipping Code ", FADJACENT,

            "XXXX", F_STRING, shipcode, dfmp);

    sf_clist("*SHIPPING CODES", 0, list_mfp, ship_fldp);

    fm_proc(0, dfmp);

/* Process form

*/

    fm_free(dfmp);

/* Free form

*/

    mf_free(list_mfp);

/* Free memory file

*/

    mem_free(shipcode);

/* Free data variables

*/

    mem_free(part_num);

    vv_exit();

/* Exit Vermont Views

*/

    return(0);

}