Programmer Guide/Macro Library/CMenu

CMenu : CObj

The CMenu class simplifies the construction, manipulation and use of context menus.

CMenu Construction

Construct a CMenu instance.

#cmenu := cmenu [ firstIndex ]

CMenu Member Functions

The CMenu class has the following member functions. See CObj Member Functions for a list of functions implemented in the parent class.

AddItem

Add an item to the menu. These include e.g. spacers, sub-items, toggle items.

Usage:

inst AddItem [ index ] ; key=value [ ; key=value ... ]

Parameters:

index

An optional index. If no index is specified, the menu item is appended to the menu. If the index exists, the item is replaced.

key=value

A key/value pair in the form of 'key=value'. The following keys are supported:

id - The unique string used to identify this menu item. If the string is not unique, the existing entry with this id is overwritten.

menu - The value associated with the key 'menu' will be used for the menu item text.

cmd - The value associated with the key 'cmd' should be used to store the command to be called when an item is selected by the user.

args - The value associated with the key 'args' should be used to store any command arguments that should be passed to 'cmd'.

hotkey - The value associated with the key 'hotkey' is parsed and the resulting string is appended to the item 'menu' value. For example, the string 'Cc' is converted into the hotkey 'Ctrl+C', whilst 'CA' is converted to the hotkey 'Ctrl+Shift+A'. Note that the asterisk character * is not allowed as a hotkey.

dynamicVariable - The variable from which to read the 'X' string to use for dynamic menus. E.g. if the variable contains either 0 or 1, then the dynamic menus 'menu0' and 'menu1' can be defined using AddItem() and the menu item will be set accordingly when GetTable() is called. The dynamic variable must be a shell or global variable.

menuX - The dynamic menu item (used depending on the value of dynamicVariable).

spacer - This key has no value and inserts a spacer into the menu.

startsub - The value associated with the key 'startsub' is the text of a menu item (e.g. like 'menu'), but is used for the parent menu item of a sub-menu.

endsub - This key has no associated value and ends the last submenu.

checked - Set to 1 if the item should be checked.

disabled - Set to 1 if the item should be disabled.

Result:

An empty string.

AddPopup

Set the context menu for the specified graph. If the Check(), Uncheck(), Enable() and Disable() functions have been used, then the state of the items is also set.

Usage:

inst AddPopup graph

Parameters:

graph

The id of the graph item.

Result:

An empty string on success.

An error code on failure.

AddToolBoxMenu

Add the standard toolbox menu items to the menu.

Usage:

inst AddToolBoxMenu context ; CMD ; cmd ; args

inst AddToolBoxMenu context ; ID ; id

Parameters:

context

The toolbox function context.

id

The string used for the item id.

cmd

The string used for the item command (CMD=command).

args

The string used for the item arguments (ARGS=args [toolboxfunction])

Result:

The number of toolbox functions added.

Notes:

If the 2nd argument is set to CMD, a command-item is added (CMD=cmd; ARGS=args [tool]). Otherwise the 2nd argument must be set to ID and an id item is added (ID=id [tool]).

Check

Set the state of the item to checked. Note that this is only reflected in the context menu if the function AddPopup() is used.

Usage:

inst Check index|key=value

Parameters:

index

The index of the item to return (as returned by the CMITEM message).

key=value

A key/value pair. The key must be one of the keys supported by AddItem(). The value should be a value previously passed to AddItem().

Result:

An empty string on success and an error code on failure.

Cmd

Executes the command in the 'cmd' field of entry specified by index or by a key/value pair. The arguments stored in the 'args' field are passed to the command

Usage:

inst Cmd index|key=value

Parameters:

index

The index as received from the CMSTAT message.

key=value

A key/value pair specified using CMenu::AddItem().

Result:

-1 if there is no command associated with this id, otherwise the result of the specified command.

Disable

Set the state of the item to disabled. Note that this is only reflected in the context menu if the function AddPopup() is used.

Usage:

inst Disable index|key=value

Parameters:

index

The index of the item to return (as returned by the CMITEM message).

key=value

A key/value pair. The key must be one of the keys supported by AddItem(). The value should be a value previously passed to AddItem().

Result:

An empty string on success and an error code on failure.

Enable

Set the state of the item to enabled. Note that this is only reflected in the context menu if the function AddPopup() is used.

Usage:

inst Enable index|key=value

Parameters:

index

The index of the item to return (as returned by the CMITEM message).

key=value

A key/value pair. The key must be one of the keys supported by AddItem(). The value should be a value previously passed to AddItem().

Result:

An empty string on success and an error code on failure.

GetIndex

Retrieve the index of an item identified by one of it's key/value pairs. Note that this can not be used to retrieve the index of spacers or startsub or endsub entries. This function can be useful in a message loop, if you want to query whether an index falls within a specific range. E.g.:

if '$#par' >= '$($#menu GetIndex id=rangeStart)' && '$#par' <= '$($#menu GetIndex id=rangeEnd)' then
// do something here ...
end

Usage:

inst GetIndex key=value [ ; iStart ]

Parameters:

key=value

key - the key (one of the keys supported by AddItem).

value - the value previously passed to AddItem.

iStart

The index to start searching from. The default is 0.

Result:

The index of the item with the key/value pair, or -1 if no such key/value pair exists.

Notes:

If there are multiple key/value pairs, the parameter iStart should be used.

GetItem

Get one or more of the field values for a particular entry. E.g. retrieve the command and arguments associated with a particular item index.

Usage:

inst GetItem index|key=value [ ; keyList ]

Parameters:

index

The index of the item to return (as returned by the CMITEM message).

key=value

A key/value pair. The key must be one of the keys supported by AddItem(). The value should be a value previously passed to AddItem().

keyList

A semi-colon separated list of keys for which to return values. If no keyList is specified, the whole entry is returned.

Result:

Either a semi-colon separated list of values associated with the requested keys, the whole item entry or an empty string if the index parameter is invalid.

GetTable

Returns the table to be used as an AddPopup parameter.

Usage:

inst GetTable

Result:

The menu table item name.

Msg

Execute the command associated with an item index or hotkey.

Usage:

inst Msg id par

Parameters:

id

One of the following keywords:

cmitem | key

par

Either a hotkey string (e.g. 'Cc') if id is 'key', or a command id if id is 'cmitem'.

Result:

1 if a command was executed.

0 if no command is associated with this index or hotkey.

SetPopup

Disable, enable, check or uncheck a context menu entry (currently only in a graphs).

Usage:

inst SetPopup index|key=value ; option ; graph

Parameters:

index

The index as received from the CMSTAT message.

key=value

A key/value pair specified using CMenu::AddItem().

option

One of the following keywords:

disable | enable | check | uncheck

graph

The id of a graph item.

Result:

0 on success

-1 on failure

Uncheck

Set the state of the item to unchecked. Note that this is only reflected in the context menu if the function AddPopup() is used.

Usage:

inst Uncheck index|key=value

Parameters:

index

The index of the item to return (as returned by the CMITEM message).

key=value

A key/value pair. The key must be one of the keys supported by AddItem(). The value should be a value previously passed to AddItem().

Result:

An empty string on success and an error code on failure.

CMenu Examples

//{{3.8 3205}{2006.10.18  13.22.25} - automatically created version information - do not change or delete this line}
/*++
Macro:  cmenu_example
Descriptions:
    An example of the use of the CMenu class to create and display
    a context menu in a dialog and react to user input 
    (command selection and hotkeys).
Parameters:
    None
Author:
    Jonnie White
History:
    2006-10-18  First implemented
--*/
[macro cmenu_example]
    // create a dialog
    #dmap := cdlgmap * dialog * 'CMenu Test Dialog'
    if '$#dmap[?]' != 'instance' em -1 ; $#mac::Error - Failed to create CDlgMap instance
    // create controls
    $($#dmap setci ok) button 0 0 '&OK' * 8
    $($#dmap setci cancel) button 1 0 '&Cancel' * 8
    // create cmenu
    #cmenu := cmenu
    if '$#cmenu[?]' != 'instance' em -1 ; $#mac::Error - Failed to create CMenu instance
    // add menu items
    $#cmenu additem ; menu=item1 ; hotkey=C1 ; cmd=cmd1 ; args=args1 ; id=command1
    $#cmenu additem ; menu=item2 ; hotkey=C2 ; cmd=cmd2 ; args=args2 ; id=command2
    $#cmenu additem ; menu=item3 ; hotkey=C3 ; cmd=cmd3 ; args=args3 ; id=command3
        
    // add menu to dialog
    $($#dmap dlg) AddPopup /X 0 $($#cmenu GetTable) /Table
    if '$rc' > 0 em $rc ; $#mac::Error - Failed to add popup context menu to dialog
    // display dialog and react to user input
    $#dmap begin
    do forever
        $($#dmap dlg) /Write
        readstr '$($#dmap loop ok cancel)' #msgId #par
        $($#dmap dlg) /Read
        if '$#msgId' == 'command' then
            // close dialog
            if '$#par' == 'ok' || '$#par' == 'cancel' break
        else if '$#msgId' == 'cmstat' then
            // show context menu
            $($#dmap Dlg) contextmenu 0
        else if '$#msgId' == 'cmitem' then
            // user selected item, so execute command
            gosubx $($#cmenu GetItem $#par ; cmd) $($#cmenu GetItem $#par ; args)
        else if '$#msgId' == 'key' then
            // user pressed hotkey, so execute command
            readstr '$#par' #code #key
            gosubx $($#cmenu GetItem hotkey=$#key ; cmd) $($#cmenu GetItem hotkey=$#key ; args)
        end
    end
    // destroy dialog and map
    $#dmap end
    $#cmenu destroy
    delete $#t
exit

cmd1:
    um command 1 called with these arguments: $#argv
exit

cmd2:
        #checked := $#cmenu ischecked id=command2
        $#cmenu $(word $#checked check uncheck) $($#cmenu getindex id=command2)
        // re-add menu, to reflect checked/unchecked/enabled/disabled status
        $#cmenu AddPopup $($#dmap dlg)
exit

cmd3:
        #checked := $#cmenu ischecked id=command3
        $#cmenu $(word $#checked check uncheck) $($#cmenu getindex id=command3)
        // re-add menu, to reflect checked/unchecked/enabled/disabled status
        $#cmenu AddPopup $($#dmap dlg)
exit