This section discusses the following topics:
| addtopup | |
| Adds an item to an existing pop-up menu. | |
| defpup | |
| Defines a pop-up menu. | |
| dopup | |
| Displays a pop-up menu. | |
| freepup | |
| Frees (deallocates) a pop-up menu and its data structures. | |
| newpup | |
| Allocates and initializes the structure for a new pop-up menu. | |
| setpup | |
| Enables or disables a given pop-up entry. | |
Note: Using popup menu facilities when the X server has been initialized in layer 1 (the overlay bitplane) is ugly. The GL popup menus use the fullscrn subroutine.
GL contains subroutines that you can include in your graphics programs to create and use pop-up menus. When you select an item from a menu, these subroutines automatically identify which menu item has been selected.
To create a pop-up menu in C programming language, use the defpup subroutine. To create a pop-up menu in FORTRAN, use the newpup and addtopup subroutine.
You can also design your own pop-up menu interface using the overlay bitplanes.
To set pop-up menu colors, use the mapcolor and mapcolors subroutines. To facilitate color selection, the following tokens are defined in the /usr/include/gl/gl.h file:
The defpup subroutine defines a pop-up menu by allocating structure and making menu entries. In C programming language, you can combine the functions of the newpup and addtopup subroutines by calling the defpup subroutine, available only in C programming language. FORTRAN does not support variable parameter lists. The syntax is as follows:
Int32 defpup(Char8 *String [, Int32 arguments ...])
The defpup subroutine creates the menu in one step. You can add menu entries with the addtopup subroutine.
The PUPDRAW option of the drawmode subroutine allows you to define the colors for pop-up menus with the mapcolor subroutine. Be aware that you cannot draw while using the PUPDRAW option of the drawmode subroutine.
If you program in FORTRAN, you must use the newpup and addtopup subroutines to create the menu.
The newpup subroutine allocates and initializes a structure for a new menu. This subroutine takes no arguments and returns a 32-bit integer identifier (the popup parameter) for the pop-up menu. The syntax is as follows:
Int32 newpup()
After the newpup subroutine creates an empty menu, use the addtopup subroutine to build the menu by adding entries to the bottom of the empty menu structure. The syntax is as follows:
void addtopup(Int32 popup, Char8 *String, Int32 argument)
The popup parameter is the menu identifier returned by the newpup subroutine or the defpup subroutine. The String parameter is a character string that specifies the entries in the menu. The string lists the menu labels from the top to the bottom of the menu, with a | (vertical bar delimiter) between entries.
The FORTRAN version, the addtopup subroutine, takes an additional Length parameter, which specifies the number of characters in the string. The Argument parameter is necessary only for advanced menu formats.
Following are two examples of adding to a menu:
menu = newpup(); addtopup (menu, "first|second|third");
IMENU = NEWPUP(); CALL ADDTOP (IMENU, "first|second|third", 18);
The number 18 in the FORTRAN subroutine is the number of characters in the string, including the vertical bar delimiters.
The following subroutines allow you to invoke your choice of pop-up menus and free the memory occupied by the menu when no longer needed.
Note: Do not call the exit routine directly from a pop-up menu. This could cause the pop-up menu to be erased from the overlays. To prevent this, either return from the dopup subroutine or clear the overlays before you call the exit routine.
The dopup subroutine displays a pop-up menu previously defined with the defpup subroutine. The popup parameter is the identifier of the pop-up menu. The system displays the menu until you either make a selection or release the button with the cursor off the menu. The value that the dopup subroutine returns depends on the menu selection. If no selection is made, the dopup subroutine returns -1 (negative one). If the pop-up menu does not use an advanced menu format, the dopup subroutine returns an integer corresponding to the position of the item in the menu. The syntax is as follows:
Int32 dopup(Int32 popup)
To cause the right mouse button to bring up the menu built in the previous example, use the following code:
dev = qread(&val);
if (dev == RIGHTMOUSE) {
if (val == 1) { /* right mouse button is pressed */
menuval = dopup (menu);
}
}
IDEV = QREAD(IVAL) IF (IDEV .EQ. RIGHTM) THEN IF (IVAL .EQ. 1) THEN MENVAL = DOPUP (IMENU); ENDIF ENDIF
Select the first , second , or third item in the menu by positioning the cursor over one of these items, then releasing the button. To make no selection, release the button with the cursor off the menu. The following table shows the return value for each possible selection in the example:
| Default Return Values | |
| Selection | Return Value |
| First | 1 |
| Second | 2 |
| Third | 3 |
| No selection | -1 |
The freepup subroutine deletes a pop-up menu, freeing the memory reserved for its data structures. The syntax is as follows:
void freepup(Int32 popup)
The setpup subroutine enables or disables a given pop-up menu entry. If used properly, this subroutine renders submenus associated with a disabled entry inaccessible. The syntax is as follows:
void setpup(Int32 pup, Int 32 entry, Int32 mode)
You can use advanced menu format to:
You introduce the special format when you call the defpup or addtopup subroutine. Following the string that defines the menu entry, add these format instructions:
More than one special format can be associated with a menu entry. Use a | (vertical bar) to separate entries.
| Summary of Advanced Menu Formats | ||||
| Task | Format | Changes Return Value? | Needs Numeric Value? | Needs Parameters? |
| Return default values | %n | No | No | No |
| Return other values | %x | Yes | Yes | No |
| Make title | %t | No | No | No |
| Bind function/ whole menu | %F | Yes | Possibly | Yes |
| Bind function/ menu item | %f | Yes | Possibly | Yes |
| Make nested menu | %m | Yes | No | Yes |
The %n format can be used to return a menu entry to its default settings. The %n format takes no parameters. The following menu:
menu = newpup(); addtopup(menu, "first|second|third");
menu = newpup(); addtopup(menu, "first %n|second %n|third %n");
The %x format changes the numeric value that the dopup subroutine returns. Note the following menu:
menu = newpup(); addtopup(menu, "first %x15|second %x7");
Selecting first causes the dopup subroutine to return 15, not -1 (the default). Selecting second causes the dopup subroutine to return 7, not 2 (the default). For this format, you must specify a numeric value that the dopup subroutine returns in place of the default.
The %t format creates a title bar on a pop-up menu. You cannot select the title bar. It does not highlight.
The following menu is the same as the first example, except that there is a title bar at the top of the menu. The %t format takes no parameters.
menu = newpup(); addtopup(menu, "Cardinal %t|first|second|third");
The %F format specifies a function that affects all values returned by any item in the menu. This format requires a parameter to specify the function or subroutine that affects all values that the dopup subroutine returns.
menu = newpup(); addtopup(menu, "Cardinal %t %F|first|second %x10", funct);
When the user selects first from the pop-up menu, the dopup subroutine returns funct(1) instead of 1. When the user selects second , the dopup subroutine returns funct(10) .
The %f format makes a menu entry that calls a function or subroutine. The name of the function is the parameter to this format:
menu = newpup(); addtopup(menu, "first|call %f", func);
When the user selects call from the pop-up menu, the funct function is called with a parameter of 2 (the default return value for this selection). The dopup(menu) returns funct(2) .
Call the addtopup subroutine each time you want to add another menu entry that has its own function.
You can also use the defpup subroutine to define a pop-up with one or more menu entries that bind to a function.
The %m format creates a simple nested pop-up menu (a submenu). When you roll the cursor to the right side of the menu item, you invoke the submenu. Labels on the submenu can have further choices. This format requires a parameter to specify the menu identifier for the pop-up submenu.
Note: You must declare any submenus before the main menu in your program.
submenu = newpup(); addtopup(submenu, "one|two"); menu = newpup(); addtopup(menu, "Cardinal %t|above %x5|below %m", submenu);
If you select an item from the submenu, the dopup(menu) returns the same value as the dopup(submenu) . If you display the submenu without making a selection, the dopup subroutine returns negative 1.