1pod::Prima::Menu(3)   User Contributed Perl Documentation  pod::Prima::Menu(3)
2
3
4

NAME

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

SYNOPSIS

9          use Prima;
10          use Prima::Application;
11
12          my $window = Prima::Window-> new(
13               menuItems => [
14                  [ '~File' => [
15                     [ '~Open', 'Ctrl+O', '^O', \&open_file ],
16                     [ '-save_file', '~Save', km::Ctrl | ord('s'), sub { save_file() } ],
17                     [],
18                     [ '~Exit', 'Alt+X', '@X', sub { exit } ],
19                  ]],
20                  [ '~Options' => [
21                     [ '*option1'  => 'Checkable option' => sub { $_[0]-> menu-> toggle( $_[1]) }],
22                     [ '*@option2' => 'Checkable option' => sub {}], # same
23                  ]],
24                  [],
25                  [ '~Help' => [
26                     [ 'Show help' => sub { $::application-> open_help("file://$0"); }],
27                  ]],
28               ],
29           );
30
31           sub open_file
32           {
33               # enable 'save' menu item
34               $window-> menu-> save_file-> enable;
35           }
36
37           $window-> popupItems( $window-> menuItems);
38

DESCRIPTION

40       The document describes interfaces of Prima::AbstractMenu class, and its
41       three descendants - Prima::Menu, Prima::Popup, and Prima::AccelTable,
42       all aimed at different targets.  Prima::AbstractMenu is a descendant of
43       Prima::Component class, and its specialization is handling of menu
44       items, held in a tree-like structure. Descendants of
45       Prima::AbstractMenu are designed to be attached to widgets and windows,
46       to serve as hints for the system-dependent pop-up and pull-down menus.
47

USAGE

49   Menu items
50       The central point of functionality in Prima::AbstractMenu-derived
51       classes and their object instances ( further referred as 'menu classes'
52       and 'menu objects'), is handling of a complex structure, contained in
53       "::items" property. This property is special in that its structure is a
54       tree-like array of scalars, each of whose is either a description of a
55       menu item or a reference to an array.
56
57       Parameters of an array must follow a special syntax, so the property
58       input can be parsed and assigned correctly. In general, the syntax is
59
60          $menu-> items( [
61             [ menu item description ],
62             [ menu item description ],
63             ...
64          ]);
65
66       where 'menu item description' is an array of scalars, that can hold
67       from 0 up to 6 elements. Each menu item has six fields, that qualify a
68       full description of a menu item; the shorter arrays are shortcuts, that
69       imply default or special cases. These base six fields are:
70
71       Menu item name
72           A string identifier.  Menu items can be accessed individually by
73           their names, and the following fields can be managed by calling
74           elemental properties, that require an item name. If not given, or
75           empty, item name is assigned a string in a form '#ID' where ID is
76           the unique integer value within the menu object.
77
78           IDs are set for each menu item, disregarding whether they have
79           names or not.  Any menu item can be uniquely identifed by its ID
80           value, by supplying the '#ID' string, in the same fashion as named
81           menu items.  When creating or copying menu items, names in format
82           '#ID' are not accepted, and treated as if an empty string is
83           passed. When copying menu items to another menu object, all menu
84           items to be copied change their IDs, but explicitly set names are
85           preserved.  Since the anonymous menu items do not have name, their
86           auto-generated names change also.
87
88           If the name is prepended by '-', '*', or '@' characters, the
89           characters are not treated as part of the name but as indicator
90           that the item is disabled  ( '-' character ), checked ( '*'
91           character ), or has an auto-toggle flag ('@').  This syntax is
92           valid only for "::items" and "insert()" functions, not for
93           "set_variable()" method.
94
95       Menu text / menu image
96           A non-separator menu item can be visualized either as a text string
97           or an image. These options are exclusive to each other, and
98           therefore occupy same field. Menu text is an arbitrary string, with
99           with ~ ( tilde ) quoting for a shortcut character, that the system
100           uses as a hot key during menu navigation.  Menu image is a
101           Prima::Image object of no particular color space and dimensions.
102
103           Menu text in menu item is accessible via the "::text" property, and
104           menu image via the "::image" property. These can not accept or
105           return sensible arguments simultaneously.
106
107       Accelerator text
108           An alternate text string, appearing together with a menu item or a
109           menu image, usually serving as a description to the hot key,
110           associated with a menu item. For example, if a hot key to a menu
111           item is combination of 'enter' and 'control' keys, then usually
112           accelerator text is 'Ctrl+Enter' string.
113
114           Accelerator text in menu item is accessible via "::accel" property.
115
116           NB: There is "Prima::KeySelector::describe" function, that converts
117           a key value to a string in human-readable format.
118
119       Hot key
120           An integer value, combined from either "kb::XXX" constant or a
121           character index with modificator key values ( "km::XXX" constant ).
122           This representation format is not that informative as three-integer
123           key event format (CODE,KEY,MOD), described in Prima::Widget.
124           However, these formats are easily converted to each other:
125           CODE,KEY,MOD is translated to INTEGER format by "translate_key()"
126           method. The reverse operation is not needed for
127           "Prima::AbstractMenu" functionality and is performed by
128           "Prima::KeySelector::translate_codes" method.
129
130           The integer value can be given in a some more readable format when
131           submitting to "::items". Character and F-keys (from F1 to F16) can
132           be used literally, without "kb::" prepending, and the modificator
133           keys can be hinted as prefix characters: km::Shift as '#', km::Ctrl
134           as '^' and km::Alt as '@'. This way, combination of 'control' and
135           'G' keys can be expressed as '^G' literal, and
136           'control'+'shift'+'F10' - as '^#F10'.
137
138           Hot key in menu item is accessible via "::key" property. The
139           property does accept literal key format, described above.
140
141           A literal key string can be converted to an integer value by
142           "translate_shortcut" method.
143
144           When the user presses the key combination, that matches to hot key
145           entry in a menu item, its action is triggered.
146
147       Action
148           Every non-separator and non-submenu item is destined to perform an
149           action. The action can be set either as an anonymous sub, or as
150           string with name of a method on the owner of a menu object. Both
151           have their niche of usage, and both are supplied with three
152           parameters, when called - the owner of a menu object, the name of a
153           menu item, that triggered the action, and the menu checked status:
154
155              Prima::MainWindow-> new(
156                   menuItems => [
157                           ['@item', 'Test',
158                           sub {
159                               my (
160                                  $window,  # MainWindow
161                                  $item,    # 'item'
162                                  $checked  # MainWindow->men('item')->checked
163                               ) = @_;
164                           }],
165                   ]
166              );
167
168           Action scalar in menu item is accessible via "::action" property.
169
170           A special built-in action can automatically toggle a menu item,
171           instead of an explicit call
172
173              $window->menu->toggle($item)
174
175           To achieve this, add '@' character to the menu item name (see "Menu
176           item name").
177
178       User data
179           At last, a non-separator and non-submenu menu item can hold an
180           arbitrary scalar value, the 'user data' field.  The toolkit does
181           not use this field, leaving that to the programmer.
182
183           User data scalar in menu item is accessible via "::data" property.
184
185       Syntax of "::items" does not provide 'disabled' and 'checked' states
186       for a menu item as separate fields. These states can be set by using
187       '-' and '*' prefix characters, as described above, in "Menu item name".
188       They also can be assigned on per-item basis via "::enabled" and
189       "::checked" properties.
190
191       All these fields qualify a most common menu item, that has text,
192       shortcut key and an action - a 'text item'.  However, there are also
193       two other types of menu items - a sub-menu and separator. The type of a
194       menu items can not be changed except by full menu item tree change
195       functions ( "::items", "remove()", "insert()".
196
197       Sub-menu item can hold same references as text menu item does, except
198       the action field. Instead, the action field is used for a sub-menu
199       reference scalar, pointing to another set of menu item description
200       arrays. From that point of view, syntax of "::items" can be more
201       elaborated and shown as
202
203          $menu-> items( [
204             [ text menu item description ],
205             [ sub-menu item description [
206
207                [ text menu item description ],
208                [ sub-menu item description [
209                    [ text menu item description ],
210                    ...
211                ]
212                [ text menu item description ],
213                ...
214             ] ],
215             ...
216          ]);
217
218       Separator items do not hold any fields, except name.  Their purpose is
219       to hint a logical division of menu items by the system, which
220       visualizes them usually as non-selectable horizontal lines.
221
222       In menu bars, the first separator item met by parser is treated
223       differently. It serves as a hint, that the following items must be
224       shown in the right corner of a menu bar, contrary to the left-adjacent
225       default layout. Subsequent separator items in a menu bar declaration
226       can be either shown as a vertical division bars, or ignored.
227
228       With these menu items types and fields, it is possible to construct the
229       described above menu description arrays.  An item description array can
230       hold from 0 to 6 scalars, and each combination is treated differently.
231
232       six - [ NAME, TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU, DATA ]
233           Six-scalar array is a fully qualified text-item description.  All
234           fields correspond to the described above scalars.
235
236       five [ NAME, TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU ]
237           Same as six-scalar syntax, but without DATA field.  If DATA is
238           skipped it is "undef" by default.
239
240       four [ TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU ]
241           Same as five-scalar syntax, but without NAME field.  When NAME is
242           skipped it is assigned to an unique string within menu object.
243
244       three [ NAME, TEXT/IMAGE, ACTION/SUBMENU ]
245           Same as five-scalar syntax, but without ACCEL and KEY fields.  KEY
246           is "kb::NoKey" by default, so no keyboard combination is bound to
247           the item. Default ACCEL value is an empty string.
248
249       two [ TEXT/IMAGE, ACTION/SUBMENU ]
250           Same as three-scalar syntax, but without NAME field.
251
252       one and zero [ ]
253           Both empty and 1-scalar arrays indicate a separator menu item. In
254           case of 1-scalar syntax, the scalar value is ignored.
255
256       As an example of all above said, a real-life piece of code is
257       exemplified:
258
259          $img = Prima::Image-> create( ... );
260          ...
261          $menu-> items( [
262             [ "~File" => [
263                 [ "Anonymous" => "Ctrl+D" => '^d' => sub { print "sub\n";}],   # anonymous sub
264                 [ $img => sub {
265                    my $img = $_[0]-> menu-> image( $_[1]);
266                    my @r = @{$img-> palette};
267                    $img-> palette( [reverse @r]);
268                    $_[0]->menu->image( $_[1], $img);
269                 }],                         # image
270                 [],                         # division line
271                 [ "E~xit" => "Exit"    ]    # calling named function of menu owner
272             ]],
273             [ ef => "~Edit" => [                  # example of system commands usage
274                ...
275                [ "Pa~ste" => sub { $_[0]->foc_action('paste')} ],
276                ...
277                ["~Duplicate menu"=>sub{ TestWindow->create( menu=>$_[0]->menu)}],
278             ]],
279             ...
280             [],                             # divisor in main menu opens
281             [ "~Clusters" => [              # right-adjacent part
282               [ "*".checker =>  "Checking Item"   => "Check"     ],
283               [],
284               [ "-".slave   =>  "Disabled state"   => "PrintText"],
285               ...
286             ]]
287          ] );
288
289       The code is stripped from 'menu.pl' from 'examples' directory in the
290       toolkit installation. The reader is advised to run the example and
291       learn the menu mechanics.
292
293   Prima::MenuItem
294       As described above, text and sub-menu items can be managed by elemental
295       properties - "::accel", "::text", "::image", "::checked", "::enabled",
296       "::action", "::data".  All these, plus some other methods can be called
297       in an alternative way, resembling name-based component calls of
298       Prima::Object. A code
299
300         $menu-> checked('CheckerMenuItem', 1);
301
302       can be re-written as
303
304         $menu-> CheckerMenuItem-> checked(1);
305
306       Name-based call substitutes Prima::MenuItem object, created on the fly.
307       Prima::MenuItem class shares same functions of Prima::AbstractMenu,
308       that handle individual menu items.
309
310   Prima::Menu
311       Objects, derived from Prima::Menu class are used to tandem
312       Prima::Window objects, and their items to be shown as menu bar on top
313       of the window.
314
315       Prima::Menu is special in that its top-level items visualized
316       horizontally, and in behavior of the top-level separator items ( see
317       above, "Menu items" ).
318
319       If "::selected" is set to 1, then a menu object is visualized in a
320       window, otherwise it is not.  This behavior allows window to host
321       multiple menu objects without clashing.  When a Prima::Menu object gets
322       'selected', it displaces the previous 'selected' menu Prima::Menu
323       object, and its items are installed into the visible menu bar.
324       Prima::Window property "::menu" then points to the menu object, and
325       "::menuItems" is an alias for "::items" menu class property.
326       Prima::Window's properties "::menuFont" and "::menuColorIndex" are used
327       as visualization hints.
328
329       Prima::Menu provide no new methods or properties.
330
331   Prima::Popup
332       Objects, derived from Prima::Popup class are used together with
333       Prima::Widget objects.  Menu items are visualized when the user pressed
334       the pop-up key or mouse buttons combination, in response to
335       Prima::Widget's "Popup" notification.
336
337       If "::selected" is set to 1, then a menu object is visualized in the
338       system pop-up menu, otherwise it is not.  This behavior allows widget
339       to host multiple menu objects without clashing.  When a Prima::Popup
340       object gets 'selected', it displaces the previous 'selected' menu
341       Prima::Popup object.  Prima::Widget property "::popup" then points to
342       the menu object, and "::popupItems" is an alias for "::items" menu
343       class property.  Prima::Widget's properties "::popupFont" and
344       "::popupColorIndex" are used as visualization hints.
345
346       A Prima::Popup object can be visualized explicitly, by means of "popup"
347       method. The implicit visualization by the user is happened only if the
348       "::autoPopup" property is set to 1.
349
350       Prima::Popup provides new "popup" method and new "::autoPopup"
351       property.
352
353   Prima::AccelTable
354       This class is destined for a more limited functionality than
355       Prima::Menu and Prima::Popup, primarily for mapping key strokes to
356       predefined actions.  Prima::AccelTable objects are never visualized,
357       and consume no system resources, although full menu item management
358       syntax is supported.
359
360       If "::selected" is set to 1, then it displaces the previous 'selected'
361       menu Prima::AccelTable object.  Prima::Widget property "::accelTable"
362       then points to the menu object, and "::accelItems" is an alias for
363       "::items" menu class property.
364
365       Prima::AccelTable provide no new methods or properties.
366

API

368   Properties
369       accel NAME, STRING / Prima::MenuItem::accel STRING
370           Manages accelerator text for a menu item.  NAME is name of the menu
371           item.
372
373       action NAME, SCALAR / Prima::MenuItem::action SCALAR.
374           Manages action for a menu item.  NAME is name of the menu item.
375           SCALAR can be either an anonymous sub or a method name, defined in
376           the menu object owner's name space.  Both called with three
377           parameters - the owner of a menu object, the menu object itself and
378           the name of the menu item.
379
380       autoPopup BOOLEAN
381           Only in Prima::Popup
382
383           If set to 1 in selected state, calls "popup()" action in response
384           to "Popup" notification, when the user presses the default key or
385           mouse button combination.
386
387           If 0, the pop-up menu can not be executed implicitly.
388
389           Default value: 1
390
391       checked NAME, BOOLEAN / Prima::MenuItem::checked BOOLEAN
392           Manages 'checked' state of a menu item. If 'checked', a menu item
393           visualized with a distinct check-mark near the menu item text or
394           image. Its usage with sub-menu items is possible, although
395           discouraged.
396
397           NAME is name of the menu item.
398
399       data NAME, SCALAR / Prima::MenuItem::data SCALAR
400           Manages the user data scalar.
401
402           NAME is name of the menu item.  SCALAR can be any scalar value, the
403           toolkit does not use this property internally.
404
405       enabled NAME, BOOLEAN / Prima::MenuItem::enabled BOOLEAN
406           Manages 'enabled' state of a menu item. If 'enabled' is 0, a menu
407           item visualized with grayed or otherwise dimmed color palette. If a
408           sub-menu item is disabled, whole sub-menu is inaccessible.
409
410           NAME is name of the menu item.
411
412       image NAME, OBJECT / Prima::MenuItem::image OBJECT
413           Manages the image, bound with a menu item. OBJECT is a non-null
414           Prima::Image object reference, with no particular color space or
415           dimensions ( because of dimensions, its usage in top-level
416           Prima::Menu items is discouraged ).
417
418           "::image" and "::text" are mutually exclusive menu item properties,
419           and can not be set together, but a menu item can change between
420           image and text representation at run time by calling these
421           properties.
422
423           NAME is name of the menu item.
424
425       items SCALAR
426           Manages the whole menu items tree. SCALAR is a multi-level
427           anonymous array structure, with syntax described in "Menu items".
428
429           "::items" is an ultimate tool for reading and writing the menu
430           items tree, but often it is too powerful, so there are elemental
431           properties "::accel", "::text", "::image", "::checked",
432           "::enabled", "::action", "::data" declared, that handle menu items
433           individually.
434
435       key NAME, KEY / Prima::MenuItem::key KEY
436           Manages the hot key combination, bound with a menu item.
437           Internally KEY is kept as an integer value, and get-mode call
438           returns integers only, but set-mode accepts the literal key format
439           - like, '^C', 'F5' strings.
440
441           NAME is name of the menu item, KEY is an integer value.
442
443       selected BOOLEAN
444           If set to 1, menu object is granted extra functionality from a
445           window or widget owner object. Different Prima::AbstractMenu
446           descendant provided with different extra functionalities.  In Usage
447           section, see Prima::Menu, Prima::Popup and Prima::AccelTable.
448
449           Within each menu class, only one menu object can be selected for
450           its owner.
451
452           If set to 0, the only actions performed are implicit hot-key lookup
453           when on "KeyDown" event.
454
455           Default value: 1
456
457       text NAME, STRING / Prima::MenuItem::text STRING
458           Manages the text, bound with a menu item. STRING is an arbitrary
459           string, with '~' ( tilde ) quotation of a hot key character. The
460           hot key character is only used when keyboard navigation of a pop-up
461           or a pull-down menu is performed; it has no influence outside menu
462           sessions.
463
464           "::text" and "::image" are mutually exclusive menu item properties,
465           and can not be set together, but a menu item can change between
466           image and text representation at run time by calling these
467           properties.
468
469   Methods
470       check NAME / Prima::MenuItem::check
471           Alias for checked(1).  Sets menu item in checked state.
472
473       disable NAME / Prima::MenuItem::disable
474           Alias for enabled(0).  Sets menu item in disabled state.
475
476       enabled NAME / Prima::MenuItem::enabled
477           Alias for enabled(1).  Sets menu item in enabled state.
478
479       get_handle
480           Returns a system-dependent menu handle.
481
482           NB: Prima::AccelTable use no system resources, and this method
483           returns its object handle instead.
484
485       has_item NAME
486           Returns boolean value, whether the menu object has a menu item with
487           name NAME.
488
489       insert ITEMS, ROOT_NAME, INDEX
490           Inserts menu item inside existing item tree.  ITEMS has same syntax
491           as "::items".  ROOT_NAME is the name of a menu item, where the
492           insertion must take place; if ROOT_NAME is an empty string, the
493           insertion is performed to the top level items.  INDEX is an offset,
494           which the newly inserted items would possess after the insertion.
495           INDEX 0 indicates the beginning, thus.
496
497           Returns no value.
498
499       popup X_OFFSET, Y_OFFSET, [ LEFT = 0, BOTTOM = 0, RIGHT = 0, TOP = 0 ]
500           Only in Prima::Popup
501
502           Executes the system-driven pop-up menu, in location near
503           (X_OFFSET,Y_OFFSET) pixel on the screen, with items from "::items"
504           tree. The pop-up menu is hinted to be positioned so that the
505           rectangle, defined by (LEFT,BOTTOM) - (RIGHT,TOP) coordinates is
506           not covered by the first-level menu. This is useful when a pop-up
507           menu is triggered by a button widget, for example.
508
509           If during the execution the user selects a menu item, then its
510           associated action is executed ( see "action" ).
511
512           The method returns immediately and returns no value.
513
514       remove NAME / Prima::MenuItem::remove
515           Deletes a menu item from the items tree, and its sub-menus if the
516           item is a sub-menu item.
517
518       select
519           Alias for selected(1).  Sets menu object in selected state.
520
521       set_command KEY, ENABLED
522           Disables or enables menu items, associated with key combinations
523           KEY.
524
525       set_variable NAME, NEW_NAME
526           Changes the name of a menu item with NAME to NEW_NAME.  NEW_NAME
527           must not be an empty string and must not be in a '#integer' form.
528
529       toggle NAME / Prima::MenuItem::toggle
530           Toggles the checked state of a menu item and returns the new state.
531
532       translate_accel TEXT
533           Locates a '~' ( tilde ) - escaped character in a TEXT string and
534           returns its index ( as ord(lc())), or 0 if no escaped characters
535           were found.
536
537           The method can be called with no object.
538
539       translate_key CODE, KEY, MOD
540           Translates three-integer key representation into the one-integer
541           format and returns the integer value.  The three-integer format is
542           used in "KeyDown" and "KeyUp" notifications for Prima::Widget.
543
544           See Prima::Widget
545
546           The method can be called with no object.
547
548       translate_shortcut KEY
549           Converts literal-represented KEY string into the integer format and
550           returns the integer value.
551
552           The method can be called with no object.
553
554       uncheck NAME / Prima::MenuItem::uncheck
555           Alias for checked(0).  Sets menu item in unchecked state.
556

BUGS

558       Menu colors and fonts don't work on Windows and probably never will.
559

AUTHOR

561       Dmitry Karasik, <dmitry@karasik.eu.org>.
562

SEE ALSO

564       Prima, Prima::Object, Prima::Widget, Prima::Window
565
566
567
568perl v5.30.1                      2020-01-30               pod::Prima::Menu(3)
Impressum