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]) }],
]],
[],
[ '~Help' => [
[ 'Show help' => sub { $::application-> open_help($0); }],
]],
],
);
sub open_file
{
# enable 'save' menu item
$window-> menu-> save_file-> enable;
}
$window-> popupItems( $window-> menuItems);
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 '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 shortcuts, that imply default or special cases. These base six fields are:
IDs are set for each menu item, disregarding whether they have names or not. Any menu item can be uniquely identifed by its ID value, by supplying the '#ID' string, in the same fashion as named menu items. When creating or copying menu items, names in format '#ID' are not accepted, 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 explicitly set names are preserved. Since the anonymous menu items do not have name, their auto-generated names change also.
If the name is prepended by '-' or '*' characters, or both, these are not treated as part of the name but as indicator that the item is disabled ( '-' character ) or checked ( '*' character ). This syntax is valid only for "::items" and "insert()" functions, not for "set_variable()" method.
Menu text in menu item is accessible via the "::text" property, and menu image via the "::image" property. These can not accept or return sensible arguments simultaneously.
Accelerator text in menu item is accessible via "::accel" property.
NB: There is "Prima::KeySelector::describe" function, that converts a key value to a string in human-readable format.
The integer value can be given in a some more readable format when submitting to "::items". Character and F-keys (from F1 to F16) can be used literally, without "kb::" prepending, and the modificator keys can be hinted as prefix characters: km::Shift as '#', km::Ctrl as '^' and km::Alt as '@'. This way, combination of 'control' and 'G' keys can be expressed as '^G' literal, and 'control'+'shift'+'F10' - as '^#F10'.
Hot key in menu item is accessible via "::key" property. The property does accept literal key format, described above.
A literal key string can be converted to an integer value by "translate_shortcut" method.
When the user presses the key combination, that matches to hot key entry in a menu item, its action is triggered.
Action scalar in menu item is accessible via "::action" property.
User data scalar in menu item is accessible via "::data" property.
Syntax of "::items" does not provide 'disabled' and 'checked' states for a menu item as separate fields. These states can be set by using '-' and '*' prefix characters, as described above, in ``Menu item name''. They also can be assigned on per-item basis via "::enabled" and "::checked" properties.
All these fields qualify a most common menu item, that has text, shortcut key and an action - a 'text item'. However, there are also two other types of menu items - a sub-menu and separator. The type of a menu items can not be changed except by full menu item tree change functions ( "::items", "remove()", "insert()".
Sub-menu item can hold same references as text menu item does, except 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, syntax of "::items" can be more elaborated and shown as
$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 ],
...
] ],
...
]);
Separator items do not hold any fields, except name. Their purpose is to hint a logical division of menu items by the system, which visualizes them usually as non-selectable horizontal lines.
In menu bars, the first separator item met by parser is treated differently. It serves as a hint, that the following items must be shown in the right corner of a 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 bars, or ignored.
With these menu items types and fields, it is possible to construct the described above menu description arrays. An item description array can hold from 0 to 6 scalars, and each combination is treated differently.
As an example of all above said, a real-life piece of code is exemplified:
$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 main menu opens
[ "~Clusters" => [ # right-adjacent part
[ "*".checker => "Checking Item" => "Check" ],
[],
[ "-".slave => "Disabled state" => "PrintText"],
...
]]
] );
The code is stripped from 'menu.pl' from 'examples' directory in the toolkit installation. The reader is advised to run the example and learn the menu mechanics.
$menu-> checked('CheckerMenuItem', 1);
can be re-written as
$menu-> CheckerMenuItem-> checked(1);
Name-based call substitutes Prima::MenuItem object, created on the fly. Prima::MenuItem class shares same functions of Prima::AbstractMenu, that handle individual menu items.
Prima::Menu is special in that its top-level items visualized horizontally, and in behavior of the top-level separator items ( see above, ``Menu items'' ).
If "::selected" is set to 1, then a menu object is visualized in a window, otherwise it is not. This behavior allows window to host multiple menu objects without clashing. When a Prima::Menu object gets 'selected', it displaces the previous 'selected' menu Prima::Menu object, and its items are installed into the visible menu bar. Prima::Window property "::menu" then points to the menu object, and "::menuItems" is an alias for "::items" menu class property. Prima::Window's properties "::menuFont" and "::menuColorIndex" are used as visualization hints.
Prima::Menu provide no new methods or properties.
If "::selected" is set to 1, then a menu object is visualized in the system pop-up menu, otherwise it is not. This behavior allows widget to host multiple menu objects without clashing. When a Prima::Popup object gets 'selected', it displaces the previous 'selected' menu Prima::Popup object. Prima::Widget property "::popup" then points to the menu object, and "::popupItems" is an alias for "::items" menu class property. Prima::Widget's properties "::popupFont" and "::popupColorIndex" are used as visualization hints.
A Prima::Popup object can be visualized explicitly, by means of "popup" method. The implicit visualization by the user is happened only if the "::autoPopup" property is set to 1.
Prima::Popup provides new "popup" method and new "::autoPopup" property.
If "::selected" is set to 1, then it displaces the previous 'selected' menu Prima::AccelTable object. Prima::Widget property "::accelTable" then points to the menu object, and "::accelItems" is an alias for "::items" menu class property.
Prima::AccelTable provide no new methods or properties.
If set to 1 in selected state, calls "popup()" action in response to "Popup" notification, when the user presses the default key or mouse button combination.
If 0, the pop-up menu can not be executed implicitly.
Default value: 1
NAME is name of the menu item.
NAME is name of the menu item. SCALAR can be any scalar value, the toolkit does not use this property internally.
NAME is name of the menu item.
"::image" and "::text" are mutually exclusive menu item properties, and can not be set together, but a menu item can change between image and text representation at run time by calling these properties.
NAME is name of the menu item.
"::items" is an ultimate tool for reading and writing the menu items tree, but often it is too powerful, so there are elemental properties "::accel", "::text", "::image", "::checked", "::enabled", "::action", "::data" declared, that handle menu items individually.
NAME is name of the menu item, KEY is an integer value.
Within each menu class, only one menu object can be selected for its owner.
If set to 0, the only actions performed are implicit hot-key lookup when on "KeyDown" event.
Default value: 1
"::text" and "::image" are mutually exclusive menu item properties, and can not be set together, but a menu item can change between image and text representation at run time by calling these properties.
NB: Prima::AccelTable use no system resources, and this method returns its object handle instead.
Returns no value.
Executes the system-driven pop-up menu, in location near (X_OFFSET,Y_OFFSET) pixel on the screen, with items from "::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.
The method can be called with no object.
See Prima::Widget
The method can be called with no object.
The method can be called with no object.