Directives 

Format

POPUP_MENU [@(col,ln)], list$, [strvar$|numvar]

Where:

Description

Use the POPUP_MENU directive to create and process floating menus. A popup menu "pops up" on top of the current window when you right click the mouse while the pointer is over a control, such as a button, multi-line or list box. Once a popup menu is created and assigned to a control, it remains invisible until the user right clicks the mouse button over the enabled component. In a popup menu, a default option may be specified.

Popup Menu Definition

The POPUP_MENU definition uses a format similar to the MENU_BAR directive:

• Each menu group is enclosed by square brackets.
• Each item in a group is separated by a comma.
• Each item's selection character (hot key) is preceded by an & (ampersand).
• Each sub-menu group is prefixed with its item ID.

Numeric values are assigned to each entry in the menu definition. By default, the first entry has the value '1', the second '2', etc. This value can be overridden by placing an = (equals sign) and numeric value after the menu item text.

Example:

"F:[&Open,&Save,&Quit=4]"

In this example, Quit would have a value of 4. In addition, the starting numeric value can be changed or reset by placing a # (pound sign), followed by the new starting point, within the menu definition string outside of group definitions. When setting a new starting value, the next menu selection will be assigned a number that is one more than the starting point:

"[&File,&Quit],#1000,F:[&Open,&Save,&Rename]"

This example defines File as 1, Quit as 2, File-Open as 1001, File-Save as 1002, and File-Rename as 1003.

Accelerator keys should be unique for each selection on a given sub-menu within a group. While the use of duplicate accelerator keys is permitted, it is difficult to determine which selection was made by using just the character strings.

Menu items can be disabled, displayed in bold or with a checkmark by placing a "D", "B" or "C" after the = (equals sign) and before the value to return.

Example:

m$="[&One=1,&Two=C2,&Three=D3,&Four=BC4]"
popup_menu m$,answer$

In this example, the resulting menu shows "Two" checked, "Three" disabled, and "Four" both bolded and checked.

Popup Menu Assignment 

A POPUP_MENU can be associated with buttons, check boxes, drop boxes, grids, list boxes, multi-lines, radio buttons and tristate boxes. The directives that control these objects include a MNU= option that defines the CTL number that will be generated when the user right clicks on the control.

Bitmaps and Icons 

Images can be included for each item in the menu. Enclose the image name in curly braces and place it in the menu definition just prior to the specific item text.

Example:

"-[&File],F:[&Open=1001,{!Stop}&Stop=1002]"

Use a leading ! (exclamation point) to identify the image as internal, or specify the relative path and filename to access an image file that is external. For information on internal/external images and recognized image file types, see Displaying Bitmaps/Icons.

System Menu

The POPUP_MENU directive also supports the ability to invoke the system menu programmatically:

POPUP_MENU "*",status

Where:

(System menu support was added in PxPlus 2017.)

Inclusion of Special Characters

If the text you want to include has any of the characters used to define the popup menu, which is {, }, [, ], = (equals sign), & (ampersand), : (colon) or , (comma), you will need to escape these characters with the backslash and put a backslash as the first character of the menu definition string.

Example:

If you want an entry in the menu bar to read "Export [to Word]", your menu_bar command would look like this:

popup_menu @(col,row),"\[&File],F:[&Open=1,,&Save,&Export \[to Word\]=2,&Quit=4]",X

The first character of the menu definition string being a backslash indicates to the system that the menu contains escaped characters. Any subsequent character in the string preceded by a backslash will not be considered as a delimiter/control character and included in the actual popup_menu text.

(Support to allow the inclusion of the special characters used to define the menu was added in PxPlus 2021.)

Two-Tone Effects

The POPUP_MENU directive supports the use of two optional parameters for defining background and left edge colours in menus (similar to MS Office applications):

Example:

In the following example, the RGB colour 200,200,200 is used for the left edge of all entries in this menu:

popup_menu "LEFT(RGB:200,200,200),[&File,&Edit,&Help],F:[...."

In the next example, the RGB colour 255,255,150 is used as the background colour for all of the text portion of the menu:

popup_menu 10,"FILL(RGB:255,255,150),[&File,&Edit,&Help],F:[...."

Note:
The system supplied Cut, Copy, Paste and Delete menu items will adhere to the FILL(arg) and LEFT(arg) definitions for the menu.

See Also

MENU_BAR Create/Control Menu Bar
BUTTON Create/Control Button
CHECK_BOX Create/Control Check Box
DROP_BOX Create/Control Drop Box
GRID Create/Control Grid
LIST_BOX Create/Control List Box
MULTI_LINE Create/Control Multi-Line Input
RADIO_BUTTON Create/Control Radio Button
TRISTATE_BOX Create/Control Tristate Box

Example

This popup menu returns a numeric value assigned by the menu bar definition:

0020 print 'CS',; list 0030,
0030 check_box 100,@(50,10,10,2)="{}Popup Menu",opt="P",mnu=101
0040 obtain *
0050 if ctl=4 then stop
0060 if ctl<>101 then goto 0040
0070 mdef$="[&File,&Edit,E&xit=4],F:[&Open=10,&Save=D20], E:[C&ut=30,&Copy=40,&Paste=50]"
0080 popup_menu @(58,12),mdef$,x
0090 print "Selected: ",x
0100 if x=4 then stop
0110 goto 0040