defpup(3G)							    defpup(3G)

NAME    [Toc]    [Back]

     defpup - defines a	menu

C SPECIFICATION    [Toc]    [Back]

     long defpup(str [,	args ... ] )
     String str;
     long args;

PARAMETERS    [Toc]    [Back]

     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.

DESCRIPTION    [Toc]    [Back]

     defpup defines a pop-up menu under	the window manager and returns a
     positive menu identifier as the function value.

EXAMPLES    [Toc]    [Back]

     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    [Toc]    [Back]

     addtopup, dopup, freepup, newpup, setpup

NOTES    [Toc]    [Back]

     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.


									PPPPaaaaggggeeee 3333