Prima::DockManager(3)

💖 Prima::DockManager 💖

okay so bestie, this is the Prima::DockManager(3) page from the User Contributed Perl Documentation 💅 and it is literally all about advanced dockable widgets. it's giving main-character GUI energy, no cap.

🌸 NAME 🌸

Prima::DockManager — advanced dockable widgets. periodt.

✨ DESCRIPTION ✨

Prima::DockManager contains classes that implement additional functionality in the dockable widgets paradigm. 🫶

The module introduces two new dockable widget classes:

• Prima::DockManager::Panelbar — a general-purpose dockable container for variable-sized widgets.
• 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. 🎀

The Prima::DockManager class is application-oriented in a way that a single of it is needed. It is derived from Prima::Component and therefore is never visualized. The class instance is stored in the instance property in all module classes to serve as a docking hierarchy root. Through the document, the instance term means the Prima::DockManager class instance. 👑

🫶 real talk: the module by itself is not enough to make a docking-aware application work effectively. The reader is urged to look at the 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 both dock itself and accept dockable widgets. As a dock, toolbars can host command widgets, 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 the toolbar when all of its command widgets are undocked. If 1 (default), the toolbar is automatically destroyed. If 0 it calls visible(0). 😭
• childDocker WIDGET — pointer to the Prima::DockManager::ToolbarDocker instance.

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

• instance INSTANCE — Prima::DockManager instance, the docking hierarchy root. 👑

---

🦋 Prima::DockManager::ToolbarDocker 🦋

An internal class, implements the dock widget for command widgets, and a client in a dockable toolbar, a Prima::LinearDockerShuttle descendant. When its size is changed due to an eventual rearrangement of its docked widgets, also resizes the toolbar. 🎀

💜 Properties 💜

• instance INSTANCE — the Prima::DockManager instance, the docking hierarchy root.
• parentDocker WIDGET — pointer to a Prima::DockManager::Toolbar instance. When in the docked state, the parentDocker value is always equal 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 the size is changed to resize the owner widget. If the toolbar is docked, the change might result in a change of its position or docking state.

---

🎀 Prima::DockManager::Panelbar 🎀

The class is derived from Prima::LinearDockerShuttle, and is different only in that the 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 the close button on the external shuttle. 💅

⭐ Properties ⭐

• instance INSTANCE — the Prima::DockManager instance, the docking hierarchy root.

---

👑 Prima::DockManager 👑

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

The manager serves several purposes.

First, it is a command state holder: the command widgets, mostly buttons, usually are in an enabled or disabled state in different life stages of a program. The manager maintains the enabled/disabled state by assigning each command a unique scalar value, or a CLSID. The toolbars can be created using a set of command widgets, using 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 CLSIDs, the commands can be grouped by sections. Both CLSID and group descriptor scalars are defined by the programmer. 🫶

Second, the create_manager method presents the standard launchpad interface that allows the 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 maintain the toolbars' and panels' visibility when the main window is hidden or restored. The windowState method hides or shows the toolbars and panels effectively. 🎀

Fourth, it serves as a docking hierarchy root. All docking sessions start their protocol interactions at a Prima::DockManager object, which although does not provide docking capabilities itself (it is a Prima::Component descendant), redirects the docking requests to the children dock widgets. 👑

Finally, it provides several helper methods and notifications and enforces the use of the fingerprint property by all dockable widgets. The module defines the following fingerprint dmfp::XXX constants:

• 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, where if the value is 1, the command is available and is disabled otherwise. Changes to this property are reflected in the visible command widgets, which are enabled or disabled immediately. Also, the CommandChange notification is triggered. 🔥
• fingerprint INTEGER — the property is read-only, and always returns 0xFFFFFFFF, to allow landing to all dockable widgets. In case 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 the create_manager launchpad 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 a unique name for an automatically created toolbar, like "Toolbar1", "Toolbar2" etc. 🌸
• commands_enable BOOLEAN, @CLSIDs — enables or disables commands from CLSIDs array. The changes are reflected in the visible command widgets, which are enabled or disabled immediately. Also, the CommandChange notification is triggered. 💅
• create_manager OWNER, %PROFILE — inserts two widgets into OWNER with PROFILE parameters: a list box 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 can be interactively selected by the list box navigation.

The icons dragged from the notebook, behave as dockable widgets: they can be landed on 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 the two widgets created, the list box and the notebook.

PROFILE recognizes the following keys:

• origin X, Y — position where the widgets are to be inserted. The default value is 0,0.
• size X, Y — size of the widget insertion area. By default, the widgets occupy all OWNER interiors.
• listboxProfile PROFILE — custom parameters passed to the list box.
• dockerProfile PROFILE — custom parameters passed to the notebook.

• create_panel CLSID, %PROFILE — spawns a dockable panel from a previously registered CLSID. PROFILE recognizes the following keys:
  • profile HASH — a hash of parameters passed to the new() method of the panel widget class. Before passing it is merged with the set of parameters registered by register_panel. The profile hash takes precedence.
  • dockerProfile HASH — contains extra options passed to the Prima::DockManager::Panelbar widget. Before passing it is merged with the set of parameters registered by register_panel.

Note: The dock key contains a reference to the desired dock widget. If dock is 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 a CLSID by register_tool, into OWNER widget at X1 - Y2 coordinates. For automatic maintenance of enabled/disabled states of command widgets, OWNER is expected to be a toolbar. If it is not, the maintenance must be performed separately, for example, by reacting to the CommandChange event. 🎀
• create_toolbar %PROFILE — creates a new toolbar of the Prima::DockManager::Toolbar class. The following PROFILE options are recognized:
  • autoClose BOOLEAN — manages the autoClose property of the toolbar.

The default value is 1 if the name option is set, and 0 otherwise.

• dock DOCK — contains a reference to the 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.

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

• rect X1, Y1, X2, Y2 — manages the geometry of the Prima::DockManager::ToolbarDocker instance in the dock widget coordinates if it’s docked, or in the screen coordinates if it’s non-docked. 💅
• toolbarProfile HASH — parameters passed to Prima::DockManager::ToolbarDocker as properties. ✨
• vertical BOOLEAN — sets the vertical property of the toolbar. 🦋
• visible BOOLEAN — selects the visibility state of the toolbar. 👑
• get_class CLSID — returns a class record hash registered under a CLSID, or undef if the class is not registered. The hash format contains these keys:
  • class STRING — widget class.
  • profile HASH — creation parameters passed to new when the corresponding widget is instantiated.
  • 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 — returns a reference to the panel widget represented by the CLSID scalar, or undef if none is found. 🫶
• panel_menuitems CALLBACK — a helper function; maps all panel names into a structure ready to feed into the Prima::AbstractMenu::items property (see Prima::Menu). The action member of the menu item record is set to the CALLBACK scalar. 🎀
• panel_visible CLSID, BOOLEAN — sets the visibility of a panel referred to by the CLSID scalar. If VISIBLE is 0, the panel is destroyed; if 1, a 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 the 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 an 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 these PROFILES options:
  • dock DOCK — the default dock widget.
  • list ARRAY — an array of CLSIDs corresponding to the command widgets to be inserted into the toolbar.
  • name STRING — selects the 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 a CLSID scalar. PROFILE must contain these keys:
  • class STRING — client widget class.
  • text STRING — a string of text displayed in the panel title bar.
  • dockerProfile HASH — a hash of parameters passed to Prima::DockManager::Panelbar.
  • profile — a 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 a CLSID scalar. PROFILE must contain these keys:
  • class STRING — client widget class.
  • profile HASH — a hash of parameters passed to the control widget.
• toolbar_by_name NAME — returns a reference to the toolbar of NAME, or undef if none is found. 🔥
• toolbar_menuitems CALLBACK — a helper function; maps all toolbar names into a structure ready to feed into the Prima::AbstractMenu::items property (see Prima::Menu). The action member of the menu item record is set to the 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 the 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 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 the commands property changes or the 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, gets hidden, or destroyed by the user. 🧨

🌟 Prima::DockManager::S::SpeedButton 🌟

The package simplifies the creation of Prima::SpeedButton command widgets. 💅

✨ Methods ✨

• class IMAGE, CLSID, %PROFILE — builds a hash with parameters ready to feed to Prima::DockManager::register_tool for registering a combination of the Prima::SpeedButton class and the PROFILE parameters. IMAGE is the path to an image file, loaded and stored in the registration hash. IMAGE provides an extended syntax for selecting the frame index if the image file is multiframed: the frame index is appended to the path name with the : character prefix. The CLSID scalar is not used but is returned so the method result can directly be passed into the 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 — go peek, bestie, iykyk. ✨

💖 this page came from perl v5.42.0, dated 2024-08-20, and it’s Prima::DockManager(3) — iconic, periodt. 💖