Steps to a Branching Menu

The following program example (tutorial program mn_basics.c) creates a menu demonstrating how to code a top-level menu with three fields. One of the top-level menu fields has an associated sub-menu. All other top-level menu fields call action functions.

mn_basics.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.

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

#include <vv_menu.h>

#include <vv_main.h>

/* Define the action functions called within the menu

*/

int act_return(mfmp)

MFORMPTR mfmp;

/* Passed pointer to menu form

*/

{

    return(EXITMENU);

/* Return and exit from menu

*/

}

act_bell(mfmp)

MFORMPTR mfmp;

/* Passed pointer to menu form

*/

{

    bell_vv();

/* Ring bell

*/

    return(SAMELEVEL);

/* Return and stay at menu

*/

}

int main(void)

{

    MFORMPTR top_mfmp, sub_mfmp;

    vv_init();

    vs_clr();

/* Define sub-menu form

*/

    sub_mfmp = mn_def(MNSTANDARD, AUTOPLACE, AUTOPLACE, AUTOSIZE,

            AUTOSIZE, LMNINACT, BDR_SLNP);

/* Define fields on sub-menu

*/

    mnf_def(0, 0, "BEEP", "This choice will beep", NULLP,

            act_bell, sub_mfmp);

    mnf_def(1, 0, "EXIT", "This choice will exit the menu",

            NULLP, act_return, sub_mfmp);

/* Define top menu form

*/

    top_mfmp = mn_def(MNSTANDARD, 0, 0, 1, 80, LMNINACT, BDR_NULLP);

/* Define fields on top menu

*/

    mnf_def(0, 0, "CALL SUB-MENU", 

            "This choice will go to a sub-menu",

            sub_mfmp, MENUCALL, top_mfmp);

    mnf_def(0, 20, "BEEP", "This choice will beep", NULLP,

            act_bell, top_mfmp);

    mnf_def(0, 40, "EXIT", "This choice will exit the menu",

            NULLP, act_return, top_mfmp);

    mn_proc(0, top_mfmp);

/* Process menu

*/

    mn_free(top_mfmp);

/* Free menu forms

*/

    mn_free(sub_mfmp);

    vv_exit();

/* Exit Vermont Views

*/

    return(0);

}

Figure 19.1 illustrates the top-level menu and one of its sub-menus.

Figure 19.1: mn_basics.c Menu System

Step 1: Include the vv_menu.h header file.

The vv_menu.h header file contains all the externs, definitions, and function prototyping needed to include branching menus in your program. You must include this header file in all modules that use menu functions and in your main() module before vv_main.h.

As always, you must include vv_main.h in the main program after all other Vermont Views header files.

Step 2: Declare pointers to the menu and sub-menu forms.

A pointer to a menu form structure is of type MFORMPTR. Declare pointers to all menu and sub-menu forms in your menu tree. You do not have to allocate memory for the structures; the menu definition function does that for you.

Step 3: Define the menu forms with mn_def().

A menu form is defined using the menu definition function, mn_def():

MFORMPTR mn_def(mn_type, rb, cb, rowq, colq, att, bdrp)

long mn_type;

/* MNSTANDARD or MNAUTOSELECT

*/

int rb;

/* Screen row to begin menu form window

*/

int cb;

/* Screen column to begin menu form window  

*/

int rowq;

/* Number of rows in menu window

*/

int colq;

/* Number of columns in menu window

*/

UCHAR att;

/* Attribute to use for menu window

*/

BORDERPTR bdrp;

/* Border to use for menu window

*/

An explanation of each argument follows:

mn_type: Specify one of the following:

rb, cb: For the location of the menu (rb and cb), specify the video screen coordinates where you want the menu or sub-menu to appear.

Especially for sub-menus, you may want the Vermont Views system to automatically determine where the menu should be located. To have the system automatically calculate the beginning coordinates for a menu form, specify AUTOPLACE for either rb or cb. If you specify Menu form:AUTOPLACE, the system places the menu so that it does not obscure the calling menu field. If AUTOPLACE is specified for a top-level menu form, the form will appear at (0, 0) on the video screen.

rowq, colq: For rowq and colq, specify the size you want the menu form window to be. You should take into account the rows and columns needed for the border characters and the window margins.

Especially for sub-menus, you may want the Vermont Views system to automatically determine what size to make the menu form window. To have the system automatically calculate the size of the menu form window, specify Menu form:AUTOSIZE for either rowq or colq. If AUTOSIZE is specified, the system will size the menu window to the smallest size that will accommodate all menu fields and background fields.

You can specify AUTOSIZE or AUTOPLACE or both in the mn_def() call. As an alternative to specifying both AUTOSIZE and AUTOPLACE in the mn_def() call, you can use the define autoplace and autosize menu function mn_defauto():

int mn_defauto(mn_type, att, bdrp)

See the Function Reference for more information on mn_defauto().

att: Video display in the Vermont Views system is controlled by logical attributes. Logical attributes are defined such that monochrome attributes are used when the program is running in a monochrome mode and color attributes are used when the program is running in a color mode. A partial list of the system logical attributes is shown in Table 19.1. A complete list of logical attribute definitions can be found in Chapter 46, "Controlling Color with Logical Attributes."

Specify the logical attribute that you want the background of the menu to be. The fields themselves will appear in the menu form using the active, inactive and unavailable attributes.

Table 19.1: Partial Listing of Logical Attribute Definitions

bdrp: Specify a pointer to the border style that you want to appear around the menu. The system border styles are listed in Table 19.2. Appearance of borders is operating system dependent.

Table 19.2: Border Types

Step 4: Define the menu fields with mnf_def().

After forms are defined for the various levels of a menu, a menu field must be defined for every field of every menu. You should define the menu fields in the order that you want the user to move through them. Generally, you will define the menu fields from left to right or top to bottom.

Menu fields are defined with the menu field definition function, mnf_def():

MFIELDPTR mnf_def(rb, cb, item, msg_stp, sub_fmp, action_fp, mfmp)

int rb;

/* Row in which field is displayed

*/

int cb;

/* Column to begin display of field

*/

UCHAR *item;

/* String to appear as menu field

*/

UCHAR *msg_stp;

/* Message displayed when field is highlighted

*/

MFORMPTR sub_fmp;

/* Pointer to sub-form (menu or data)

*/

int action_fp();

/* Pointer to action function

*/

MFORMPTR mfmp;

/* Pointer to menu containing field

*/

An explanation of each argument in the mnf_def() function follows:

rb, cb: The beginning row and column of the menu field are based on the coordinates within the menu form window.

item: Specify the string that will appear as the menu field. In constructing menus, you can make the menu field strings different lengths. A field can contain more than one word.

msg_stp: Specify the string to be displayed in the menu message window when this field is highlighted. Specify a NULLP if no message is desired.

Caution: Care should be taken when defining large menus that might take the entire video screen. If there is not room for the menu message window, the message window may overlap the menu. Either do not specify messages for such menus, or define the menu so that the menu window will not interfere with the message window.

sub_fmp: Specify

• nA pointer to a menu form, MFORMPTR mfmp, if you want a sub-menu to appear when this field is selected. (The sub-menu must have already been defined with a call to mn_def() or have already been read from a Designer library.)
  
  
• nA pointer to a data form, DFORMPTR dfmp, if you want to process a data form when this field is selected. (The sub-form must have already been defined with a call to fm_def() or have already been read from a Designer library.)
  
  
• nNULLP if you want the menu to call our CHECKMARK() function.
  
  
• nNULLP if your action function reads the menu or data form from the Designer library or defines the form in code.
  
  
• nNULLP if your action function does not process a menu or data form.

action_fp: Vermont Views provides three action functions: MENUCALL(), FORMCALL(), and CHECKMARK(). You can use one of these or provide your own. Specify:

• n if you want the menu field to display the sub-menu associated with this field. In this case, you should specify a pointer to the sub-menu for the sub_fmp argument.
  
  
• n if you want the menu field to process the associated data form. In this case, you should specify a pointer to the data form for the sub_fmp argument.
  
  
• n if you want to toggle the display of the checkmark character for this menu field. In this case, NULLP should be specified for the sub_fmp argument.
  
  
• nA pointer to your own action function, if you want to invoke this routine when the field is selected.

mfmp: Specify the menu form that this menu field will appear on.

Step 5: Write all action functions.

Menu action functions are C functions that perform specific tasks. All action functions must accept a pointer to the calling menu form and return an integer. The return value is used to indicate the next menu level and is interpreted as follows:

Table 19.3: Action Function Return Values & Their Meanings

You must write any action functions not provided in the library. Vermont Views provides the three action functions MENUCALL(), FORMCALL(), and CHECKMARK(), which carry out tasks commonly called from menu fields.

More information about the three menu action functions that the system provides and about how to write your own menu action functions is provided in Chapter 33, "Writing Menu Action Functions." Details on using checkmarks in menus can be found in Chapter 21, "Changing the Appearance of Menus."

Step 6: Pass control to the user with mn_proc().

After you have defined the menu forms, menu fields, and action functions, you pass control to the user by calling the menu processing function, mn_proc():

int mn_proc(start_item, mfmp)

int start_item;

/* Num. of menu field initially highlighted

*/

MFORMPTR mfmp;

/* Pointer to the top-level menu form  

*/

When mn_proc() is called in the program example, the form pointed to by top_mfmp is displayed and the specified field (start_item) is highlighted initially. If the highlighted field calls an autoselect sub-menu, the sub-menu is displayed and, by default, the first field in the sub-menu is highlighted. Control is turned over to the user. Keyboard and mouse input are interpreted by searching the system event table (SYSETP), the form event table (FMETP), and then the menu field event table (MNETP).

Function mn_proc() returns when either (1) the user presses the Quit key from the top-level menu, or (2) FUNCERROR or EXITMENU is returned by a called action function.

Step 7: Free memory for all menu forms with mn_free().

When you are finished using any menu form, you can free the memory allocated for it by calling the menu free function, mn_free():

void mn_free(MFORMPTR mfmp)

MFORMPTR mfmp;        /* Pointer to form (data or menu) to free        */

This function frees all memory allocated for the menu field structures for this form and the menu form structure.