Man Linux: Main Page and Category List

NAME

       Prima::DockManager - advanced dockable widgets

DESCRIPTION

       "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.

Prima::DockManager::Toolbar

       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.

   Properties
       autoClose BOOLEAN
           Selects the behavior of a toolbar when all of its command widgets
           are undocked. If 1, the toolbar is automatically destroyed. If 0 it
           calls visible(0).

       childDocker WIDGET
           Pointer to "Prima::DockManager::ToolbarDocker" instance.

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

       instance INSTANCE
           "Prima::DockManager" instance, the docking hierarchy root.

Prima::DockManager::ToolbarDocker

       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.

   Properties
       instance INSTANCE
           "Prima::DockManager" instance, the docking hierarchy root.

       parentDocker WIDGET
           Pointer to "Prima::DockManager::Toolbar" instance. When in the
           docked state, "parentDocker" value is always equals 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 size is changed to resizes the owner widget. If it is
           in the docked state, the size change might result in change of
           position or docking state.

Prima::DockManager::Panelbar

       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.

   Properties
       instance INSTANCE
           "Prima::DockManager" instance, the docking hierarchy root.

Prima::DockManager

       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.

   Properties
       commands HASH
           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.

       fingerprint INTEGER
           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.

       interactiveDrag BOOLEAN
           If 1, the command widgets can be interactively dragged, created and
           destroyed. This property is usually operated together with
           "create_manager" 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 an unique name for an automatically created toolbar, like
           "Toolbar1", "Toolbar2" etc.

       commands_enable BOOLEAN, @CLSIDs
           Enabled or disables commands from CLSIDs array.  The changes are
           reflected in the visible command widgets, which are enabled or
           disabled immediately.  Also, "CommandChange" notification is
           triggered.

       create_manager OWNER, %PROFILE
           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.

           Returns two widgets, the listbox and the notebook.

           PROFILE recognizes the following keys:

           origin X, Y
               Position where the widgets are to be inserted.  Default value
               is 0,0.

           size X, Y
               Size of the widget insertion area. By default the widgets
               occupy all OWNER interior.

           listboxProfile PROFILE
               Custom parameters, passed to the listbox.

           dockerProfile PROFILE
               Custom parameteres, passed to the notebook.

       create_panel CLSID, %PROFILE
           Creates a dockable panel of a previously registered CLSID by
           "register_panel". PROFILE recognizes the following keys:

           profile HASH
               Hash of parameters, passed to "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.

           dockerProfile HASH
               Constains extra options, passed to
               "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 });

       create_tool OWNER, CLSID, X1, Y1, X2, Y2
           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.

       create_toolbar %PROFILE
           Creates a new toolbar of "Prima::DockManager::Toolbar" class.  The
           following PROFILE options are recognized:

           autoClose BOOLEAN
               Sets "autoClose" property of the toolbar.

               Default value is 1 if "name" options is set, 0 otherwise.

           dock DOCK
               Contain a reference to a 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.

               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.

           rect X1, Y1, X2, Y2
               Selects rectangle of the "Prima::DockManager::ToolbarDocker"
               instance in the dock widget ( if docked ) or the screen ( if
               non-docked ) coordinates.

           toolbarProfile HASH
               Parameters passed to "Prima::DockManager::ToolbarDocker" as
               creation properties.

           vertical BOOLEAN
               Sets "vertical" property of the toolbar.

           visible BOOLEAN
               Selects visibility state of the toolbar.

       get_class CLSID
           Returns class record hash, registered under CLSID, or "undef" if
           the class is not registered. The hash format contains the following
           keys:

           class STRING
               Widget class

           profile HASH
               Creation parameters passed to "create" when the widget is
               created.

           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
           Return reference to a panel widget represented by CLSID scalar, or
           "undef" if none found.

       panel_menuitems CALLBACK
           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.

       panel_visible CLSID, BOOLEAN
           Sets the visibility of a panel, referred by CLSID scalar.  If
           VISIBLE is 0, a panel is destroyed; if 1, 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 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 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 the following PROFILES options:

           dock DOCK
               The default dock widget.

           list ARRAY
               Array of CLSIDs corresponding to the command widgets to be
               inserted into the toolbar.

           name STRING
               Selects 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 CLSID scalar. PROFILE must contain the following
           keys:

           class STRING
               Client widget class

           text STRING
               String, displayed in the panel title bar

           dockerProfile HASH
               Hash of parameters, passed to "Prima::DockManager::Panelbar".

           profile
               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 CLSID scalar. PROFILE must be set the following
           keys:

           class STRING
               Client widget class

           profile HASH
               Hash of parameters, passed to the control widget.

       toolbar_by_name NAME
           Returns a pointer to a toolbar of NAME, or "undef" if none found.

       toolbar_menuitems CALLBACK
           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.

       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 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:

                   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 "commands" property changes or "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, hidden, or destroyed
           by the user.

Prima::DockManager::S::SpeedButton

       The package simplifies creation of "Prima::SpeedButton" command
       widgets.

   Methods
       class IMAGE, CLSID, %PROFILE
           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.

           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