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

FreeBSD Manual Pages

  
 
  

home | help
Prima::DockManager(3) User Contributed Perl DocumentationPrima::DockManager(3)

NAME
       Prima::DockManager - advanced dockable widgets

DESCRIPTION
       "Prima::DockManager" contains classes that implement additional
       functionality within the	dockable widgets paradigm.

       The module introduces two new dockable widget classes:
       "Prima::DockManager::Panelbar", a general purpose dockable container
       for variable-sized widgets; and "Prima::DockManager::Toolbar", a
       dockable	container for fixed-size command widgets, mostly push buttons.
       The command widgets, nested in a	toolbar, can also be docked.

       "Prima::DockManager" class is an	application-oriented class in a	way
       that ( mostly ) the only	instance of it is needed in the	program. It is
       derived from "Prima::Component" and therefore is	never visualized.  The
       class instance is stored	in "instance" property of all module classes
       to serve	as a docking hierarchy root. Through the document, instance
       term is referred	to "Prima::DockManager"	class instance.

       The module by itself is not enough to make a docking-aware application
       work effectively. The reader is urged to	look at	examples/dock.pl
       example code, which demonstrates	the usage and capabilities of the
       module.

Prima::DockManager::Toolbar
       A toolbar widget	class. The toolbar has a dual nature; it can dock and
       accept docking widgets simultaneously. In the scope of
       "Prima::DockManager", the toolbar hosts command widget, mostly push
       buttons.

       The toolbar consists of two widgets. The	external dockable widget is
       implemented in "Prima::DockManager::Toolbar", and the internal dock in
       "Prima::DockManager::ToolbarDocker" classes.

   Properties
       autoClose BOOLEAN
	   Selects the behavior	of a toolbar when all of its command widgets
	   are undocked. If 1, the toolbar is automatically destroyed. If 0 it
	   calls visible(0).

       childDocker WIDGET
	   Pointer to "Prima::DockManager::ToolbarDocker" instance.

	   See also "Prima::DockManager::ToolbarDocker::parentDocker".

       instance	INSTANCE
	   "Prima::DockManager"	instance, the docking hierarchy	root.

Prima::DockManager::ToolbarDocker
       Internal	class, implements a dock widget	for command widgets, while
       serves as a client in a dockable	toolbar, which is a
       "Prima::LinearDockerShuttle" descendant.	When its size is changed due
       an eventual rearrange of	its docked widgets, also resizes the toolbar.

   Properties
       instance	INSTANCE
	   "Prima::DockManager"	instance, the docking hierarchy	root.

       parentDocker WIDGET
	   Pointer to "Prima::DockManager::Toolbar" instance. When in the
	   docked state, "parentDocker"	value is always	equals to "owner".

	   See also "Prima::DockManager::Toolbar::childDocker".

   Methods
       get_extent
	   Calculates the minimal rectangle that encloses all docked widgets
	   and returns its extensions.

       update_size
	   Called when size is changed to resizes the owner widget. If it is
	   in the docked state,	the size change	might result in	change of
	   position or docking state.

Prima::DockManager::Panelbar
       The class is derived from "Prima::LinearDockerShuttle", and is
       different only in that "instance" property is introduced, and the
       external	shuttle	can be resized interactively.

       The class is to be used as a simple host	to sizeable widgets.  The user
       can dispose of the panel	bar by clicking	close button on	the external
       shuttle.

   Properties
       instance	INSTANCE
	   "Prima::DockManager"	instance, the docking hierarchy	root.

Prima::DockManager
       A binder	class, contains	set of functions that groups toolbars, panels,
       and command widgets together under the docking hierarchy.

       The manager servers several purposes.  First, it	is a command state
       holder: the command widgets, mostly buttons, usually are	in enabled or
       disabled	state in different life	stages of a program. The manager
       maintains the enabled/disabled state by assigning each command an
       unique scalar value ( farther and in the	code referred as CLSID ). The
       toolbars	can be created with set	of command widgets, referred via these
       CLSIDs. The same	is valid for the panels	- although they	do not host
       command widgets,	the widgets that they do host can also be created
       indirectly via CLSID identifier.	 In addition to	CLSID, the commands
       can be grouped by sections.  Both CLSID and group descriptor scalars
       are defined by the programmer.

       Second, "create_manager"	method presents	a standard configuration
       widget, that allows rearranging of normally non-dockable	command
       widgets,	by presenting a	full set of available commands to the user as
       icons.  Dragging	the icons to toolbars, dock widgets or merely outside
       the configuration widget	automatically creates the corresponding
       command widget.	The notable moment here	is that	the command widgets
       are not required	to know	anything about dragging	and docking; any
       "Prima::Widget" descendant can be used as a command widget.

       Third, it helps maintaining the toolbars	and panels visibility when the
       main window is hidden or	restored. "windowState"	method hides or	shows
       the toolbars and	panels effectively.

       Fourth, it serves as a docking hierarchy	root. All docking sessions
       begin from "Prima::DockManager" object, which although does not provide
       docking capabilities itself ( it	is "Prima::Component" descendant ),
       redirects the docking requests to the lower-level dock widgets.

       Fifth, it provides number of helper methods and notifications, and
       enforces	use or "fingerprint" property by all dockable widgets.	This
       property	has default value of 0xFFFF ( defined in "Prima::Docks"	).
       The module contains the fingerprint "dmfp::XXX" constants with value
       greater than this, so the toolbars and panels are not docked to a dock
       widget with the default configuration. The base constant	set is:

	       fdmp::Tools	( 0x0F000) - dock the command widgets
	       fdmp::Toolbar	( 0x10000) - dock the toolbars
	       fdmp::LaunchPad	( 0x20000) - allows widgets recycling

       All this	functionality is demonstrated in examples/dock.pl example.

   Properties
       commands	HASH
	   A hash of boolean values, with keys of CLSID	scalars.  If value is
	   1, the command is available.	If 0, the command is disabled. Changes
	   to this property are	reflected in the visible command widgets,
	   which are enabled or	disabled immediately. Also, "CommandChange"
	   notification	is triggered.

       fingerprint INTEGER
	   The property	is read-only, and always returns 0xFFFFFFFF, to	allow
	   landing for all dockable widgets. In	case when a finer granulation
	   is needed, the default "fingerprint"	values of toolbars and panels
	   can be reset.

       interactiveDrag BOOLEAN
	   If 1, the command widgets can be interactively dragged, created and
	   destroyed. This property is usually operated	together with
	   "create_manager" widget. If 0, the command widgets cannot be
	   dragged.

	   Default value: 0

   Methods
       activate
	   Brings to front all toolbars	and panels. To be used inside a
	   callback code of a main window, that	has the	toolbars and panels
	   attached to:

		   onActivate => sub { $dock_manager-> activate	}

       auto_toolbar_name
	   Returns an unique name for an automatically created toolbar,	like
	   "Toolbar1", "Toolbar2" etc.

       commands_enable BOOLEAN,	@CLSIDs
	   Enabled or disables commands	from CLSIDs array.  The	changes	are
	   reflected in	the visible command widgets, which are enabled or
	   disabled immediately.  Also,	"CommandChange"	notification is
	   triggered.

       create_manager OWNER, %PROFILE
	   Inserts two widgets into OWNER with PROFILE parameters: a listbox
	   with	command	section	groups,	displayed as items, that usually
	   correspond to the predefined	toolbar	names, and a notebook that
	   displays the	command	icons. The notebook pages are interactively
	   selected by the listbox navigation.

	   The icons, dragged from the notebook, behave	as dockable widgets:
	   they	can be landed upon a toolbar, or any other dock	widget,	given
	   it matches the "fingerprint"	( by default
	   "dmfp::LaunchPad|dmfp::Toolbar|dmfp::Tools").  "dmfp::LaunchPad"
	   constant allows the recycling; if a widget is dragged back onto the
	   notebook, it	is destroyed.

	   Returns two widgets,	the listbox and	the notebook.

	   PROFILE recognizes the following keys:

	   origin X, Y
	       Position	where the widgets are to be inserted.  Default value
	       is 0,0.

	   size	X, Y
	       Size of the widget insertion area. By default the widgets
	       occupy all OWNER	interior.

	   listboxProfile PROFILE
	       Custom parameters, passed to the	listbox.

	   dockerProfile PROFILE
	       Custom parameteres, passed to the notebook.

       create_panel CLSID, %PROFILE
	   Creates a dockable panel of a previously registered CLSID by
	   "register_panel". PROFILE recognizes	the following keys:

	   profile HASH
	       Hash of parameters, passed to "create()"	of the panel widget
	       class.  Before passing it is merged with	the set	of parameters,
	       registered by "register_panel". The "profile" hash takes	the
	       precedence.

	   dockerProfile HASH
	       Constains extra options,	passed to
	       "Prima::DockManager::Panelbar" widget. Before the usage it is
	       merged with the set of parameters, registered by
	       "register_panel".

	       NB: The "dock" key here contains	a reference to a desired dock
	       widget.	If "dock" set to "undef", the panel is created in the
	       non-docked state.

	   Example:

		   $dock_manager-> create_panel( $CLSID,
			   dockerProfile => { dock => $main_window }},
			   profile	 => { backColor	=> cl::Green });

       create_tool OWNER, CLSID, X1, Y1, X2, Y2
	   Inserts a command widget, previously	registered with	CLSID by
	   "register_tool", into OWNER widget with X1 -	Y2 coordinates.	For
	   automatic maintenance of enable/disable state of command widgets
	   OWNER is expected to	be a toolbar. If it is not, the	maintenance
	   must	be performed separately, for example, by "CommandChange"
	   event.

       create_toolbar %PROFILE
	   Creates a new toolbar of "Prima::DockManager::Toolbar" class.  The
	   following PROFILE options are recognized:

	   autoClose BOOLEAN
	       Sets "autoClose"	property of the	toolbar.

	       Default value is	1 if "name" options is set, 0 otherwise.

	   dock	DOCK
	       Contain a reference to a	desired	DOCK widget. If	"undef", the
	       toolbar is created in the non-docked state.

	   dockerProfile HASH
	       Parameters passed to "Prima::DockManager::Toolbar" as creation
	       properties.

	       NB: The "dock" key here contains	a reference to a desired dock
	       widget.	If "dock" set to "undef", the panel is created in the
	       non-docked state.

	   rect	X1, Y1,	X2, Y2
	       Selects rectangle of the	"Prima::DockManager::ToolbarDocker"
	       instance	in the dock widget ( if	docked ) or the	screen ( if
	       non-docked ) coordinates.

	   toolbarProfile HASH
	       Parameters passed to "Prima::DockManager::ToolbarDocker"	as
	       creation	properties.

	   vertical BOOLEAN
	       Sets "vertical" property	of the toolbar.

	   visible BOOLEAN
	       Selects visibility state	of the toolbar.

       get_class CLSID
	   Returns class record	hash, registered under CLSID, or "undef" if
	   the class is	not registered.	The hash format	contains the following
	   keys:

	   class STRING
	       Widget class

	   profile HASH
	       Creation	parameters passed to "create" when the widget is
	       created.

	   tool	BOOLEAN
	       If 1, the class belongs to a control widget. If 0, the class
	       represents a panel client widget.

	   lastUsedDock	DOCK
	       Saved value of the last used dock widget

	   lastUsedRect	X1, Y1,	X2, Y2
	       Saved coordinates of the	widget

       panel_by_id CLSID
	   Return reference to a panel widget represented by CLSID scalar, or
	   "undef" if none found.

       panel_menuitems CALLBACK
	   A helper function; maps all panel names into	a structure, ready to
	   feed	into "Prima::AbstractMenu::items" property ( see Prima::Menu
	   ).  The action member of the	menu item record is set	to CALLBACK
	   scalar.

       panel_visible CLSID, BOOLEAN
	   Sets	the visibility of a panel, referred by CLSID scalar.  If
	   VISIBLE is 0, a panel is destroyed; if 1, new panel instance	is
	   created.

       panels
	   Returns all visible panel widgets in	an array.

       predefined_panels CLSID,	DOCK, [	CLSID, DOCK, ... ]
	   Accepts pairs of scalars, where each	first item is a	panel CLSID
	   and second is the default dock widget. Checks for panel visibility,
	   and creates the panels that are not visible.

	   The method is useful	in program startup, when some panels have to
	   be visible from the beginning.

       predefined_toolbars @PROFILES
	   Accepts array of hashes, where each array item describes a toolbar
	   and a default set of	command	widgets. Checks	for toolbar
	   visibility, and creates the toolbars	that are not visible.

	   The method recognizes the following PROFILES	options:

	   dock	DOCK
	       The default dock	widget.

	   list	ARRAY
	       Array of	CLSIDs corresponding to	the command widgets to be
	       inserted	into the toolbar.

	   name	STRING
	       Selects toolbar name.

	   origin X, Y
	       Selects the toolbar position relative to	the dock ( if "dock"
	       is specified ) or to the	screen ( if "dock" is not specified ).

	   The method is useful	in program startup, when some panels have to
	   be visible from the beginning.

       register_panel CLSID, PROFILE
	   Registers a panel client class and set of parameters	to be
	   associated with CLSID scalar. PROFILE must contain the following
	   keys:

	   class STRING
	       Client widget class

	   text	STRING
	       String, displayed in the	panel title bar

	   dockerProfile HASH
	       Hash of parameters, passed to "Prima::DockManager::Panelbar".

	   profile
	       Hash of parameters, passed to the client	widget.

       register_tool CLSID, PROFILE
	   Registers a control widget class and	set of parameters to be
	   associated with CLSID scalar. PROFILE must be set the following
	   keys:

	   class STRING
	       Client widget class

	   profile HASH
	       Hash of parameters, passed to the control widget.

       toolbar_by_name NAME
	   Returns a pointer to	a toolbar of NAME, or "undef" if none found.

       toolbar_menuitems CALLBACK
	   A helper function; maps all toolbar names into a structure, ready
	   to feed into	"Prima::AbstractMenu::items" property (	see
	   Prima::Menu ).  The action member of	the menu item record is	set to
	   CALLBACK scalar.

       toolbar_visible TOOLBAR,	BOOLEAN
	   Sets	the visibility of a TOOLBAR.  If VISIBLE is 0, the toolbar is
	   hidden; if 1, it is shown.

       toolbars
	   Returns all toolbar widgets in an array.

       windowState INTEGER
	   Mimics interface of "Prima::Window::windowState", and maintains
	   visibility of toolbars and panels. If the parameter is
	   "ws::Minimized", the	toolbars and panels are	hidden.	On any other
	   parameter these are shown.

	   To be used inside a callback	code of	a main window, that has	the
	   toolbars and	panels attached	to:

		   onWindowState => sub	{ $dock_manager-> windowState( $_[1] ) }

   Events
       Command CLSID
	   A generic event, triggered by a command widget when the user
	   activates it. It can	also be	called by other	means.

	   CLSID is the	widget identifier.

       CommandChange
	   Called when "commands" property changes or "commands_enable"	method
	   is invoked.

       PanelChange
	   Triggered when a panel is created or	destroyed by the user.

       ToolbarChange
	   Triggered when a toolbar is created,	shown, hidden, or destroyed
	   by the user.

Prima::DockManager::S::SpeedButton
       The package simplifies creation of "Prima::SpeedButton" command
       widgets.

   Methods
       class IMAGE, CLSID, %PROFILE
	   Builds a hash with parameters, ready	to feed
	   "Prima::DockManager::register_tool" for registering a
	   "Prima::SpeedButton"	class instance with PROFILE parameters.

	   IMAGE is a path to a	image file, loaded and stored in the
	   registration	hash.  IMAGE provides an extended syntax for
	   indicating a	frame index, if	the image file is multiframed: the
	   frame index is appended to the path name with ":" character prefix.

	   CLSID scalar	is not used; it	is returned so the method result can
	   directly be passed into "register_tool" method.

	   Returns two scalars:	CLSID and the registration hash.

	   Example:

		   $dock_manager-> register_tool(
			   Prima::DockManager::S::SpeedButton::class( "myicon.gif:2",
			   q(CLSID::Logo), hint	=> 'Logo image'	));

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

SEE ALSO
       Prima, Prima::Widget, Prima::Docks, examples/dock.pl

perl v5.24.1			  2017-02-28		 Prima::DockManager(3)

NAME | DESCRIPTION | Prima::DockManager::Toolbar | Prima::DockManager::ToolbarDocker | Prima::DockManager::Panelbar | Prima::DockManager | Prima::DockManager::S::SpeedButton | AUTHOR | SEE ALSO

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

home | help