Menus

Pull-down menus are a familiar part of most graphical user interfaces, and CCATSL make it very easy to include menus in your own programs. The simplest way is to use MenuCL, which creates a menu and then waits for the user to select one of the items. Sometimes you will want several menus side-by-side, each containing logically related functions. In this case you must define each menu separately with MenuOpenCL giving each menu a unique menu ID, and then call MenuSelectCL to obtain the user's selection. Once opened, a menu can be removed with MenuCloseCL.

It is sometimes useful to restrict the items that a user can select from your menus. CCATSL allows you to deactivate individual items in a menu (deactivated items will appear `grayed'), or even an entire menu, using MenuRestrictCL and MenuRestCL. Deactivated items can be re-activated with MenuWakeCL.

Many of the example programs provide illustrations of the menu routines.

MenuCL

This routine creates a single pull-down menu, and then waits for the user to select one of the items.

	int MenuCL (	char *caption,
		char *itemList);

	caption		The string which appears at the top of the menu. Until the user clicks on it, only caption is visible, below which the entire menu will appear.
	itemList		The list of menu items. This should be a $-separated list of strings. Each string represents a menu item, except for the special string (-) which is interpreted as a separator (a horizontal line dividing menu items). See the example below.

The return value is the index of the selected item (starting from 1).

/*   /examples/chapter5/ctmenu.c  */
#include <catam.h>
int MainCL(void)
{
  int opt;
  do {
    opt=MenuCL("Options","Option 1$(-)$Option 2$Quit");
  } while (opt!=4);
  return 0;
}

MenuOpenCL

This routine defines a menu, opens it, and associates it with a menu ID. MenuSelectCL can be used to give the user the opportunity to select an item from such a menu.

	void MenuOpenCL (	int id,
		char *caption,
		char *itemList);

	id		The menu ID to associate with the menu. If a menu already exists with the same ID, the previous menu will be destroyed. Valid IDs are in the range 4 - 20.
	caption		The string to appear at the top of the menu. Only the caption is visible until the user clicks on it, when the entire menu will appear beneath.
	itemList		The list of items for the menu. This should be a $ separated list of string. Each string represents a menu item, except for the special string (-) which is interpreted as a separator (a horizontal line dividing menu items).

MenuSelectCL

This routine waits for the user to select one of the items from one of the currently open menus (see MenuOpenCL) and returns the corresponding menu ID and item number. Only active menu items can be selected (see MenuWakeCL, MenuRestCL and MenuRestrictCL to see how to restrict the set of possible selections).

	void MenuSelectCL (	int *id,
		int *item);

	id		Pointer to a variable to hold the menu ID of the selected item when MenuSelectCL returns.
	item		Pointer to a variable to hold the index (1, 2, etc.) of the selected item when MenuSelectCL returns.

/*   /examples/chapter5/select_f.c   */
#include <catam.h>

int MainCL(void)
{
  int nmenu,nitem;
  MenuOpenCL(4,"File","Quit");
  MenuOpenCL(5,"Edit","Paste");
  MenuSelectCL(&nmenu,&nitem);
}

MenuCloseCL

This routine destroys an open menu (see MenuOpenCL). A typical use of MenuCloseCL is to replace one set of menus with another.

	void MenuCLoseCL (	int id);

id

The menu ID of the menu to be closed and deleted.

MenuRestCL

This routine deactivates all the items of a menu, causing MenuSelectCL to ignore attempts to select any of its items. The items will appear `grayed' to the user.

	void MenuRestCL (	int id);

id

The ID of the menu to rest.

MenuWakeCL

This routine makes all items of a menu active again (see also MenuSelectCL, MenuRestCL and MenuRestrictCL.

	void MenuWakeCL (	int id);

id

The ID of the menu.

MenuRestrictCL

This routine activates or deactivates a selection from a menu.

	void MenuRestrictCL (	int id,
		int item,
		int control);

	id		The ID of the menu.
	item		The index (1, 2, etc.) of the item to activate or deactivate.
	control		control=0 deactivates the item, control=1 activates it.