addtopup(3G)

NAME
     addtopup - adds items to an existing pop-up menu

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

PARAMETERS
     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
                   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
     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
     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
     defpup, 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.