1pod::Prima::Menu(3) User Contributed Perl Documentation pod::Prima::Menu(3)
2
6 Prima::Menu - pull-down and pop-up menu objects
7
9 use Prima;
10 use Prima::Application;
11 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 sub open_file
32 {
33 # enable 'save' menu item
34 $window-> menu-> save_file-> enable;
35 }
36 $window-> popupItems( $window-> menuItems);
38
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
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 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 $menu-> items( [
61 [ menu item description ],
62 [ menu item description ],
63 ...
64 ]);
65 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 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 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 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 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 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 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 Accelerator text in menu item is accessible via "::accel" property.
115 NB: There is "Prima::KeySelector::describe" function, that converts
117 a key value to a string in human-readable format.
118 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 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 Hot key in menu item is accessible via "::key" property. The
139 property does accept literal key format, described above.
140 A literal key string can be converted to an integer value by
142 "translate_shortcut" method.
143 When the user presses the key combination, that matches to hot key
145 entry in a menu item, its action is triggered.
146 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 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 Action scalar in menu item is accessible via "::action" property.
169 A special built-in action can automatically toggle a menu item,
171 instead of an explicit call
172 $window->menu->toggle($item)
174 To achieve this, add '@' character to the menu item name (see "Menu
176 item name").
177 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 User data scalar in menu item is accessible via "::data" property.
184 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 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 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 $menu-> items( [
204 [ text menu item description ],
205 [ sub-menu item description [
206 [ 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 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 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 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 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 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 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 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 two [ TEXT/IMAGE, ACTION/SUBMENU ]
250 Same as three-scalar syntax, but without NAME field.
251 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 As an example of all above said, a real-life piece of code is
257 exemplified:
258 $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 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 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 $menu-> checked('CheckerMenuItem', 1);
301 can be re-written as
303 $menu-> CheckerMenuItem-> checked(1);
305 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 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 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 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 Prima::Menu provide no new methods or properties.
330 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 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 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 Prima::Popup provides new "popup" method and new "::autoPopup"
351 property.
352 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 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 Prima::AccelTable provide no new methods or properties.
366
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 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 autoPopup BOOLEAN
381 Only in Prima::Popup
382 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 If 0, the pop-up menu can not be executed implicitly.
388 Default value: 1
390 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 NAME is name of the menu item.
398 data NAME, SCALAR / Prima::MenuItem::data SCALAR
400 Manages the user data scalar.
401 NAME is name of the menu item. SCALAR can be any scalar value, the
403 toolkit does not use this property internally.
404 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 NAME is name of the menu item.
411 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 "::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 NAME is name of the menu item.
424 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 "::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 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 NAME is name of the menu item, KEY is an integer value.
442 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 Within each menu class, only one menu object can be selected for
450 its owner.
451 If set to 0, the only actions performed are implicit hot-key lookup
453 when on "KeyDown" event.
454 Default value: 1
456 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 "::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 Methods
470 check NAME / Prima::MenuItem::check
471 Alias for checked(1). Sets menu item in checked state.
472 disable NAME / Prima::MenuItem::disable
474 Alias for enabled(0). Sets menu item in disabled state.
475 enabled NAME / Prima::MenuItem::enabled
477 Alias for enabled(1). Sets menu item in enabled state.
478 get_handle
480 Returns a system-dependent menu handle.
481 NB: Prima::AccelTable use no system resources, and this method
483 returns its object handle instead.
484 has_item NAME
486 Returns boolean value, whether the menu object has a menu item with
487 name NAME.
488 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 Returns no value.
498 popup X_OFFSET, Y_OFFSET, [ LEFT = 0, BOTTOM = 0, RIGHT = 0, TOP = 0 ]
500 Only in Prima::Popup
501 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 If during the execution the user selects a menu item, then its
510 associated action is executed ( see "action" ).
511 The method returns immediately and returns no value.
513 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 select
519 Alias for selected(1). Sets menu object in selected state.
520 set_command KEY, ENABLED
522 Disables or enables menu items, associated with key combinations
523 KEY.
524 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 toggle NAME / Prima::MenuItem::toggle
530 Toggles the checked state of a menu item and returns the new state.
531 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 The method can be called with no object.
538 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 See Prima::Widget
545 The method can be called with no object.
547 translate_shortcut KEY
549 Converts literal-represented KEY string into the integer format and
550 returns the integer value.
551 The method can be called with no object.
553 uncheck NAME / Prima::MenuItem::uncheck
555 Alias for checked(0). Sets menu item in unchecked state.
556
558 Menu colors and fonts don't work on Windows and probably never will.
559
561 Dmitry Karasik, <dmitry@karasik.eu.org>.
562
564 Prima, Prima::Object, Prima::Widget, Prima::Window
565perl v5.30.0 2019-08-21 pod::Prima::Menu(3)