defpopup

Defines a popup menu

Usage

defpopup [-m] (<popup_name>)
{
    prologue[(<id>)] <prologue_command>
    epilogue[(<id>)] <epilogue_command>
    label(<text>[,<id>])[(<expression>)][;]
    item(<text>[,<icon>[,<id>]])[(<expression>)]<command>
    popup(<text>[,<icon>[,<id>]])[(<expression>)]
    {
        <popup body>
    }
    extpopup(<text>,<name>[,<icon>[,<id>]])[(<expression>)][;]
    separator[(<expression>)][;]
    separatorid[(<id>)][(<expression>)][;]
    ...
}

Description

Defines the popup menu <popup_name>. If the -m switch is not used the previous contents of the popups are cleared before updating.
The popup is generated 'on the fly' when the popup command is called.
The item keyword adds a menu item with visible <text>, the optional <icon> and <command> as code to be executed when the item is clicked. <text> is a string that is evaluated at popup call time and may contain identifiers and variables. If <expression> is given, it is evaluated at popup call time and if the result is 0, the item is not shown in the physical popup.
The popup keyword adds a submenu with visible <text>, the optional <icon> and a popup body that has identical syntax to the defpopup body. The <expression> has the same meaning as with the item keyword.
The 'extpopup' keyword adds a submenu with visible <text>, the optional icon and a popup body that is defined by the popup menu <name>. This basically allows to nest popup menus and define their parts separately. <icon> and <expression> have the same meaning as with the item keyword.
The separator keyword adds a straight line between items (separator).
The 'separatorid' keyword adds a straight line between items, but permits to specify a separator id.
The label keyword adds a descriptive label that acts like a separator.
The prologue keyword adds a <prologue_command> to be executed just before the popup is filled at popup command call.
The epilogue keyword adds an <epilogue_command> to be executed just after the popup has been filled at popup command call.
There can be multiple prologue and epilogue commands: their execution order is undefined.
<icon> is always an image identifier.
<id> is an unique identifier that can be used to remove single items by the means of delpopupitem. If <id> is omitted then it is automatically generated. Please note that using this command inside the prologue, epilogue or item code of the modified popup menu is forbidden. In other words: self modification of popup menus is not allowed.
To remove a popup menu use this command with an empty body:

defpopup(test){}

This will remove the popup test and free its memory. Popups have a special kind of local variables that have an extended lifetime, called extended scope - this is described in the Data structures documentation.
The syntax for an "extended scope" variable is:
%:<variable name>
This type of variable is maintained during the entire visible lifetime of the popup - from the popup command call to the moment in that the user selects an item and the corresponding code is executed (essentially from a popup call to the next one).
This allows you to pre-calculate data and conditions in the prologue of the popup and then use it in the item handlers or item conditions.

Switches

-m | --merge

Merges the new popup contents with the current named popup. If the named popup does not exist, the popup is created.