Steps to Using Designer Menus

This section explains how to use a menu system that you have created using the Designer. This section applies to a menu system with any number of sub-menu levels. If any of the menu fields in any of the menu forms in the system call and process a data form, an additional step is required which is explained in the next section.

For this example, we will use the Designer menu form tutorial des_menu.c. The top level menu form top_level is stored in the library des_tut.vvd. This menu form has the following menu fields:

Documentation     Software     Quit

The menu fields of the menu top_level have characteristics described in Table 18.1.

Table 18.1: top_level Menu Specifications

The sub-menu doc_menu has four menu fields: User's Guide, Reference Manual, Tutorial, and Quit. This menu has the characteristics described in Table 18.2.

Table 18.2: doc_menu Menu Specifications

The sub-menu soft_menu also has four menu fields: Edit, Compile, Link, Quit. These menu fields have the specifications listed in Table 18.3.

Table 18.3: soft_menu Menu Specifications

The function list generated by the Designer thus contains the following functions:

FUNCLIS des_tut[] = 

{

    {(UCHAR *) "compile",         (PFI)compile},

    {(UCHAR *) "edit_refman",     (PFI)edit_refman},

    {(UCHAR *) "edit_source",     (PFI)edit_source},

    {(UCHAR *) "edit_tut",        (PFI)edit_tut},

    {(UCHAR *) "edit_ug",         (PFI)edit_ug},

    {(UCHAR *) "link",            (PFI)link},

    {(UCHAR *) "sub_quit",        (PFI)sub_quit},

    {(UCHAR *) "quit",            (PFI)quit},

    {(UCHAR *) NULLP,             (PFI)NULLFP}

};

The pre-defined menu action functions MENUCALL(), FORMCALL(), and CHECKMARK() are not included because they are already addressed and prototyped in the Vermont Views libraries.

Note: The above is the listing of functions relevant to the current example. The file des_tut.h in the tutorial directory contains a function listing for all data forms and menus contained in the library des_tut.vvd.

The function list is an array of structures, one element in the array for each function used in the library. The function list serves to convert a string name of a file to a pointer for reference within the program.

The function prototype file, prototyp.h, generated by the Designer contains the following statements:

PROTOTYPE int FASTCALL compile(FORMPTR);

PROTOTYPE int FASTCALL edit_refman(FORMPTR);

PROTOTYPE int FASTCALL edit_source(FORMPTR);

PROTOTYPE int FASTCALL edit_tut(FORMPTR);

PROTOTYPE int FASTCALL edit_ug(FORMPTR);

PROTOTYPE int FASTCALL link(FORMPTR);

PROTOTYPE int FASTCALL quit(FORMPTR);

Step 1: In main.c, include the proper header files.

The following code processes the menu forms described above. Code similar to this is included in the tutorial des_menu.c.

#include <vv_menu.h>

/* Enables use of menus

*/

#include <vv_help.h>

/* Enables use of help system

*/

#include <vv_des.h>

/* Enable use of Designer forms

*/

#include <vv_main.h>

/* Global Vermont Views declarations

*/

#include <prototyp.h>

/* Prototypes for user functions

*/

#include <des_tut.h>

/* Function list

*/

int main()

{

    MFORMPTR top_mfmp;

/* Pointer to top menu form

*/

    DLIBPTR libp;

/* Pointer to library

*/

    vv_init();

/* Initialize Vermont Views

*/

    /* Open library

*/

    libp = dl_open("des_tut.vvd");

    /* Get menu form and sub-menus from library

*/

    top_mfmp = dl_mnget("top_level", SUBMENUS, des_tut, NULLP, libp);

    dl_close(libp);

/* Close library

*/

    mn_proc(0, top_mfmp);

/* Process menu system

*/

    mn_free(top_mfmp);

/* Free menu forms

*/

    vv_exit();

/* Exit Vermont Views

*/

    return(0);

}

The first lines in main.c are the include statements. You must #include all the appropriate header files for your application. This includes all the Vermont Views header files for the facilities you are using in your application, the header file containing the function list, and the header file listing all the function prototypes.

Note the inclusion of the Vermont Views header file vv_des.h. This header file must be included before vv_main.h in the main program and in any module that uses the Vermont Views Designer interface routines. It enables the processing of a Designer menu form within a Vermont Views application.

The order in which you include the header files is important. All other Vermont Views header files must be included before vv_main.h. If you are using prototyping in your code, the header file listing the function prototypes must be included before the header file containing the function list.

Step 2: Make the variable declarations.

You will need to declare a pointer to a library and a pointer to a menu form. The code would be as follows:

MFORMPTR top_mfmp;

/* Pointer to form

*/

DLIBPTR libp;

/* Pointer to library

*/

Step 3: Open the library containing the menu.

Before you can use a menu form, you must open the library file that contains the menu form. Opening a Designer library is done with the Designer library open function, dl_open():

DLIBPTR dl_open(lib_name_stp)

UCHAR *lib_name_stp;      /* Name of library file to open    */

dl_open() opens the file specified in the call and uses the data in the file to initialize a library structure. A pointer to the library structure is returned.

For example, to open the library des_tut.vvd, the call would be as follows:

libp = dl_open("des_tut.vvd");

In applications using several library files, you can keep as many library files open as the operating system can handle. Under PCDOS, this is determined by the number of FILE entries in the config.sys file for the machine.

Step 4: Get the menu form from the library.

Once the library is open, the menu can be read into memory with dl_mnget(). This function allocates memory for a menu form structure and then initializes it from the information it reads from the library about the form. dl_mnget() returns a pointer to the initialized menu form structure. If you choose, dl_mnget() will also resolve all external references to functions, sub-menu forms, and associated data forms. The call for dl_mnget() is as follows:

MFORMPTR dl_mnget(mnname_stp, submn_flag, funclistp, dfmlistp, libp)

UCHAR *mnname_stp;

/* Name of menu form to read from library

*/

int submn_flag;

/* Get sub-menus-SUBMENUS or not-NOSUBMENUS

*/

FUNCLISTPTR funclistp;

/* Pointer to function list

*/

DFMINFOPTR dfmlistp;

/* Pointer to data form information array

*/

DLIBPTR libp;

/* Pointer to form library 

*/

For submn_flag, you can pass SUBMENUS or NOSUBMENUS. If you pass SUBMENUS, dl_mnget() will get all sub-menus and sub-forms called in the menu hierarchy from the specified menu. Thus, if you call dl_mnget() for the top-level menu, all of the sub-menus and sub-forms associated with the form (down to the lowest level) will be read in from the library at this time.

If you specify NOSUBMENUS for submn_flag, only the specified menu form is read from the library. If there are any sub-menus, you will have to call dl_mnget() for each of these individually. If there are any sub-forms, you will have to call dl_fmget() for each of these individually. If you read in a sub-menu, you again have the choice of reading in its sub-menus and sub-forms at that time.

For funclistp, pass the pointer to the function list created by the Designer.

For dfmlistp, pass either a NULLP or the pointer to a DFMINFO structure that contains information about each sub-form. More information about the DFMINFO structure is contained later in this chapter.

Since there are no data forms associated with this menu field in our example, we do not need to worry about the data form information list. Generally, pass NULLP if you are not dealing with menus that have associated data forms or if you do not want to resolve the references to data forms at this time.

In our example, the call to get the top-level menu form and all of the associated sub-menus from the library is as follows:

top_mfmp = dl_mnget("top_level", SUBMENUS, des_tut, NULLP, libp);

Step 5: Close the library.

After you read the menu and sub-menus out of the library, the library file can be closed with the Designer library close function, dl_close():

int dl_close(libp)

DLIBPTR libp;        /* Pointer to library to close        */

Step 6: Process the menu.

From this point, you can use any of the Vermont Views functions that take a form pointer to act on the Designer form. In our example, we have processed the form with a call to mn_proc().

Step 7: Free the menu.

dl_mnget() allocates a menu form structure and then initializes it based on the information found in the library for the specified form. You must pair a call to dl_mnget() with mn_free() so that this menu form structure is freed:

void mn_free(mfmp)

MFORMPTR mfmp;        /* Pointer to menu form structure to free    */

If you used dl_mnget() to also read in the sub-menu forms with the menu, mn_free() will free these menu form structures also.