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]) }],
]],
[],
[ '~Help' => [
[ 'Show help' => sub { $::application-> open_help($0); }],
]],
],
);
sub open_file
{
# enable 'save' menu item
$window-> menu-> save_file-> enable;
}
$window-> popupItems( $window-> menuItems);
DESCRIPTION¶
The document describes interfaces of Prima::AbstractMenu class, and its three
descendants - Prima::Menu, Prima::Popup, and Prima::AccelTable, all aimed at
different targets. Prima::AbstractMenu is a descendant of Prima::Component
class, and its specialization is 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 as 'menu classes' and 'menu
objects'), is handling of a complex structure, contained in
"::items" property. This property is special in that its structure
is a tree-like array of scalars, each of whose 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 '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:
- Menu item name
- A string identifier. Menu items can be accessed individually by their
names, and the following fields can be managed by calling elemental
properties, that require an item name. If not given, or empty, item name
is assigned a string in a form '#ID' where ID is the unique integer value
within the menu object.
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 / menu image
- A non-separator menu item can be visualized either as a text string or an
image. These options are exclusive to each other, and therefore occupy
same field. Menu text is an arbitrary string, with with ~ ( tilde )
quoting for a shortcut character, that the system uses as a hot key during
menu navigation. Menu image is a Prima::Image object of no particular
color space and dimensions.
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
- An alternate text string, appearing together with a menu item or a menu
image, usually serving as a description to the hot key, associated with a
menu item. For example, if a hot key to a menu item is combination of
'enter' and 'control' keys, then usually accelerator text is 'Ctrl+Enter'
string.
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.
- Hot key
- An integer value, combined from either "kb::XXX" constant or a
character index with modificator key values ( "km::XXX" constant
). This representation format is not that informative as three-integer key
event format (CODE,KEY,MOD), described in Prima::Widget. However, these
formats are easily converted to each other: CODE,KEY,MOD is translated to
INTEGER format by "translate_key()" method. The reverse
operation is not needed for "Prima::AbstractMenu" functionality
and is performed by "Prima::KeySelector::translate_codes"
method.
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
- Every non-separator and non-submenu item is destined to perform an action.
The action can be set either as an anonymous sub, or as string with name
of a method on the owner of a menu object. Both have their niche of usage,
and both are supplied with three parameters, when called - the owner of a
menu object, the menu object itself and the name of a menu item, that
triggered the action.
Action scalar in menu item is accessible via "::action"
property.
- User data
- At last, a non-separator and non-submenu menu item can hold an arbitrary
scalar value, the 'user data' field. The toolkit does not use this field,
leaving that to the programmer.
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.
- six - [ NAME, TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU, DATA ]
- 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 six-scalar syntax, but without DATA field. If DATA is skipped it
is "undef" by default.
- four [ TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU ]
- Same as five-scalar syntax, but without NAME field. When NAME is skipped
it is assigned to an unique string within menu object.
- three [ NAME, TEXT/IMAGE, ACTION/SUBMENU ]
- Same as five-scalar syntax, but without ACCEL and KEY fields. KEY is
"kb::NoKey" by default, so no keyboard combination is bound to
the item. Default ACCEL value is an empty string.
- two [ TEXT/IMAGE, ACTION/SUBMENU ]
- Same as three-scalar syntax, but without NAME field.
- one and zero [ ]
- Both empty and 1-scalar arrays indicate a separator menu item. In case of
1-scalar syntax, the scalar value is ignored.
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.
As described above, text and sub-menu items can be managed by elemental
properties - "::accel", "::text", "::image",
"::checked", "::enabled", "::action",
"::data". All these, plus some other methods can be called in an
alternative way, resembling name-based component calls of Prima::Object. A
code
$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.
Objects, derived from Prima::Menu class are used to tandem Prima::Window
objects, and their items to be shown as menu bar on top of the window.
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.
Objects, derived from Prima::Popup class are used together with Prima::Widget
objects. Menu items are visualized when the user pressed the pop-up key or
mouse buttons combination, in response to Prima::Widget's "Popup"
notification.
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.
Prima::AccelTable¶
This class is destined for a more limited functionality than Prima::Menu and
Prima::Popup, primarily for mapping key strokes to predefined actions.
Prima::AccelTable objects are never visualized, and consume no system
resources, although full menu item management syntax is supported.
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.
API¶
Properties¶
- accel NAME, STRING / Prima::MenuItem::accel STRING
- Manages accelerator text for a menu item. NAME is name of the menu
item.
- action NAME, SCALAR / Prima::MenuItem::action SCALAR.
- Manages action for a menu item. NAME is name of the menu item. SCALAR can
be either an anonymous sub or a method name, defined in the menu object
owner's name space. Both called with three parameters - the owner of a
menu object, the menu object itself and the name of the menu item.
- autoPopup BOOLEAN
- Only in Prima::Popup
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
- checked NAME, BOOLEAN / Prima::MenuItem::checked BOOLEAN
- Manages 'checked' state of a menu item. If 'checked', a menu item
visualized with a distinct check-mark near the menu item text or image.
Its usage with sub-menu items is possible, although discouraged.
NAME is name of the menu item.
- data NAME, SCALAR / Prima::MenuItem::data SCALAR
- Manages the user data scalar.
NAME is name of the menu item. SCALAR can be any scalar value, the toolkit
does not use this property internally.
- enabled NAME, BOOLEAN / Prima::MenuItem::enabled BOOLEAN
- Manages 'enabled' state of a menu item. If 'enabled' is 0, a menu item
visualized with grayed or otherwise dimmed color palette. If a sub-menu
item is disabled, whole sub-menu is inaccessible.
NAME is name of the menu item.
- image NAME, OBJECT / Prima::MenuItem::image OBJECT
- Manages the image, bound with a menu item. 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 ).
"::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 SCALAR
- Manages the whole menu items tree. SCALAR is a multi-level anonymous array
structure, with syntax described in "Menu items".
"::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.
- key NAME, KEY / Prima::MenuItem::key KEY
- Manages the hot key combination, bound with a menu item. Internally KEY is
kept as an integer value, and get-mode call returns integers only, but
set-mode accepts the literal key format - like, '^C', 'F5' strings.
NAME is name of the menu item, KEY is an integer value.
- selected BOOLEAN
- If set to 1, menu object is granted extra functionality from a window or
widget owner object. Different Prima::AbstractMenu descendant provided
with different extra functionalities. In Usage section, see
Prima::Menu, Prima::Popup and Prima::AccelTable.
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 NAME, STRING / Prima::MenuItem::text STRING
- Manages the text, bound with a menu item. STRING is an arbitrary string,
with '~' ( tilde ) quotation of a hot key character. The hot key character
is only used when keyboard navigation of a pop-up or a pull-down menu is
performed; it has no influence outside menu sessions.
"::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.
Methods¶
- check NAME / Prima::MenuItem::check
- Alias for checked(1). Sets menu item in checked state.
- disable NAME / Prima::MenuItem::disable
- Alias for enabled(0). Sets menu item in disabled state.
- enabled NAME / Prima::MenuItem::enabled
- Alias for enabled(1). Sets menu item in enabled state.
- get_handle
- Returns a system-dependent menu handle.
NB: Prima::AccelTable use no system resources, and this method returns its
object handle instead.
- has_item NAME
- Returns boolean value, whether the menu object has a menu item with name
NAME.
- insert ITEMS, ROOT_NAME, INDEX
- Inserts menu item inside existing item tree. ITEMS has same syntax as
"::items". ROOT_NAME is the name of a 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, which the newly
inserted items would possess after the insertion. INDEX 0 indicates the
beginning, thus.
Returns no value.
- 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 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.
- remove NAME / Prima::MenuItem::remove
- Deletes a menu item from the items tree, and its sub-menus if the item is
a sub-menu item.
- select
- Alias for selected(1). Sets menu object in selected state.
- set_command KEY, ENABLED
- Disables or enables menu items, associated with key combinations KEY.
- set_variable NAME, NEW_NAME
- Changes the name of a menu item with NAME to NEW_NAME. NEW_NAME must not
be an empty string and must not be in a '#integer' form.
- toggle NAME / Prima::MenuItem::toggle
- Toggles the checked state of a menu item and returns the new state.
- translate_accel TEXT
- Locates a '~' ( tilde ) - escaped character in a 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 three-integer key representation into the one-integer format
and returns the integer value. The three-integer format is used in
"KeyDown" and "KeyUp" notifications for Prima::Widget.
See Prima::Widget
The method can be called with no object.
- translate_shortcut KEY
- Converts literal-represented 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 menu item in unchecked state.
AUTHOR¶
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO¶
Prima, Prima::Object, Prima::Widget, Prima::Window