Steps to a Choice List Menu

To use choice lists, you must first place the desired list of choices in a memory file and then define the choice list menu. 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."

The tutorial program cl_menu.c, listed below, illustrates the code necessary to create and use a choice list menu.

#include <vv_clist.h>

#include <vv_main.h>



int main(void)

{

    vv_init();



    MFILEPTR list_mfp; 

    CLISTPTR clistp;

    int retcode;

    int choiceno;

    /* Define memory file and read disk file            

    list_mfp = mf_def(20, 35);

    mf_rd("cl_menu.txt", list_mfp);

*/

    /* Define choice list                    

    clistp = cl_def(0, 0, 10, 40, BDR_SLNP, "*INTRO MENU", list_mfp);

*/

    retcode = cl_proc(0, clistp);

/* Get result 

*/

    wn_up(FULL_WNP);

/* Set full screen window

*/

    cs_mv(10, 0, FULL_WNP);

/* Position cursor 

*/

    if (retcode == AC_EXIT)

    {

       choiceno = cl_curnum(clistp);

       v_printf(FULL_WNP, "Selection #%d", choiceno);

    }

    else 

       v_printf(FULL_WNP, "No selection");

    cl_free(clistp);

/* Free memory for choice list

*/

    mf_free(list_mfp);

/* Free memory for memory file

*/

    vv_exit();        

    return(0);

}

/* Exit Vermont Views

*/

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

To use choice lists, you must #include vv_clist.h in the main module and in all other modules using choice lists.

Step 2: 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.
  
  
• nYou can put a comment or explanation of the choice item on the line. The choice itself must be the first part of the line.

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

All choice lists can be placed in a single ASCII text file. Each section of the file can be marked by means of a keyword. When defining a choice list menu, you pass the keyword that corresponds to the choice list menu that you want to appear. Only the section of the file marked by the keyword is displayed in the choice list window. The keyword itself will not be displayed.

A keyword must be in the first column, have the system keyword character (an asterisk by default) as the first character, 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.

An Example of an ASCII Text File Containing Choice Lists

Below is an example of how choice lists should appear in an ASCII text file, named cl_menu.txt, where "*INTRO MENU" and "*FONT MENU (NORMAL)" are keywords for two choice lists.

*INTRO MENU

Start a new document

Edit an existing document

Change directory

Quit

*FONT MENU (NORMAL)

TR10 -- Times Roman 10 point

TR12 -- Times Roman 12 point

CS10 -- Century Schoolbook 10 point

CS12 -- Century Schoolbook 12 point

SV10 -- Souvenir 10 point

SV24 -- Souvenir 24 point

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

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:

Alternatively, you can read into memory only the keyworded section in use. See the sections on dynamically loading sections of a memory file into memory in Chapter 45, "Creating and Viewing Memory Files."

Defining the Memory File

mf_def() has the following calling convention:

MFILEPTR mf_def(maxrows, maxcols)

int maxrows;

int 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 number of characters in the longest line in your ASCII text file. You can specify maxrows to be the number of lines in the ASCII text file, but you may want to specify a larger number in case you insert more items later. You can determine now many rows and columns the memory file must contain by calling the function mf_size():

int mf_size(filespec, rowq_ptr, colq_ptr)

UCHAR *filespec;

int *rowp;

int *colp;

where filespec is the path (optional) and the filename of the ASCII file containing the choice list, and rowq_ptr and colq_ptr are pointers to integer variables to contain the number of rows and columns, respectively.

Reading in the ASCII Text File

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;

MFILEPTR mfp;

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: Define a choice list with cl_def().

After you have the choice lists in a memory file, you define the choice list with the choice list definition function, cl_def():

CLISTPTR cl_def(rb, cb, rowq, colq, bdrp, kwdp, mfp)

int rb;

/* Row to start window at

*/

int cb;

/* Column to start window at

*/

int rowq;

/* Number of rows in window

*/

int colq;

/* Number of columns in window

*/

BORDERPTR bdrp;

/* Border for window

*/

UCHAR *kwdp;

/* Keyword for items

*/

MFILEPTR mfp;

/* Memory file to get text from

*/

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

Step 6: Process the choice list with cl_proc().

To display the choice list and pass control to the user, call the choice list processing function, cl_proc(). You specify the item that you want initially highlighted. Numbering of items starts at 0. The call for cl_proc() is as follows:

int cl_proc(start_item, clistp)

int start_item;

/* Number of item to make current

*/

CLISTPTR clistp;

/* Choice list to process

*/

cl_proc() displays the choice list, if it is not already displayed, and passes control to the user. The user can scroll through the items and select one or can leave the choice list without selecting an item. cl_proc() returns when the user has either exited the choice list (i.e., made a selection) or quit the choice list (i.e., left without making a selection).

cl_proc() will leave the choice list in the state it was found. If the choice list was already displayed when cl_proc() was called, the choice list will remain on the screen. Otherwise, it is taken down.

Step 7: Determine the item number chosen or the text chosen.

cl_proc() returns the #defined value AC_EXIT if the user made a choice from the list and AC_QUIT if the user quit without choosing an item from the list. If the return value of cl_proc() tests positively for AC_EXIT, you can determine the number of the choice list item that was chosen or the string for that item, depending on what is needed for your application.

To determine the item number chosen, use the choice list current item number function, cl_curnum():

int cl_curnum(clistp)

CLISTPTR clistp;

The choice list number is returned by this function.

To determine the text string associated with the chosen item, use the choice list current text function, cl_curtxt():

int cl_curtxt(stp, clistp)

UCHAR *stp;

CLISTPTR clistp;

The text for the chosen item is placed in the string buffer specified as an argument in the function. Take care that the length of the string buffer is at least one character longer than the longest string in the choice list. The extra character space is for the null terminator.

Step 8: Free the choice list with cl_free().

When the choice list menu is no longer needed, free the list structure with cl_free():

void cl_free(clistp)

CLISTPTR clistp;

This function does NOT free the memory file that is used to create the choice list text.

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

If you are finished with all of the contents of the memory file, free this memory before continuing. To do this call the free memory file function, mf_free():

void mf_free(mfp)

MFILEPTR mfp;

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