popupMenu()

Activating a context-sensitive menu by means of right-clicking.

In the user interface you can activate a context menu also through left-click.

Synopsis

int popupMenu(dyn_mapping | dyn_string text, int &answer);

Parameters

Parameter Description
text Structure of the menu, can be either given as a dyn_mapping or a dyn_string. See the comprehensive description below.
answer Return variable

Return value

In the event of an error, the function returns -1 otherwise, 0.

Error

Wrong or missing parameters.

Details

A pop-up menu opens for a user to select from options. The selected option will be returned by the variable answer. The structure and contents of the menu are set with the text parameter, which can be given either as a dyn_mapping or a dyn_string.

dyn_mapping text parameter:

When using the a dyn_mapping text parameter, the overall mapping contains individual mappings for each menu item, which itself contain the menu item's properties. This division provides a clear definition of key/value properties. All menu item properties are optional, which means only relevant properties must be set. This also enables the use of icons within the popup menu.

Property Description
"type" defines the type of the menu item, the following values are possible:
  • "push" or "PUSH_BUTTON" - normal button (default)
  • "check" or "CHECK_BUTTON" - check button with optional checkmark
  • "cascade" or "CASCADE_BUTTON" - cascade button that opens a submenu
  • "separator" or "SEPARATOR" - separator line, this item ignores all other properties
"label" Label text for the item. The default is no label text.
"value" Integer value, which is returned when the item is clicked (This property is only used for push and check buttons). The default value is "-1".
"enabled" Boolean that defines whether the item is enabled or not. The default is "true".
"icon" Name of the icon to show for this item (this is ignored for check buttons, as it would hide the check mark). The default is no icon.
"checked" Boolean that defines whether the item is checked or not (this only applies to check buttons). The default is not checked
"submenu" Definitions for the submenu to be displayed (this only applies for cascade buttons). The default is no submenu. This submenu has the same structure as the top-level menu. For this we recommend creating a separate CTRL variable for the submenu and then using this variable as the value of this property (see the example below).

dyn_string text parameter:

Each line in the transferred string must begin with a keyword. The following keywords are allowed:

Keyword Description
PUSH_BUTTON

This keyword defines a menu item. The text to be displayed follows the word PUSH_BUTTON and is followed by the return value (int) that will be returned to the variable "answer" after this button has been clicked. The last value defines whether an entry is active or inactive. The value '1' indicates that an entry is active and can be clicked on. The value '0' results in this value being set to inactive and therefore cannot be clicked on.

Example: "PUSH_BUTTON, test field, 15, 1" would be an entry with the text "test field" that returns 15 as the return value and is active.
SEPARATOR The keyword SEPARATOR has no parameters and displays a horizontal separation line in a menu.
CHECK_BUTTON

The item "CHECK_BUTTON" can display a check box. The values for this item are given as follows:

<Object><Name><Return value><Enabled><Checked>

e.g.: "CHECK_BUTTON, check10, 10, 1, 1",

If you want to disable a check box, set the "Checked", meaning the fifth parameter, to 0.

Figure 1. Figure: check box
CASCADE_BUTTON

This field generates a branch at a lower menu level. CASCADE_BUTTON has two parameters: name and activity. Activity is the same as for PUSH_BUTTON. The specified name serves a double role: First it is used as the text for a branch. Second the name is immediately available as a keyword. All the menu items following this keyword are then found in the lower level.

The text for a menu with the structure :

Button 1

level 2 -> Button 2

Button 3

would therefore be "PUSH_BUTTON,Button 1,1,1",

"CASCADE_BUTTON,level 2,1",

"PUSH_BUTTON,Button 3,3,1",

"level 2",

"PUSH_BUTTON,Button 2,2,1"

Note:
After "level 2" it will no longer be possible to define a first-level element.

dyn_mapping text parameter example

This example sets a popup menu with a check box and a cascade button.

 // definition of the submenu
dyn_mapping level2 = makeDynMapping(
    makeMapping("label", "text 1", 
                "value", 4, 
                "enabled", false),
    makeMapping("type", "check", 
                "label", "check 12", 
                "value", 12, 
                "checked", true), 
    makeMapping("label", "text5",   
                "value", 5));

  // definition of the top-level menu
dyn_mapping menu = makeDynMapping(
    makeMapping("label", "text 1", 
                "value", 1, 
                "icon", "copy"),
    makeMapping("label", "text 2", 
                "value", 2,
                "icon", "ewo"),
    makeMapping("type", "check", 
                "label", "check 10", 
                "value", 10, 
                "checked", true),
    makeMapping("type", "separator"),
    makeMapping("type", "cascade", 
                "label", "Level 2", 
                "icon", "paste", 
                "submenu", level2),
    makeMapping("label", "text 3", 
                "value", 3));
int answer;
  
  //setting the popup menu
popupMenu(menu, answer);

dyn_string text parameter example

The following example script generates a two-level menu after a right-click. The entries text1, text2 and text3 are in the first level. The entry level2 will also be displayed. If this entry is clicked, the level below will be set to visible.

main()
{
  dyn_string txt;
  int answer;
  txt = makeDynString("PUSH_BUTTON, text1, 1, 1",
            "PUSH_BUTTON, text2, 2, 1",
            "SEPARATOR",
// separating line
            "CASCADE_BUTTON, Level 2, 1",
// branch
            "PUSH_BUTTON, text3, 3, 1",
            "Level 2",
// from here level 2
            "PUSH_BUTTON, text4, 4, 0",
            "PUSH_BUTTON, text5, 5, 1");

  popupMenu(txt, answer);
  DebugN(answer);
}

Assignment

Graphics

Availability

UI