Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pod::Prima::Menu(3)   User Contributed Perl Documentation  pod::Prima::Menu(3)

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])	}],
		     [ '*@option2' => 'Checkable option' => sub	{}], # same
		  ]],
		  [],
		  [ '~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, the
	   characters are not treated as part of the name but as indicator
	   that	the item is disabled  (	'-' character ), checked ( '*'
	   character ),	or has an auto-toggle flag ('@').  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 name of a
	   menu	item, that triggered the action, and the menu checked status:

	      Prima::MainWindow-> new(
		   menuItems =>	[
			   ['@item', 'Test',
			   sub {
			       my (
				  $window,  # MainWindow
				  $item,    # 'item'
				  $checked  # MainWindow->men('item')->checked
			       ) = @_;
			   }],
		   ]
	      );

	   Action scalar in menu item is accessible via	"::action" property.

	   A special built-in action can automatically toggle a	menu item,
	   instead of an explicit call

	      $window->menu->toggle($item)

	   To achieve this, add	'@' character to the menu item name (see "Menu
	   item	name").

       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.

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

AUTHOR
       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO
       Prima, Prima::Object, Prima::Widget, Prima::Window

perl v5.24.1			  2017-02-27		   pod::Prima::Menu(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | API | BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pod::Prima::Menu&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help