Ubuntu Manpage: Prima::DockManager - advanced dockable widgets

Provided by: libprima-perl_1.28-1.2_amd64

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