|
Prima::DockManager - advanced dockable widgets |
Prima::DockManager - advanced dockable widgets
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.
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.
visible(0).
Prima::DockManager::ToolbarDocker instance.
See also Prima::DockManager::ToolbarDocker::parentDocker.
Prima::DockManager instance, the docking hierarchy root.
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.
Prima::DockManager instance, the docking hierarchy root.
Prima::DockManager::Toolbar instance. When in
the docked state, parentDocker value is always equals to owner.
See also Prima::DockManager::Toolbar::childDocker.
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.
Prima::DockManager instance, the docking hierarchy root.
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.
CommandChange notification is triggered.
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.
create_manager widget. If 0, the command widgets
cannot be dragged.
Default value: 0
onActivate => sub { $dock_manager-> activate }
Toolbar1, Toolbar2 etc.
CommandChange notification is triggered.
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:
register_panel. PROFILE recognizes the following keys:
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.
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 });
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.
Prima::DockManager::Toolbar class.
The following PROFILE options are recognized:
autoClose property of the toolbar.
Default value is 1 if name options is set, 0 otherwise.
undef,
the toolbar is created in the non-docked state.
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.
Prima::DockManager::ToolbarDocker instance
in the dock widget ( if docked ) or the screen ( if non-docked ) coordinates.
Prima::DockManager::ToolbarDocker as
creation properties.
vertical property of the toolbar.
undef
if the class is not registered. The hash format contains
the following keys:
create when the widget is created.
undef if none found.
Prima::AbstractMenu::items property ( see the Prima::Menu manpage ).
The action member of the menu item record is set to CALLBACK scalar.
The method is useful in program startup, when some panels have to be visible from the beginning.
The method recognizes the following PROFILES options:
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.
Prima::DockManager::Panelbar.
undef if none found.
Prima::AbstractMenu::items property ( see the Prima::Menu manpage ).
The action member of the menu item record is set to CALLBACK scalar.
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] ) }
CLSID is the widget identifier.
commands property changes or commands_enable method is invoked.
The package simplifies creation of Prima::SpeedButton command widgets.
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' ));
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, the Prima::Widget manpage, the Prima::Docks manpage, examples/dock.pl
|
Prima::DockManager - advanced dockable widgets |