addtopup(3G)							  addtopup(3G)

NAME    [Toc]    [Back]

     addtopup -	adds items to an existing pop-up menu

C SPECIFICATION    [Toc]    [Back]

     void addtopup(long	pup, String str	[, arg]	... )

PARAMETERS    [Toc]    [Back]

     pup      expects the menu identifier of the menu to which you want	to
	      add. The menu identifier is the returned function	value of the
	      menu creation call to either newpup or defpup functions.

     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.	 You can use this as a
		   visual cue 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



									Page 1






addtopup(3G)							  addtopup(3G)



		   the arg parameter to	specify	the numeric value.

	      NOTE: If you use the vertical bar	delimiter, "|",	you can
	      specify multiple menu items in a text string.  However, because
	      there is only one	arg parameter, the text	string can contain no
	      more than	one item type that references the arg parameter.

     arg      expects the command or submenu that you want to assign to	the
	      menu item.  You can have only one	arg parameter for each call to
	      addtopup.

DESCRIPTION    [Toc]    [Back]

     addtopup adds items to the	bottom of an existing pop-up menu.  You	can
     build a menu by using a call to newpup to create a	menu, followed by a
     call to addtopup for each menu item that you want to add to the menu. To
     activate and display the menu, submit the menu to dopup.

EXAMPLE    [Toc]    [Back]

     This example creates a menu with a	submenu:

	  submenu = newpup();
	  addtopup(submenu, "rotate %f", dorota);
	  addtopup(submenu, "translate %f", dotran);
	  addtopup(submenu, "scale %f",	doscal);
	  menu = newpup();
	  addtopup(menu, "sample %t", 0);
	  addtopup(menu, "persp", 0);
	  addtopup(menu, "xform	%m", submenu);
	  addtopup(menu, "greset %f", greset);


     Because neither the "sample" menu title nor the "persp" menu item refer
     to	the arg	parameter, you can group "sample", "persp", and	"xform"	in a
     single call:

	  addtopup(menu, "sample %t | persp | xform %m", submenu);

SEE ALSO    [Toc]    [Back]

     defpup, 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 2222