NAME

Prima::Menu - pull-down and pop-up menu objects

SYNOPSIS

use Prima;
use Prima::Application;

my $window = Prima::Window-> new(
     menuItems => [
        [ '~File' => [
           [ '~Open', 'Ctrl+O', '^O', \&open_file ],
           [ '-save_file', '~Save', km::Ctrl | ord('s'), sub { save_file() } ],
           [],
           [ '~Exit', 'Alt+X', '@X', sub { exit } ],
        ]],
        [ '~Options' => [
           [ '*option1'  => 'Checkable option' => sub { $_[0]-> menu-> toggle( $_[1]) }],
           [ '*@option2' => 'Checkable option' => sub {}], # same
        ]],
        [],
        [ '~Help' => [
           [ 'Show help' => sub { $::application-> open_help("file://$0"); }],
        ]],
     ],
 );

 sub open_file
 {
     # enable 'save' menu item
     $window-> menu-> save_file-> enable;
 }

 $window-> popupItems( $window-> menuItems);

DESCRIPTION

The document describes the interfaces of Prima::AbstractMenu class, and its three descendants - Prima::Menu, Prima::Popup, and Prima::AccelTable. Prima::AbstractMenu is a descendant of the Prima::Component class, and its specialization is the handling of menu items, held in a tree-like structure. Descendants of Prima::AbstractMenu are designed to be attached to widgets and windows, to serve as hints for the system-dependent pop-up and pull-down menus.

USAGE

The central point of functionality in Prima::AbstractMenu-derived classes and their object instances ( further referred to as 'menu classes' and 'menu objects'), is the handling of a complex structure, contained in the ::items property. This property is special in that its structure is a tree-like array of scalars, each of which is either a description of a menu item or a reference to an array.

Parameters of an array must follow a special syntax, so the property input can be parsed and assigned correctly. In general, the syntax is

$menu-> items( [
   [ menu item description ],
   [ menu item description ],
   ...
]);

where the 'menu item description' is an array of scalars, that can hold from 0 up to 6 elements. Each menu item has six fields, that qualify a full description of a menu item. The shorter arrays are the shortcuts that imply some default or special cases. These base six fields are:

Menu item name

A string identifier. There are defined several shortcut properties in the Prima::MenuItem namespace that access the menu items and their data by the name. If the menu item name is not given or is empty, the name is assigned a string in the form '#ID' where the ID is a unique integer value within the menu object.

The IDs are set for each menu item, disregarding whether they have names or not. Any menu item can be uniquely identified by its ID value, by supplying the '#ID' string, in the same fashion as the named menu items. When creating or copying menu items, names in the format '#ID' are ignored and treated as if an empty string is passed. When copying menu items to another menu object, all menu items to be copied change their IDs, but the explicitly set names are preserved. Since the anonymous menu items do not have names their auto-generated names change also.

If the name is prepended by the special characters ( see below ), these characters are not treated as a part of the name but as an item modifier. This syntax is valid only for ::items and insert() functions, not for set_variable() method.

- - the item is disabled

* - the item is checked

@ - the item is using auto-toggling

? - the item is custom drawn

Expects the onMeasure and onPaint callbacks in options

( and ) - radio group

The items marked with parentheses are treated as a part of a group, where only a single item can be checked at any time. Checking and unchecking happen automatically.

A group is only valid on the same level where it was defined (i.e. submenus are not a part of the group). A group is automatically closed on the separator item. If that is not desired, mark it as ( too (consequent ('s are allowed):

[ '(one' ... ]
[ 'two' ... ]
[ '(' ],
[ ')last' ... ]

If the user hits an already checked item then nothing happens. However, when combined with auto-toggling (i.e. marked with (@), a checked item becomes unchecked, thus the group can present a state where no items are checked as well.

See also: group

Menu text / menu image

A non-separator menu item can be visualized either as a text string or an image. These options exclude each other and therefore occupy the same field. The menu text is an arbitrary string, with the ~ ( tilde ) character escaping a shortcut character, so that the system uses it as a hotkey during the menu navigation. The menu image is a Prima::Image object.

Note: the tilde-marked character is also recognized when navigating the custom drawn menu items, even though they not necessarily might draw the highlighted character.

The menu text in the menu item is accessible via the ::text property, and the menu image via the ::image property. Only one of these could be used, depending on whether the menu item contains text or image.

Accelerator text

An alternative text string that appears next to the menu item or the menu image, usually serving as a hotkey description. For example, if the hotkey is a combination of the 'enter' and the 'control' keys, then usually the accelerator text is the 'Ctrl+Enter' string.

The accelerator text in the menu item is accessible via the ::accel property.

Note: there is the Prima::KeySelector::describe function which converts an integer key value to a string in the human-readable format, perfectly usable as accelerator text.

Hotkey

An integer value, is a combination of either a kb::XXX constant or a character index with the modifier key values ( km::XXX constant ). This format is less informative than the three-integer key event format (CODE,KEY,MOD), described in Prima::Widget. However, these formats are easily converted to each other: CODE,KEY,MOD are translated to the INTEGER format by the translate_key() method. The reverse operation is not needed for the Prima::AbstractMenu functionality and is performed by the Prima::KeySelector::translate_codes method.

The integer value can be given in a more readable format when calling the ::items method. Character and F-keys (from F1 to F16) can be used as string literals, without the kb:: constant, and the modifier keys can be hinted as prefix characters: km::Shift as '#', km::Ctrl as '^', and km::Alt as '@'. This way the combination of the 'control' and 'G' keys can be expressed as the '^G' literal, and 'control'+'shift'+'F10' - as '^#F10'.

The hotkey in menu items is accessible via the ::key property. This property accepts the literal key format described above.

A literal key string can be converted to an integer value by the translate_shortcut method.

When the user presses the key combination that matches the hotkey entry in a menu item, its action is triggered.

Action

Every non-separator and non-submenu item performs an action that needs to be defined explicitly. The action can be set either as an anonymous sub or as a string with the name of the method on the owner of the menu object. Both ways have their niches, and both use three parameters when called - the owner of the menu object, the name of the menu item, that triggered the action, and the new checked status of the menu item

Prima::MainWindow-> new(
	menuItems => [
		['@item', 'Test',
             sub {
                 my (
                    $window,  # MainWindow
                    $item,    # 'item'
                    $checked  # MainWindow->men('item')->checked
                 ) = @_;
             }],
	]
);

The action scalar in the menu item is accessible via the ::action property.

A special built-in action can automatically toggle a menu item without the need to program that explicitly. The manual toggle of the menu item can be done by a code like this:

$window->menu->toggle($item)

However, Prima can toggle the item automatically too, if the @ character is added to the menu item name (see "Menu item name").

Options

At last, the non-separator menu items can hold an extra hash in the options property. The toolkit reserves the following keys for internal use:

group INTEGER: Same as the group property.
icon HANDLE: Is used to replace the default checkmark bitmap on a menu item
onMeasure MENUITEM, REF: Required when the custom painting is requested. It is called when the system needs to query the menu item dimensions. REF is a 2-item arrayref that needs to be set with the pixel dimensions of the item.
onPaint MENUITEM, CANVAS, SELECTED, X1, Y1, X2, Y2: Required when custom painting is requested. It is called whenever the system needs to draw the menu item. The X1 - Y2 are the coordinates of the rectangle where the drawing is allowed.

The syntax of the ::items method does not provide the 'disabled' and the 'checked' states for a menu item as separate fields. These states can be only set by using the - and the * prefix characters, as described above, in "Menu item name". They can though be assigned later on a per-item basis via the ::enabled and the ::checked properties when the menu object is created.

All these fields comprise the most common type of a menu item, that has a text, a shortcut key, and an action - a 'text item'. However, there are also two other types of menu items - a sub-menu and a separator. The type of the menu item cannot be changed on the fly except by changing the full menu tree by the functions ::items, remove(), and insert().

A sub-menu item can hold the same references as a text menu item does, except for the action field. Instead, the action field is used for a sub-menu reference scalar pointing to another set of menu item description arrays. From that point of view, the syntax of ::items can be more elaborated and shown in the following example:

$menu-> items( [
   [ text menu item description ],
   [ sub-menu item description [

      [ text menu item description ],
      [ sub-menu item description [
          [ text menu item description ],
          ...
      ]
      [ text menu item description ],
      ...
   ] ],
   ...
]);

The separator items don't have any fields, except the name. Their purpose is to hint a logical division of the menu items, usually as non-selectable horizontal lines.

In the menu bars, the first separator item met by the menu parser is treated differently. It serves as a hint that the following items must be shown in the right corner of the menu bar, contrary to the left-adjacent default layout. Subsequent separator items in a menu bar declaration can be either shown as a vertical division bar, or ignored.

All of these menu item types can be constructed by specifying menu description arrays. An item description array can hold between 0 to 6 scalars, and each combination is treated differently:

six - [ NAME, TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU, DATA ]

A six-scalar array is a fully qualified text-item description. All fields correspond to the described above scalars.

five [ NAME, TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU ]

Same as the six-scalar syntax, but without the DATA field. If DATA is skipped then it is set to undef.

four [ TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU ] or [ NAME, TEXT/IMAGE, ACTION/SUBMENU, DATA ]

One of the two definitions, depending on whether the last item is a hashref or not.

If the last item is not a hashref, then treated the same as the five-scalar syntax, but without the NAME field. When NAME is skipped it is assigned to a unique string within the menu object.

Otherwise same as the three-scalar syntax plus the DATA hashref.

three [ NAME, TEXT/IMAGE, ACTION/SUBMENU ] or [ TEXT/IMAGE, ACTION/SUBMENU, DATA ]

One of the two definitions, depending on whether the last item is a hashref or not.

If the last item is not a hashref, then treated the same as the five-scalar syntax, but without the ACCEL and the KEY fields. KEY is kb::NoKey by default, so no keyboard combination is bound to the item. The default ACCEL value is an empty string.

Otherwise the same as the two-scalar syntax plus DATA hashref.

two [ TEXT/IMAGE, ACTION/SUBMENU ] or [ NAME, DATA ]

One of the two definitions, depending on whether the last item is a hashref or not.

If the last item is not a hashref, then treated the same as the three-scalar syntax, but without the NAME field.

Otherwise treated as the menu items with the data reference. Useful for custom menu items that need at least the '?' flag in the NAME.

one and zero [ NAME ]

Both empty and 1-scalar arrays define a separator menu item. In the case of the 1-scalar syntax, the scalar value is the name of the separator item.

As an example of all the above, here's an example of a menu tree:

$img = Prima::Image-> create( ... );
...
$menu-> items( [
   [ "~File" => [
       [ "Anonymous" => "Ctrl+D" => '^d' => sub { print "sub\n";}],   # anonymous sub
       [ $img => sub {
          my $img = $_[0]-> menu-> image( $_[1]);
          my @r = @{$img-> palette};
          $img-> palette( [reverse @r]);
          $_[0]->menu->image( $_[1], $img);
       }],                         # image
       [],                         # division line
       [ "E~xit" => "Exit"    ]    # calling named function of menu owner
   ]],
   [ ef => "~Edit" => [                  # example of system commands usage
      ...
      [ "Pa~ste" => sub { $_[0]->foc_action('paste')} ],
      ...
      ["~Duplicate menu"=>sub{ TestWindow->create( menu=>$_[0]->menu)}],
   ]],
   ...
   [],                             # divisor in the main menu opens
   [ "~Clusters" => [              # right-adjacent part
     [ "*".checker =>  "Checking Item"   => "Check"     ],
     [],
     [ "-".slave   =>  "Disabled state"   => "PrintText"],
     ...
   ]]
] );

The code is from the examples/menu.pl in the toolkit installation. The reader is advised to run the example and learn the menu mechanics.

Prima::MenuItem

As briefly mentioned above, all menu items can be accessed using the following properties: ::accel, ::text, ::image, ::checked, ::enabled, ::action, ::data. These, plus some other methods can be also called in an alternative way, resembling name-based component calls of Prima::Object. For example, the call

$menu-> checked('CheckerMenuItem', 1);

can be also written as

$menu-> CheckerMenuItem-> checked(1);

Such name-based calls create temporary Prima::MenuItem objects that are only used to mimic the accessor functions from the Prima::AbstractMenu class and not much else.

The Prima::Menu objects complement the Prima::Window objects so that their menu items are shown as the menu bar on top of the window.

Prima::Menu's top-level items are laid out horizontally, and the top-level separator items behave differently ( see above, "Menu items" ).

If the ::selected property is set to 1, then a menu object is visualized in a window, otherwise it is not. This behavior allows a window to host multiple menu objects without interfering with each other. When a Prima::Menu object gets 'selected', it displaces the previous 'selected' menu, and its items are installed in the window menu bar. The Prima::Window property ::menu then points to that new menu object. Another Prima::Window property ::menuItems is an alias for the ::items property of the currently selected menu object. Prima::Window's properties ::menuFont and ::menuColorIndex are used as visualization hints, if/when the system supports that.

Prima::Menu provides no new methods or properties.

Objects derived from the Prima::Popup class are used together with the Prima::Widget objects in the same way as the menu objects with the window objects. Popup items are shown when the user presses the system-defined pop-up key or mouse button, as a response to the Prima::Widget's Popup notification.

If the ::selected property is set to 1, and the autoPopup property is also set to 1, then a popup object can appear fully automatically, without the need to program the popup-menu appearance and handling. This behavior allows a widget to host multiple popup objects without interfering with each other. When a Prima::Popup object gets 'selected', it displaces the previous 'selected' popup object. The Prima::Widget property ::popup then points to that object. Another widget property ::popupItems is an alias for the ::items property of the currently selected popup object. Prima::Widget's properties ::popupFont and Prima::Widgets's properties ::popupFont and ::popupColorIndex are used as visualization hints, if/when the system supports that.

A Prima::Popup object can be also visualized explicitly, by calling the popup method.

Prima::AccelTable

This class has a more limited functionality than Prima::Menu or Prima::Popup and is primarily used for mapping keystrokes to actions. Prima::AccelTable objects are never visualized, and consume no system resources, although the full menu item management syntax is supported.

If the ::selected property is set to 1, then an acceltable object displaces the previous 'selected' acceltable object. The Prima::Widget property ::accelTable then points to that object. Another widget property ::accelItems is an alias for the ::items property of the currently selected acceltable object.

Prima::AccelTable provides no new methods or properties.

API

Properties

accel NAME, STRING / Prima::MenuItem::accel STRING

Manages accelerator text for the menu item. NAME is the name of the menu item.

action NAME, SCALAR / Prima::MenuItem::action SCALAR.

Manages the action for the menu item. NAME is the name of the menu item. SCALAR can be either an anonymous sub or a method name, defined in the menu object owner's namespace. Both are called with three parameters - the owner of the menu object, the menu object itself, and the name of the menu item.

autoPopup BOOLEAN

Only in Prima::Popup

If set to 1 in the selected state, calls the popup() method in response to the Popup notification, when the user presses the system-defined hotkey or mouse button combination.

If 0, the pop-up menu can only be shown by a call to the popup method programmatically.

Default value: 1

autoToggle NAME, SCALAR / Prima::MenuItem::autoToggle SCALAR.

Manages the autoToggle flag for the menu item. When set, the checked option is flipped when the user selects the item. Also, in the unchecked state, the system displays an empty check box icon where normally a check icon would appear, to hint to the user that the menu item is toggle-able, despite it being unchecked.

checked NAME, BOOLEAN / Prima::MenuItem::checked BOOLEAN

Manages the 'checked' state of a menu item. If 'checked', a menu item is visualized with a distinct checkmark near the menu item text or image. Its usage with the sub-menu items is possible, although discouraged.

NAME is the name of the menu item.

data NAME, HASH / Prima::MenuItem::data HASH

Manages the user data hash. NAME is the name of the menu item.

enabled NAME, BOOLEAN / Prima::MenuItem::enabled BOOLEAN

Manages the 'enabled' state of the menu item. If 'enabled' is set, a menu item is visualized with a grayed or otherwise dimmed color palette. If a sub-menu item is disabled, the whole sub-menu is inaccessible.

Default: true

NAME is the name of the menu item.

group NAME, GROUP_ID / Prima::MenuItem::group GROUP_ID

If not 0, the menu item is treated as a member of a radio group with the GROUP_ID number. That means if one of the menu items that belong to the same group is checked, the other items are automatically unchecked.

image NAME, OBJECT / Prima::MenuItem::image OBJECT

Manages the image that is bound to the menu item. The OBJECT is a non-null Prima::Image object reference, with no particular color space or dimensions ( because of dimensions, its usage in top-level Prima::Menu items is discouraged ).

The ::image and the ::text properties are mutually exclusive, and can not be set together, but a menu item can change its representation between an image and a text during the runtime if these properties are called.

NAME is the name of the menu item.

items SCALAR

Manages the whole menu items tree. SCALAR is a multi-level anonymous array structure, with the syntax described in "Menu items".

The ::items property is an ultimate tool for reading and writing the menu items tree, but often it is too powerful, so there exist several easier-to-use properties ::accel, ::text, ::image, ::checked, ::enabled, ::action, ::data, that can access menu items individually.

key NAME, KEY / Prima::MenuItem::key KEY

Manages the hotkey combination, bound with the menu item. Internally the KEY is kept as an integer value, and a get-mode call always returns integers. The set-mode calls, however, accept the literal key format - strings such as '^C' or 'F5'.

NAME is the name of the menu item; KEY is an integer value.

selected BOOLEAN

If set to 1, the menu object is granted extra functionality from a window or widget owner object. Different Prima::AbstractMenu descendants are equipped with different extra functionalities. In the Usage section, see Prima::Menu, Prima::Popup, and Prima::AccelTable.

Within each menu-owner object hierarchy , only one menu object can be selected for its owner.

If set to 0, the only actions performed are implicit hotkey lookup when on the KeyDown event.

Default value: 1

submenu NAME, ARRAY / Prima::MenuItem::submenu ARRAY

Manages a submenu, if it is present. A get-call of the submenu property is equivalent to the get_items(NAME, 1) call. On a set-call removes all of the items under the NAME and inserts new ones.

Methods

check NAME / Prima::MenuItem::check

Alias for checked(1). Sets the menu item in the checked state.

disable NAME / Prima::MenuItem::disable

Alias for enabled(0). Sets the menu item in the disabled state.

enabled NAME / Prima::MenuItem::enabled

Alias for enabled(1). Sets the menu item in the enabled state.

execute NAME

Calls the action associated with the menu item

find_item_by_key KEY

Finds items by the associated hotkey combination

get_handle

Returns a system-dependent menu handle.

NB: Prima::AccelTable uses no system resources, and this method returns its object handle instead.

get_children NAME

Returns the list of children of the menu item with the name NAME

get_item NAME, FULL_TREE = 0

Returns the item entry corresponding to NAME, with or without the eventual full tree of children items, depending on the FULL_TREE flag.

get_items NAME, FULL_TREE = 1

Returns immediate children items entries that have NAME as a parent, with or without the eventual full tree of children items, depending on the FULL_TREE flag.

has_item NAME

Returns a boolean value, that is true if the menu object has a menu item with the name NAME.

insert ITEMS, ROOT_NAME, INDEX

Inserts menu items inside the existing item tree. ITEMS has the same syntax as the ::items property. ROOT_NAME is the name of the menu item, where the insertion must take place; if ROOT_NAME is an empty string, the insertion is performed to the top-level items. INDEX is an offset, that the newly inserted items would possess after the insertion. INDEX 0 indicates the very start of the menu.

Returns no value.

is_separator NAME

Returns true if the item is a separator, false otherwise

is_submenu NAME

Returns true if the item has a submenu, false otherwise

popup X_OFFSET, Y_OFFSET, [ LEFT = 0, BOTTOM = 0, RIGHT = 0, TOP = 0 ]

Only in Prima::Popup

Executes the system-driven pop-up menu, in the location near (X_OFFSET,Y_OFFSET) pixel on the screen, with the items from the ::items tree. The pop-up menu is hinted to be positioned so that the rectangle, defined by (LEFT,BOTTOM) - (RIGHT,TOP) coordinates is not covered by the first-level menu. This is useful when a pop-up menu is triggered by a button widget, for example.

If during the execution the user selects a menu item, then its associated action is executed ( see action ).

The method returns immediately and returns no value.

There is no functionality to cancel the running popup session.

remove NAME / Prima::MenuItem::remove

Deletes the menu item named NAME from the items tree, and its eventual sub-menus

select

Alias for selected(1). Sets the menu object in the selected state, and deselects all menu siblings of the same type (ie Menu->select(1) won't affect the selected status for a popup, for example).

set_variable NAME, NEW_NAME

Changes the name of the menu item from NAME to NEW_NAME. NEW_NAME must not be an empty string and must not be in the '#integer' form.

toggle NAME / Prima::MenuItem::toggle

Toggles the checked state of the menu item and returns the new state.

translate_accel TEXT

Locates a '~' ( tilde ) - escaped character in the TEXT string and returns its index ( as ord(lc())), or 0 if no escaped characters were found.

The method can be called with no object.

translate_key CODE, KEY, MOD

Translates the three-integer key representation into the one-integer format and returns the integer value. The three-integer format is used in the KeyDown and the KeyUp notifications for Prima::Widget.

See Prima::Widget

The method can be called with no object.

translate_shortcut KEY

Converts string literal KEY string into the integer format and returns the integer value.

The method can be called with no object.

uncheck NAME / Prima::MenuItem::uncheck

Alias for checked(0). Sets the menu item in the unchecked state.

Events

Change ACTION [, NAME [, VALUE ]]

Triggered when the structure of the menu tree is changed. ACTION is the method call that triggered that action, and NAME is the menu item name, when applicable. If NAME is an empty string, that means the affected menu item is the root of the item tree. VALUE is the new value, if applicable.

ItemMeasure ITEMID, REF

Called when the system needs to query the dimensions of a menu item that has the custom painting bit set. REF is a 2-item arrayref that needs to be set pixel-wise dimensions.

BUGS

Menu colors and fonts don't work on Windows and probably never will.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

USAGE

Menu items

Prima::MenuItem

Prima::Menu

Prima::Popup

Prima::AccelTable

API

Properties

Methods

Events

BUGS

AUTHOR

SEE ALSO

Module Install Instructions