*** UNIX MANUAL PAGE BROWSER ***

MENUHIT(9.3) MENUHIT(9.3) NAME menuhit, hmenuhit - present user with menu and get selection SYNOPSIS #include <jerq.h> int menuhit(m, b) Menu *m; #include <menu.h> NMitem *hmenuhit(m, b) NMenu *m; DESCRIPTION Menuhit presents the user with a menu specified by the Menu pointer m and returns an integer indicating the selection made, or -1 for no se- lection. The integer b specifies which button to use for the interac- tion: 1, 2 or 3. Menuhit assumes that the button is already depressed when it is called. The user makes a selection by lifting the button when the cursor points at the desired selection; lifting the button outside the menu indicates no selection. Menus can be built in two ways, either as an array of strings or with a generator function: typedef struct { char **item; /* string array, ending with 0 */ char *(*generator)(); /* used if item == 0 */ short prevhit; /* offset from top of last select */ short prevtop; /* topmost item displayed */ } Menu; char *menutext[]={"Item 0", "Item 1", "Item 2", 0}; Menu stringsmenu={ menutext }; or char *menugen(); Menu genmenu={ (char **)0, menugen }; The generator function is passed an integer parameter n, and must re- turn the string for the nth menu entry, or 0 if n is beyond the number of entries in the menu. The n's may come in any order but the result is only needed until the next call. Regardless of the method of generation, characters with the 0200 bit set are regarded as fill characters. For example, the string "\240X" will appear in the menu as a right-justified is the ASCII space charac- ter). Menu strings without fill characters are drawn centered in the menu. The fields prevhit and prevtop are used to guide which items are dis- played and which item the mouse points to initially. They should be nonnegative. Both menuhit and hmenuhit may choose to ignore these fields. Hmenuhit supports hierarchical menus. Submenus are denoted graphically by a right-pointing arrow. Moving the cursor onto the arrow causes the submenu to appear. Hierarchical menus are built of NMitems defined as typedef struct NMenu { char *text; char *help; struct NMenu *next; void (*dfn)(), (*bfn)(), (*hfn)(); long data; } NMitem; The text field is shown to the user; characters with the 0200 bit set behave as above. The contents of the help field are shown whenever the user holds down button 1 at the same time as the button specified by the parameter b. If b is 1, you get help all the time. The next field is the address of a submenu or (NMenu *)0 if there is none. The two functions (*dfn)() and (*bfn)() support dynamic submenus. Dfn is called just before the submenu is invoked. Its argument is the current menu item. Similarly, bfn is called with the current menu item just after the submenu has finished. Hfn is called only when a menu item is selected; its argument is the current menu item. The menu has been un- drawn before hfn is called. The return value from hmenuhit is the menu item selected or (NMenu *)0 if none was selected. To permit communica- tion between menu functions and the calling program, the data field is available for the user; it is ignored by hmenuhit. An NMenu, like a Menu, may be built by list or by generator. An NMenu generator takes an integer parameter n and returns a pointer to an In either case, the list of menu items is terminated by an item with a 0 text field. EXAMPLES Simple code to use stringsmenu declared above: switch(menuhit(&stringsmenu, 3)){ case 0: item_0(); break; case 1: item_1(); break; case 2: item_2(); break; case -1: noselection(); break; } To provide a submenu for item 1: NMitem *gen(); NMenu i1list = { 0, gen }; void item_2(), item_3(); NMitem imenu = { { "item 1", "item 1 help", &i1list }, { "item 2", "item 2 help", 0, 0, 0, item_2 }, { "item 3", 0, 0, 0, 0, item_3 }, { 0 } }; NMenu b3 = { imenu }; (void)hmenuhit(&b3, 3); MENUHIT(9.3)