1Prima::DockManager(3) User Contributed Perl DocumentationPrima::DockManager(3)
2
6 Prima::DockManager - advanced dockable widgets
7
9 "Prima::DockManager" contains classes that implement additional
10 functionality within the dockable widgets paradigm.
11 The module introduces two new dockable widget classes:
13 "Prima::DockManager::Panelbar", a general purpose dockable container
14 for variable-sized widgets; and "Prima::DockManager::Toolbar", a
15 dockable container for fixed-size command widgets, mostly push buttons.
16 The command widgets, nested in a toolbar, can also be docked.
17 "Prima::DockManager" class is an application-oriented class in a way
19 that ( mostly ) the only instance of it is needed in the program. It is
20 derived from "Prima::Component" and therefore is never visualized. The
21 class instance is stored in "instance" property of all module classes
22 to serve as a docking hierarchy root. Through the document, instance
23 term is referred to "Prima::DockManager" class instance.
24 The module by itself is not enough to make a docking-aware application
26 work effectively. The reader is urged to look at examples/dock.pl
27 example code, which demonstrates the usage and capabilities of the
28 module.
29
31 A toolbar widget class. The toolbar has a dual nature; it can dock and
32 accept docking widgets simultaneously. In the scope of
33 "Prima::DockManager", the toolbar hosts command widget, mostly push
34 buttons.
35 The toolbar consists of two widgets. The external dockable widget is
37 implemented in "Prima::DockManager::Toolbar", and the internal dock in
38 "Prima::DockManager::ToolbarDocker" classes.
39 Properties
41 autoClose BOOLEAN
42 Selects the behavior of a toolbar when all of its command widgets
43 are undocked. If 1, the toolbar is automatically destroyed. If 0 it
44 calls visible(0).
45 childDocker WIDGET
47 Pointer to "Prima::DockManager::ToolbarDocker" instance.
48 See also "Prima::DockManager::ToolbarDocker::parentDocker".
50 instance INSTANCE
52 "Prima::DockManager" instance, the docking hierarchy root.
53
55 Internal class, implements a dock widget for command widgets, while
56 serves as a client in a dockable toolbar, which is a
57 "Prima::LinearDockerShuttle" descendant. When its size is changed due
58 an eventual rearrange of its docked widgets, also resizes the toolbar.
59 Properties
61 instance INSTANCE
62 "Prima::DockManager" instance, the docking hierarchy root.
63 parentDocker WIDGET
65 Pointer to "Prima::DockManager::Toolbar" instance. When in the
66 docked state, "parentDocker" value is always equals to "owner".
67 See also "Prima::DockManager::Toolbar::childDocker".
69 Methods
71 get_extent
72 Calculates the minimal rectangle that encloses all docked widgets
73 and returns its extensions.
74 update_size
76 Called when size is changed to resizes the owner widget. If it is
77 in the docked state, the size change might result in change of
78 position or docking state.
79
81 The class is derived from "Prima::LinearDockerShuttle", and is
82 different only in that "instance" property is introduced, and the
83 external shuttle can be resized interactively.
84 The class is to be used as a simple host to sizeable widgets. The user
86 can dispose of the panel bar by clicking close button on the external
87 shuttle.
88 Properties
90 instance INSTANCE
91 "Prima::DockManager" instance, the docking hierarchy root.
92
94 A binder class, contains set of functions that groups toolbars, panels,
95 and command widgets together under the docking hierarchy.
96 The manager servers several purposes. First, it is a command state
98 holder: the command widgets, mostly buttons, usually are in enabled or
99 disabled state in different life stages of a program. The manager
100 maintains the enabled/disabled state by assigning each command an
101 unique scalar value ( farther and in the code referred as CLSID ). The
102 toolbars can be created with set of command widgets, referred via these
103 CLSIDs. The same is valid for the panels - although they do not host
104 command widgets, the widgets that they do host can also be created
105 indirectly via CLSID identifier. In addition to CLSID, the commands
106 can be grouped by sections. Both CLSID and group descriptor scalars
107 are defined by the programmer.
108 Second, "create_manager" method presents a standard configuration
110 widget, that allows rearranging of normally non-dockable command
111 widgets, by presenting a full set of available commands to the user as
112 icons. Dragging the icons to toolbars, dock widgets or merely outside
113 the configuration widget automatically creates the corresponding
114 command widget. The notable moment here is that the command widgets
115 are not required to know anything about dragging and docking; any
116 "Prima::Widget" descendant can be used as a command widget.
117 Third, it helps maintaining the toolbars and panels visibility when the
119 main window is hidden or restored. "windowState" method hides or shows
120 the toolbars and panels effectively.
121 Fourth, it serves as a docking hierarchy root. All docking sessions
123 begin from "Prima::DockManager" object, which although does not provide
124 docking capabilities itself ( it is "Prima::Component" descendant ),
125 redirects the docking requests to the lower-level dock widgets.
126 Fifth, it provides number of helper methods and notifications, and
128 enforces use or "fingerprint" property by all dockable widgets. This
129 property has default value of 0xFFFF ( defined in "Prima::Docks" ).
130 The module contains the fingerprint "dmfp::XXX" constants with value
131 greater than this, so the toolbars and panels are not docked to a dock
132 widget with the default configuration. The base constant set is:
133 fdmp::Tools ( 0x0F000) - dock the command widgets
135 fdmp::Toolbar ( 0x10000) - dock the toolbars
136 fdmp::LaunchPad ( 0x20000) - allows widgets recycling
137 All this functionality is demonstrated in examples/dock.pl example.
139 Properties
141 commands HASH
142 A hash of boolean values, with keys of CLSID scalars. If value is
143 1, the command is available. If 0, the command is disabled. Changes
144 to this property are reflected in the visible command widgets,
145 which are enabled or disabled immediately. Also, "CommandChange"
146 notification is triggered.
147 fingerprint INTEGER
149 The property is read-only, and always returns 0xFFFFFFFF, to allow
150 landing for all dockable widgets. In case when a finer granulation
151 is needed, the default "fingerprint" values of toolbars and panels
152 can be reset.
153 interactiveDrag BOOLEAN
155 If 1, the command widgets can be interactively dragged, created and
156 destroyed. This property is usually operated together with
157 "create_manager" widget. If 0, the command widgets cannot be
158 dragged.
159 Default value: 0
161 Methods
163 activate
164 Brings to front all toolbars and panels. To be used inside a
165 callback code of a main window, that has the toolbars and panels
166 attached to:
167 onActivate => sub { $dock_manager-> activate }
169 auto_toolbar_name
171 Returns an unique name for an automatically created toolbar, like
172 "Toolbar1", "Toolbar2" etc.
173 commands_enable BOOLEAN, @CLSIDs
175 Enabled or disables commands from CLSIDs array. The changes are
176 reflected in the visible command widgets, which are enabled or
177 disabled immediately. Also, "CommandChange" notification is
178 triggered.
179 create_manager OWNER, %PROFILE
181 Inserts two widgets into OWNER with PROFILE parameters: a listbox
182 with command section groups, displayed as items, that usually
183 correspond to the predefined toolbar names, and a notebook that
184 displays the command icons. The notebook pages are interactively
185 selected by the listbox navigation.
186 The icons, dragged from the notebook, behave as dockable widgets:
188 they can be landed upon a toolbar, or any other dock widget, given
189 it matches the "fingerprint" ( by default
190 "dmfp::LaunchPad|dmfp::Toolbar|dmfp::Tools"). "dmfp::LaunchPad"
191 constant allows the recycling; if a widget is dragged back onto the
192 notebook, it is destroyed.
193 Returns two widgets, the listbox and the notebook.
195 PROFILE recognizes the following keys:
197 origin X, Y
199 Position where the widgets are to be inserted. Default value
200 is 0,0.
201 size X, Y
203 Size of the widget insertion area. By default the widgets
204 occupy all OWNER interior.
205 listboxProfile PROFILE
207 Custom parameters, passed to the listbox.
208 dockerProfile PROFILE
210 Custom parameteres, passed to the notebook.
211 create_panel CLSID, %PROFILE
213 Creates a dockable panel of a previously registered CLSID by
214 "register_panel". PROFILE recognizes the following keys:
215 profile HASH
217 Hash of parameters, passed to "create()" of the panel widget
218 class. Before passing it is merged with the set of parameters,
219 registered by "register_panel". The "profile" hash takes the
220 precedence.
221 dockerProfile HASH
223 Constains extra options, passed to
224 "Prima::DockManager::Panelbar" widget. Before the usage it is
225 merged with the set of parameters, registered by
226 "register_panel".
227 NB: The "dock" key here contains a reference to a desired dock
229 widget. If "dock" set to "undef", the panel is created in the
230 non-docked state.
231 Example:
233 $dock_manager-> create_panel( $CLSID,
235 dockerProfile => { dock => $main_window }},
236 profile => { backColor => cl::Green });
237 create_tool OWNER, CLSID, X1, Y1, X2, Y2
239 Inserts a command widget, previously registered with CLSID by
240 "register_tool", into OWNER widget with X1 - Y2 coordinates. For
241 automatic maintenance of enable/disable state of command widgets
242 OWNER is expected to be a toolbar. If it is not, the maintenance
243 must be performed separately, for example, by "CommandChange"
244 event.
245 create_toolbar %PROFILE
247 Creates a new toolbar of "Prima::DockManager::Toolbar" class. The
248 following PROFILE options are recognized:
249 autoClose BOOLEAN
251 Sets "autoClose" property of the toolbar.
252 Default value is 1 if "name" options is set, 0 otherwise.
254 dock DOCK
256 Contain a reference to a desired DOCK widget. If "undef", the
257 toolbar is created in the non-docked state.
258 dockerProfile HASH
260 Parameters passed to "Prima::DockManager::Toolbar" as creation
261 properties.
262 NB: The "dock" key here contains a reference to a desired dock
264 widget. If "dock" set to "undef", the panel is created in the
265 non-docked state.
266 rect X1, Y1, X2, Y2
268 Selects rectangle of the "Prima::DockManager::ToolbarDocker"
269 instance in the dock widget ( if docked ) or the screen ( if
270 non-docked ) coordinates.
271 toolbarProfile HASH
273 Parameters passed to "Prima::DockManager::ToolbarDocker" as
274 creation properties.
275 vertical BOOLEAN
277 Sets "vertical" property of the toolbar.
278 visible BOOLEAN
280 Selects visibility state of the toolbar.
281 get_class CLSID
283 Returns class record hash, registered under CLSID, or "undef" if
284 the class is not registered. The hash format contains the following
285 keys:
286 class STRING
288 Widget class
289 profile HASH
291 Creation parameters passed to "create" when the widget is
292 created.
293 tool BOOLEAN
295 If 1, the class belongs to a control widget. If 0, the class
296 represents a panel client widget.
297 lastUsedDock DOCK
299 Saved value of the last used dock widget
300 lastUsedRect X1, Y1, X2, Y2
302 Saved coordinates of the widget
303 panel_by_id CLSID
305 Return reference to a panel widget represented by CLSID scalar, or
306 "undef" if none found.
307 panel_menuitems CALLBACK
309 A helper function; maps all panel names into a structure, ready to
310 feed into "Prima::AbstractMenu::items" property ( see Prima::Menu
311 ). The action member of the menu item record is set to CALLBACK
312 scalar.
313 panel_visible CLSID, BOOLEAN
315 Sets the visibility of a panel, referred by CLSID scalar. If
316 VISIBLE is 0, a panel is destroyed; if 1, new panel instance is
317 created.
318 panels
320 Returns all visible panel widgets in an array.
321 predefined_panels CLSID, DOCK, [ CLSID, DOCK, ... ]
323 Accepts pairs of scalars, where each first item is a panel CLSID
324 and second is the default dock widget. Checks for panel visibility,
325 and creates the panels that are not visible.
326 The method is useful in program startup, when some panels have to
328 be visible from the beginning.
329 predefined_toolbars @PROFILES
331 Accepts array of hashes, where each array item describes a toolbar
332 and a default set of command widgets. Checks for toolbar
333 visibility, and creates the toolbars that are not visible.
334 The method recognizes the following PROFILES options:
336 dock DOCK
338 The default dock widget.
339 list ARRAY
341 Array of CLSIDs corresponding to the command widgets to be
342 inserted into the toolbar.
343 name STRING
345 Selects toolbar name.
346 origin X, Y
348 Selects the toolbar position relative to the dock ( if "dock"
349 is specified ) or to the screen ( if "dock" is not specified ).
350 The method is useful in program startup, when some panels have to
352 be visible from the beginning.
353 register_panel CLSID, PROFILE
355 Registers a panel client class and set of parameters to be
356 associated with CLSID scalar. PROFILE must contain the following
357 keys:
358 class STRING
360 Client widget class
361 text STRING
363 String, displayed in the panel title bar
364 dockerProfile HASH
366 Hash of parameters, passed to "Prima::DockManager::Panelbar".
367 profile
369 Hash of parameters, passed to the client widget.
370 register_tool CLSID, PROFILE
372 Registers a control widget class and set of parameters to be
373 associated with CLSID scalar. PROFILE must be set the following
374 keys:
375 class STRING
377 Client widget class
378 profile HASH
380 Hash of parameters, passed to the control widget.
381 toolbar_by_name NAME
383 Returns a pointer to a toolbar of NAME, or "undef" if none found.
384 toolbar_menuitems CALLBACK
386 A helper function; maps all toolbar names into a structure, ready
387 to feed into "Prima::AbstractMenu::items" property ( see
388 Prima::Menu ). The action member of the menu item record is set to
389 CALLBACK scalar.
390 toolbar_visible TOOLBAR, BOOLEAN
392 Sets the visibility of a TOOLBAR. If VISIBLE is 0, the toolbar is
393 hidden; if 1, it is shown.
394 toolbars
396 Returns all toolbar widgets in an array.
397 windowState INTEGER
399 Mimics interface of "Prima::Window::windowState", and maintains
400 visibility of toolbars and panels. If the parameter is
401 "ws::Minimized", the toolbars and panels are hidden. On any other
402 parameter these are shown.
403 To be used inside a callback code of a main window, that has the
405 toolbars and panels attached to:
406 onWindowState => sub { $dock_manager-> windowState( $_[1] ) }
408 Events
410 Command CLSID
411 A generic event, triggered by a command widget when the user
412 activates it. It can also be called by other means.
413 CLSID is the widget identifier.
415 CommandChange
417 Called when "commands" property changes or "commands_enable" method
418 is invoked.
419 PanelChange
421 Triggered when a panel is created or destroyed by the user.
422 ToolbarChange
424 Triggered when a toolbar is created, shown, hidden, or destroyed
425 by the user.
426
428 The package simplifies creation of "Prima::SpeedButton" command
429 widgets.
430 Methods
432 class IMAGE, CLSID, %PROFILE
433 Builds a hash with parameters, ready to feed
434 "Prima::DockManager::register_tool" for registering a
435 "Prima::SpeedButton" class instance with PROFILE parameters.
436 IMAGE is a path to a image file, loaded and stored in the
438 registration hash. IMAGE provides an extended syntax for
439 indicating a frame index, if the image file is multiframed: the
440 frame index is appended to the path name with ":" character prefix.
441 CLSID scalar is not used; it is returned so the method result can
443 directly be passed into "register_tool" method.
444 Returns two scalars: CLSID and the registration hash.
446 Example:
448 $dock_manager-> register_tool(
450 Prima::DockManager::S::SpeedButton::class( "myicon.gif:2",
451 q(CLSID::Logo), hint => 'Logo image' ));
452
454 Dmitry Karasik, <dmitry@karasik.eu.org>.
455
457 Prima, Prima::Widget, Prima::Docks, examples/dock.pl
458perl v5.36.0 2022-07-22 Prima::DockManager(3)