defpup(3G)defpup(3G)NAMEdefpup - defines a menu
C SPECIFICATION
long defpup(str [, args ... ] )
String str;
long args;
PARAMETERS
str expects a pointer to the text that you want to add as a menu item.
In addition, you have the option of pairing an ``item type'' flag
with each menu item. There are seven menu item type flags:
%t marks item text as the menu title string.
%F invokes a routine for every selection from this menu except
those marked with a %n. You must specify the invoked routine
in the arg parameter. The value of the menu item is used as
a parameter of the executed routine. Thus, if you select the
third menu item, the system passes 3 as a parameter to the
function specified by %F.
%f invokes a routine when this particular menu item is selected.
You must specify the invoked routine in the arg parameter.
The value of the menu item is passed as a parameter of the
routine. Thus, if you select the third menu item, the system
passes 3 as a parameter to the routine specified by %f. If
you have also used the %F flag within this menu, then the
result of the %f routine is passed as a parameter of the %F
routine.
%l adds a line under the current entry. This is useful in
providing visual clues to group like entries together.
%m pops up a menu whenever this menu item is selected. You must
provide the menu identifier of the new menu in the arg
parameter.
%n like %f, this flag invokes a routine when the user selects
this menu item. However, %n differs from %f in that it
ignores the routine (if any) specified by %F. The value of
the menu item is passed as a parameter of the executed
routine. Thus, if you select the third menu item, the system
passes 3 as a parameter to the function specified by %f.
%xn assigns a numeric value to this menu item. This values
overrides the default position-based value assigned to this
menu item (e.g., the third item is 3). You must enter the
numeric value as the n part of the text string. Do not use
the arg parameter to specify the numeric value.
Page 1
defpup(3G)defpup(3G)
args an optional set of arguments. Each argument expects the command
or submenu that you want to assign to this menu item. You can use
as many args parameters as you need.
FUNCTION RETURN VALUE
The returned value for the function is the menu identifier of the menu
just defined.
DESCRIPTIONdefpup defines a pop-up menu under the window manager and returns a
positive menu identifier as the function value.
EXAMPLES
Examples best illustrate the use of the item types.
menu = defpup("menu %t|item 1|item 2|item 3|item 4");
defines a pop-up menu with title menu and four items. You can use a menu
of this type as follows:
switch (dopup(menu)) {
case 1: /* item 1 */
handling code
break;
case 2: /* item 2 */
handling code
break;
case 3: /* item 3 */
handling code
break;
case 4: /* item 4 */
handling code
break;
}
A more complex example is:
String str = "menu2 %t %F|1 %n%l|2 %m|3 %f|4 %x234";
menu2 = defpup(str, menufunc, submenu, func);
defines a menu with title menu2 and four items with a line under the
first one. Invoked by:
menuval = dopup(menu2);
Page 2
defpup(3G)defpup(3G)
Selecting menu item 1 causes dopup to return menufunc(1). Rolling off
menu item 2 displays submenu, which provides additional selections. dopup
returns menufunc(dopup(submenu)) when another selection is made;
otherwise submenu disappears and selections are made from menu. Buttoning
item 3 executes func with 3 as its argument. dopup returns
menufunc(func(3)). Buttoning item 4 causes dopup to return
menufunc(234). If no item is selected, then dopup returns -1.
SEE ALSO
addtopup, dopup, freepup, newpup, setpup
NOTES
This routine is available only in immediate mode.
When using the Distributed Graphics Library (DGL), you can not call other
DGL routines within a function that is called by a popup menu, i.e. a
function given as the argument to a %f or %F item type.
Page 3
