NAME

defpup − defines a menu

SPECIFICATION

C
int defpup(str [, args ] ... )
char *str;
long args;

FORTRAN
available only in C

Pascal
available only in C

DESCRIPTION

defpup defines a pop-up menu in the window manager; 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
%n takes no arguments.
%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
    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

addtopup, dopup, freepup, newpup Using mex, Chapter 3, Making Pop-Up Menus

NOTE

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

Version 3.6  —  December 20, 1987