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.

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.

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:

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.

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.

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.

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.

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.

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.

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:

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.