Creating a Multi-toggle Field

To create a multi-toggle field you must first define a standard data field, either in code or using the Designer. Any of the following standard data fields can be converted to a multi-toggle: string, character, date, time, integer, short integer, long integer, decimal, single-precision floating point, or double-precision floating point. See Chapter 7, "Standard Data Field Types," to learn how to create a standard data field.

The multi-toggle choices are specified using a memory file. You do not need to know the details about using the Vermont Views memory file facility to implement a multi-toggle. 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 convert a data field to a multi-toggle 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; you will need to edit the text file, clist.txt, 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.

You can also convert a data field to a multi-toggle in your code at any point after you have read the form from the Designer library.

Code: Use the following steps to create a multi-toggle in code. These steps assume that you have already created the standard data field and have #included the header file required to implement the specified data field type (for example, vv_str.h, vv_date.h, vv_int.h, etc.).

Step 1: Write the text for the list of multi-toggle choices.

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

• nEach item in the list must appear on a single file line.
  
  
• nThe length of the entry must fit into the data field.

By default, the first choice in the list is the first choice that is displayed in the field during form processing.

Step 2: Mark the multi-toggle list text with a keyword.

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

*PART CODES

A001

A002

B001

B002

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

Step 3: Include the multi-toggle header file vv_mtog.h.

Include the multi-toggle header file vv_mtog.h in all modules that use multi-toggles and in your main() module before vv_main.h.

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

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

Defining the Memory File

The function mf_def() has the following function call:

MFILEPTR mf_def(maxrows, maxcols)

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 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)

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

Step 5: Assign a multi-toggle list to the field.

After you have the multi-toggle lists in a memory file, you assign a multi-toggle list to a specific field with the set field to multi-toggle function, sf_mtoggle():

int sf_mtoggle(keyword, mfp, fldp)

UCHAR *keyword;        /* Keyword marking multi-toggle list items        */

MFILEPTR mfp;        /* Memory file holding multi-toggle list             */

FIELDPTR fldp;        /* Field to assign multi-toggle list            */

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

In the code example below, the following line:

sf_mtoggle("*PART CODES", list_mfp, part_fldp);

assigns a multi-toggle list, whose items are listed under the keyword *PART CODES in the memory file list_mfp, to the part field part_fldp.

Step 6: Process the form.

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

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

When the form is freed, the multi-toggle structures associated with any fields on the form are also freed. However, the memory file containing the multi-toggle lists 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 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 following example demonstrates the steps needed to create a multi-toggle field in code. Code similar to this example is available in the tutorial fld_mtog.c.

#include <vv_str.h>        /* Enable string fields                */

#include <vv_mtog.h>        /* Enable multi-toggles                */

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



#ifdef LINT_ARGS

int CDECL main(void);

#else

int CDECL main();

#endif



int CDECL main()

{

    MFILEPTR list_mfp;

    DFORMPTR fmp;

    DFIELDPTR ship_fldp, part_fldp;

    UCHAR *shipcode;

    UCHAR *part_num;



    vv_init();            /* Initialize Vermont Views            */

    vs_clr();            /* Clear the screen                */



    /* Allocate space and initialize the space to blanks for the        */

    /* ship code and the part number                            */

    shipcode = mem_stblank(4);

    part_num = mem_stblank(4);



    /* Define and read in the memory file which contains the            */

    /* multi-toggle choice lists                            */

    list_mfp = mf_def(20, 35);

    mf_rd("cl_data.txt", list_mfp);



    /* Define the form and the first field                        */

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

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

        (PTR)part_num, fmp);



    /* Assign the multi-toggle choice list to the field            */

    sf_mtoggle("*PART CODES", list_mfp, part_fldp);



    /* Define the second field and assign the multi-toggle choice list    */

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

        F_STRING, (PTR)shipcode, fmp);

    sf_mtoggle("*SHIPPING CODES", list_mfp, ship_fldp);



    fm_proc(0, fmp);        /* Process the form                */



    fm_free(fmp);            /* Free the form                    */

    mf_free(list_mfp);        /* Free the memory file                */

    mem_free((PTR)shipcode);    /* Free the data variables            */

    mem_free((PTR)part_num);



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

    vv_exit();            /* Exit Vermont Views                */



#if VMS

    return;

#else

    return(0);

#endif

}