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 selection. The integer b specifies which
button to use for the interaction: 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 return 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,
MENUHIT(9.3) MENUHIT(9.3)
the string "\240X" will appear in the menu as a right-
justified `X' (`040' is the ASCII space character). Menu
strings without fill characters are drawn centered in the
menu.
The fields prevhit and prevtop are used to guide which items
are displayed 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 sub-
menus. 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
undrawn before hfn is called. The return value from
hmenuhit is the menu item selected or (NMenu *)0 if none was
selected. To permit communication 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 `NMitem'. 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;
MENUHIT(9.3) MENUHIT(9.3)
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);