1Prima::DockManager(3) User Contributed Perl DocumentationPrima::DockManager(3)
2
3
4

NAME

6       Prima::DockManager - advanced dockable widgets
7

DESCRIPTION

9       "Prima::DockManager" contains classes that implement additional
10       functionality within the dockable widgets paradigm.
11
12       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
18       "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
25       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

Prima::DockManager::Toolbar

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
36       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
40   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
46       childDocker WIDGET
47           Pointer to "Prima::DockManager::ToolbarDocker" instance.
48
49           See also "Prima::DockManager::ToolbarDocker::parentDocker".
50
51       instance INSTANCE
52           "Prima::DockManager" instance, the docking hierarchy root.
53

Prima::DockManager::ToolbarDocker

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
60   Properties
61       instance INSTANCE
62           "Prima::DockManager" instance, the docking hierarchy root.
63
64       parentDocker WIDGET
65           Pointer to "Prima::DockManager::Toolbar" instance. When in the
66           docked state, "parentDocker" value is always equals to "owner".
67
68           See also "Prima::DockManager::Toolbar::childDocker".
69
70   Methods
71       get_extent
72           Calculates the minimal rectangle that encloses all docked widgets
73           and returns its extensions.
74
75       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

Prima::DockManager::Panelbar

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
85       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
89   Properties
90       instance INSTANCE
91           "Prima::DockManager" instance, the docking hierarchy root.
92

Prima::DockManager

94       A binder class, contains set of functions that groups toolbars, panels,
95       and command widgets together under the docking hierarchy.
96
97       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
109       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
118       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
122       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
127       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
134               fdmp::Tools      ( 0x0F000) - dock the command widgets
135               fdmp::Toolbar    ( 0x10000) - dock the toolbars
136               fdmp::LaunchPad  ( 0x20000) - allows widgets recycling
137
138       All this functionality is demonstrated in examples/dock.pl example.
139
140   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
148       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
154       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
160           Default value: 0
161
162   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
168                   onActivate => sub { $dock_manager-> activate }
169
170       auto_toolbar_name
171           Returns an unique name for an automatically created toolbar, like
172           "Toolbar1", "Toolbar2" etc.
173
174       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
180       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
187           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
194           Returns two widgets, the listbox and the notebook.
195
196           PROFILE recognizes the following keys:
197
198           origin X, Y
199               Position where the widgets are to be inserted.  Default value
200               is 0,0.
201
202           size X, Y
203               Size of the widget insertion area. By default the widgets
204               occupy all OWNER interior.
205
206           listboxProfile PROFILE
207               Custom parameters, passed to the listbox.
208
209           dockerProfile PROFILE
210               Custom parameteres, passed to the notebook.
211
212       create_panel CLSID, %PROFILE
213           Creates a dockable panel of a previously registered CLSID by
214           "register_panel". PROFILE recognizes the following keys:
215
216           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
222           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
228               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
232           Example:
233
234                   $dock_manager-> create_panel( $CLSID,
235                           dockerProfile => { dock => $main_window }},
236                           profile       => { backColor => cl::Green });
237
238       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
246       create_toolbar %PROFILE
247           Creates a new toolbar of "Prima::DockManager::Toolbar" class.  The
248           following PROFILE options are recognized:
249
250           autoClose BOOLEAN
251               Sets "autoClose" property of the toolbar.
252
253               Default value is 1 if "name" options is set, 0 otherwise.
254
255           dock DOCK
256               Contain a reference to a desired DOCK widget. If "undef", the
257               toolbar is created in the non-docked state.
258
259           dockerProfile HASH
260               Parameters passed to "Prima::DockManager::Toolbar" as creation
261               properties.
262
263               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
267           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
272           toolbarProfile HASH
273               Parameters passed to "Prima::DockManager::ToolbarDocker" as
274               creation properties.
275
276           vertical BOOLEAN
277               Sets "vertical" property of the toolbar.
278
279           visible BOOLEAN
280               Selects visibility state of the toolbar.
281
282       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
287           class STRING
288               Widget class
289
290           profile HASH
291               Creation parameters passed to "create" when the widget is
292               created.
293
294           tool BOOLEAN
295               If 1, the class belongs to a control widget. If 0, the class
296               represents a panel client widget.
297
298           lastUsedDock DOCK
299               Saved value of the last used dock widget
300
301           lastUsedRect X1, Y1, X2, Y2
302               Saved coordinates of the widget
303
304       panel_by_id CLSID
305           Return reference to a panel widget represented by CLSID scalar, or
306           "undef" if none found.
307
308       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
314       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
319       panels
320           Returns all visible panel widgets in an array.
321
322       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
327           The method is useful in program startup, when some panels have to
328           be visible from the beginning.
329
330       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
335           The method recognizes the following PROFILES options:
336
337           dock DOCK
338               The default dock widget.
339
340           list ARRAY
341               Array of CLSIDs corresponding to the command widgets to be
342               inserted into the toolbar.
343
344           name STRING
345               Selects toolbar name.
346
347           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
351           The method is useful in program startup, when some panels have to
352           be visible from the beginning.
353
354       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
359           class STRING
360               Client widget class
361
362           text STRING
363               String, displayed in the panel title bar
364
365           dockerProfile HASH
366               Hash of parameters, passed to "Prima::DockManager::Panelbar".
367
368           profile
369               Hash of parameters, passed to the client widget.
370
371       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
376           class STRING
377               Client widget class
378
379           profile HASH
380               Hash of parameters, passed to the control widget.
381
382       toolbar_by_name NAME
383           Returns a pointer to a toolbar of NAME, or "undef" if none found.
384
385       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
391       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
395       toolbars
396           Returns all toolbar widgets in an array.
397
398       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
404           To be used inside a callback code of a main window, that has the
405           toolbars and panels attached to:
406
407                   onWindowState => sub { $dock_manager-> windowState( $_[1] ) }
408
409   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
414           CLSID is the widget identifier.
415
416       CommandChange
417           Called when "commands" property changes or "commands_enable" method
418           is invoked.
419
420       PanelChange
421           Triggered when a panel is created or destroyed by the user.
422
423       ToolbarChange
424           Triggered when a toolbar is created, shown, hidden, or destroyed
425           by the user.
426

Prima::DockManager::S::SpeedButton

428       The package simplifies creation of "Prima::SpeedButton" command
429       widgets.
430
431   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
437           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
442           CLSID scalar is not used; it is returned so the method result can
443           directly be passed into "register_tool" method.
444
445           Returns two scalars: CLSID and the registration hash.
446
447           Example:
448
449                   $dock_manager-> register_tool(
450                           Prima::DockManager::S::SpeedButton::class( "myicon.gif:2",
451                           q(CLSID::Logo), hint => 'Logo image' ));
452

AUTHOR

454       Dmitry Karasik, <dmitry@karasik.eu.org>.
455

SEE ALSO

457       Prima, Prima::Widget, Prima::Docks, examples/dock.pl
458
459
460
461perl v5.34.0                      2021-07-22             Prima::DockManager(3)
Impressum