|
Prima::Menu - pull-down and pop-up menu objects |
Prima::Menu - pull-down and pop-up menu objects
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.
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:
set_variable()
method. If the menu name was not given explicitly, it is formed
by sprintf("MenuItem_%d", unique number) string automatically.
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.
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 the Prima::Widget manpage.
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 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.
undef by default.
kb::NoKey by default, so no keyboard combination
is bound to the item. Default ACCEL value is an empty string.
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 the Prima::Object manpage. 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.
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.
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.
checked(1).
Sets menu item in checked state.
enabled(0).
Sets menu item in disabled state.
enabled(1).
Sets menu item in enabled state.
NB: Prima::AccelTable use no system resources, and this method returns its object handle instead.
::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.
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.
selected(1).
Sets menu object in selected state.
The method can be called with no object.
KeyDown and KeyUp notifications for Prima::Widget.
The method can be called with no object.
The method can be called with no object.
checked(0).
Sets menu item in unchecked state.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, the Prima::Object manpage, the Prima::Widget manpage, the Prima::Window manpage
|
Prima::Menu - pull-down and pop-up menu objects |