Museum

     defpup(3G)                                             defpup(3G)



     NAME

          defpup - defines a menu


     SPECIFICATION

          C         int defpup(str [, args ] ... )

                    char *str;

                    long args;




          FORTRAN   Note: available only in C


     DESCRIPTION

          defpup defines a pop-up menu; it returns a positive menu

          identifier.  str is a string that describes each menu item.

          Menu items include title, submenu, or selectable item. title

          is the string displayed at the top of the menu.  submenu is

          an item that invokes a submenu with further choices if

          rolled off to either side.  A selectable item, selected with

          the right mouse button, can be a numeric value, function, or

          an implied numeric value associated with it.


          The optional arguments [, args] provide submenu identifiers

          returned by defpup and newpup, and/or handling function

          addresses dictated by str. str is made up of label/type

          pairs separated by vertical bars. Each label/type pair

          includes a menu label and an optional typing character that

          is preceded by a percent sign (%). The item types are:


          %t    title string.

          %F    menu function invoked by any item selection.

          %f    item function invoked by selecting the associated item

                with the mouse button.

          %m    submenu brought up by rolling off the associated item

          %x#   numeric item selected by selecting the associated item

                with the mouse button.


          An example best illustrates the use of the item types.


          menu=defpup("foo %t |item 1|item 2 |item 3 |item 4");


          defines a pop-up menu with title foo 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



     Page 1                                          (printed 8/20/87)

     defpup(3G)                                             defpup(3G)



                   break;
                  case 4 : /* item 4 */
                    handling code
                   break;
              }

          A more complex example is:

          menu=defpup("
             foobar %t %F|item 1%n|item 2%m|item 3%f|item 4%x234",
                menufunc, submenu, func);

          defines a menu with title foobar and four items.  Invoked
          by:

          menuval = dopup(menu);

          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.

          pupmode or full-screen mode executes any function that is
          invoked from a pop-up menu.  If a menu handling function
          uses the pop-up planes and/or regions of the screen beyond
          the process's graphics window, it must make calls to pupmode
          and/or fullscrn .

     SEE ALSO
          newpup, addtopup, dopup, freepup

          Using mex, Chapter 4, Pop-Up Menus

     NOTE
          This routine is available only in immediate mode. FORTRAN
          does not support this routine; use newpup and addtopup .









     Page 2                                          (printed 8/20/87)