Prima

 view release on metacpan or  search on metacpan

pod/Prima/Menu.pod  view on Meta::CPAN

=head1 NAME

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

=head1 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);

=head1 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.

=head1 USAGE

=head2 Menu items

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
C<::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:

=over

=item 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 identified 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 special characters ( see below ), these characters
are not treated as part of the name but as an item modifier.  This syntax is
valid only for C<::items> and C<insert()> functions, not for C<set_variable()>
method.

pod/Prima/Menu.pod  view on Meta::CPAN

=head2 Prima::MenuItem

As described above, text and sub-menu items can be managed
by elemental properties - C<::accel>, C<::text>, C<::image>,
C<::checked>, C<::enabled>, C<::action>, C<::data>.
All these, plus some other methods can be called in an
alternative way, resembling name-based component calls
of L<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.

=head2 Prima::Menu

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, L<Menu items> ).

If C<::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 C<::menu> then points to the menu object, and
C<::menuItems> is an alias for C<::items> menu class property.
Prima::Window's properties C<::menuFont> and C<::menuColorIndex>
are used as visualization hints.

Prima::Menu provides no new methods or properties.

=head2 Prima::Popup

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 C<Popup> notification.

If C<::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 C<::popup> then points to the menu object, and
C<::popupItems> is an alias for C<::items> menu class property.
Prima::Widget's properties C<::popupFont> and C<::popupColorIndex>
are used as visualization hints.

A Prima::Popup object can be visualized
explicitly, by means of C<popup> method. The
implicit visualization by the user is happened only
if the C<::autoPopup> property is set to 1.

Prima::Popup provides new C<popup> method
and new C<::autoPopup> property.

=head2 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 C<::selected> is set to 1, then it displaces
the previous 'selected' menu Prima::AccelTable object.
Prima::Widget property C<::accelTable> then points to
the menu object, and C<::accelItems> is an alias for
C<::items> menu class property.

Prima::AccelTable provide no new methods or properties.

=head1 API

=head2 Properties

=over

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

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

=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.

=item autoPopup BOOLEAN

Only in Prima::Popup

If set to 1 in selected state, calls C<popup()> action
in response to C<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

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

Manages autoToggle flag for a menu item. When set, C<checked> option is flipped
when 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 the user
that an item is a toggle, despite being unchecked.

=item 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.

=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.

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

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

Default: true

NAME is name of the menu item.

=item group NAME, INTEGER / Prima::MenuItem::group INTEGER

If not 0, treated as a member of radio group with that number when checked.
I.e. if one of the group is checked, others are unchecked.

=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 ).

C<::image> and C<::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.

pod/Prima/Menu.pod  view on Meta::CPAN

=item enabled NAME / Prima::MenuItem::enabled

Alias for C<enabled(1)>.
Sets menu item in enabled state.

=item execute NAME

Calls the action associated with the menu item

=item find_item_by_key KEY

Finds items by the associated hot key combination

=item get_handle

Returns a system-dependent menu handle.

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

=item get_children NAME

Returns list of NAME's children

=item get_item NAME, FULL_TREE = 0

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

=item get_item NAMES, FULL_TREE = 0

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

=item has_item NAME

Returns boolean value, whether the menu object has
a menu item with name NAME.

=item insert ITEMS, ROOT_NAME, INDEX

Inserts menu item inside existing item tree.
ITEMS has same syntax as C<::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.

=item is_separator NAME

Returns true if the item is a separator, false otherwise

=item is_submenu NAME

Returns true if the item has submenu, false otherwise

=item 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 C<::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 C<action> ).

The method returns immediately and returns no value.

=item 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.

=item select

Alias for C<selected(1)>.
Sets menu object in selected state.

=item 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.

=item toggle NAME / Prima::MenuItem::toggle

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

=item 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.

=item 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
C<KeyDown> and C<KeyUp> notifications for Prima::Widget.

See L<Prima::Widget>

The method can be called with no object.

=item translate_shortcut KEY

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