Man Linux: Main Page and Category List

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

   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
       "::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.

   Prima::MenuItem
       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.

   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, "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.

   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 "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