# 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>)][;]
        ...
    }

Description

Defines the popup menu <popup_name>. If the -m switch is NOT used the previous contents of the popups are cleared, otherwise are preserved.
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 follows exactly the same syntax as 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 'label' keywork 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: these are called "extended scope variables" and are described in the data structures documentation.
The syntax for these variables is:
%:<variable name>
These variables are visible during all the "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 (substantially from a popup call to the next one).
This allows you to pre-calculate data and conditions in the porologue of the popup and then use it in the item handlers or item conditions.

Switches

-m | --merge
Merges the new popup contents with an older popup version

Syntax Specification

    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>)][;]
        ...
    }

See also
popup

Index, Commands

KVIrc 4.0.2.4740 Documentation
Generated by root at Tue Feb 1 06:16:04 2011