Man Linux: Main Page and Category List


       Prima::Docks - dockable widgets


       The module contains a set of classes and an implementation of dockable
       widgets interface. The interface assumes two parties, the dockable
       widget and the dock widget; the generic methods for the dock widget
       class are contained in "Prima::AbstractDocker::Interface" package.


       A dockable widget is required to take particular steps before it can
       dock to a dock widget. It needs to talk to the dock and find out if it
       is allowed to land, or if the dock contains lower-level dock widgets
       that might suit better for docking. If there’s more than one dock
       widget in the program, the dockable widget can select between the
       targets; this is especially actual when a dockable widget is dragged by
       mouse and the arbitration is performed on geometrical distance basis.

       The interface implies that there exists at least one tree-like
       hierarchy of dock widgets, linked up to a root dock widget. The
       hierarchy is not required to follow parent-child relationships,
       although this is the default behavior.  All dockable widgets are
       expected to know explicitly what hierarchy tree they wish to dock to.
       "Prima::InternalDockerShuttle" introduces "dockingRoot" property for
       this purpose.

       The conversation between parties starts when a dockable widget calls
       "open_session" method of the dock. The dockable widget passes set of
       parameters signaling if the widget is ready to change its size in case
       the dock widget requires so, and how. "open_session" method can either
       refuse or accept the widget.  In case of the positive answer from
       "open_session", the dockable widget calls "query" method, which either
       returns a new rectangle, or another dock widget.  In the latter case,
       the caller can enumerate all available dock widgets by repetitive calls
       to "next_docker" method. The session is closed by "close_session" call;
       after that, the widget is allowed to dock by setting its "owner" to the
       dock widget, the "rect" property to the negotiated position and size,
       and calling "dock" method.

       "open_session"/"close_session" brackets are used to cache all necessary
       calculations once, making "query" call as light as possible. This
       design allows a dockable widget, when dragged, repeatedly ask all
       reachable docks in an optimized way. The docking sessions are kept open
       until the drag session is finished.

       The conversation can be schematized in the following code:

               my $dock = $self-> dockingRoot;
               my $session_id = $dock-> open_session({ self => $self });
               return unless $session_id;
               my @result = $dock-> query( $session_id, $self-> rect );
               if ( 4 == scalar @result) {       # new rectangle is returned
                       if ( ..... is new rectangle acceptable ? ... ) {
                               $dock-> close_session( $session_id);
                               $dock-> dock( $self);
               } elsif ( 1 == scalar @result) {  # another dock returned
                       my $next = $result[0];
                       while ( $next) {
                               if ( ... is new docker acceptable? ....) {
                                       $dock-> close_session( $session_id);
                                       $next-> dock( $self);
                               $next = $dock-> next_docker( $session_id, $self-> origin );
               $dock-> close_session( $session_id);

       Since even the simplified code is quite cumbersome, direct calls to
       "open_session" are rare. Instead, "Prima::InternalDockerShuttle"
       implements "find_docking" method which performs the arbitration
       automatically and returns the appropriate dock widget.

       "Prima::InternalDockerShuttle" is a class that implements dockable
       widget functionality. It also employs a top-level window-like wrapper
       widget for the dockable widget when it is not docked.  By default,
       "Prima::ExternalDockerShuttle" is used as the wrapper widget class.

       It is not required, however, to use neither
       "Prima::InternalDockerShuttle" nor "Prima::AbstractDocker::Interface"
       to implement a dockable widget; the only requirements to one is to
       respect "open_session"/"close_session" protocol.

       "Prima::InternalDockerShuttle" initiates a class hierarchy of dockable
       widgets.  Its descendants are "Prima::LinearWidgetDocker" and, in turn,
       "Prima::SingleLinearWidgetDocker".  "Prima::SimpleWidgetDocker" and
       "Prima::LinearWidgetDocker", derived from
       "Prima::AbstractDocker::Interface", begin hierarchy of dock widgets.
       The full hierarchy is as follows:




       All docker widget classes are derived from
       "Prima::AbstractDocker::Interface".  Depending on the specialization,
       they employ more or less sophisticated schemes for arranging dockable
       widgets inside. The most complicated scheme is implemented in
       "Prima::LinearWidgetDocker"; it does not allow children overlapping and
       is able to rearrange with children and resize itself when a widget is
       docked or undocked.

       The package provides only basic functionality. Module
       "Prima::DockManager" provides common dockable controls, - toolbars,
       panels, speed buttons etc.  based on "Prima::Docks" module. See


       Implements generic functionality of a docket widget. The class is not
       derived from "Prima::Widget"; is used as a secondary ascendant class
       for dock widget classes.

       Since the class is not "Prima::Object" descendant, it provides only
       run-time implementation of its properties. It is up to the descendant
       object whether the properties are recognized on the creation stage or

       fingerprint INTEGER
           A custom bit mask, to be used by docking widgets to reject
           inappropriate dock widgets on early stage. The "fingerprint"
           property is not part of the protocol, and is not required to be
           present in a dockable widget implementation.

           Default value: 0x0000FFFF

       dockup DOCK_WIDGET
           Selects the upper link in dock widgets hierarchy tree. The upper
           link is required to be a dock widget, but is not required to be a
           direct or an indirect parent. In this case, however, the
           maintenance of the link must be implemented separately, for

                   $self-> dockup( $upper_dock_not_parent );

                   $upper_dock_not_parent-> add_notification( 'Destroy', sub {
                           return unless $_[0] == $self-> dockup;
                           undef $self-> {dockup_event_id};
                           $self-> dockup( undef );
                   }, $self);

                   $self-> {destroy_id} = $self-> add_notification( 'Destroy', sub {
                           $self-> dockup( undef );
                   } unless $self-> {destroy_id};

       add_subdocker SUBDOCK
           Appends SUBDOCK to the list of lower-level docker widgets. The
           items of the list are returned by "next_docker" method.

       check_session SESSION
           Debugging procedure; checks SESSION hash, warns if its members are
           invalid or incomplete. Returns 1 if no fatal errors were
           encountered; 0 otherwise.

       close_session SESSION
           Closes docking SESSION and frees the associated resources.

       dock WIDGET
           Called after WIDGET is successfully finished negotiation with the
           dock widget and changed its "owner" property. The method adapts the
           dock widget layout and lists WIDGET into list of docked widgets.
           The method does not change "owner" property of WIDGET.

           The method must not be called directly.

       dock_bunch @WIDGETS
           Effectively docks set of WIDGETS by updating internal structures
           and calling "rearrange".

           Returns array of docked widgets.

       next_docker SESSION, [ X, Y ]
           Enumerates lower-level docker widgets within SESSION; returns one
           docker widget at a time. After the last widget returns "undef".

           The enumeration pointer is reset by "query" call.

           X and Y are coordinates of the point of interest.

       open_session PROFILE
           Opens docking session with parameters stored in PROFILE and returns
           session ID scalar in case of success, or "undef" otherwise.  The
           following keys must be set in PROFILE:

           position ARRAY
               Contains two integer coordinates of the desired position of a
               widget in (X,Y) format in screen coordinate system.

           self WIDGET
               Widget that is about to dock.

           sizeable ARRAY
               Contains two boolean flags, representing if the widget can be
               resized to an arbitrary size, horizontally and vertically. The
               arbitrary resize option used as last resort if "sizes" key does
               not contain the desired size.

           sizeMin ARRAY
               Two integers; minimal size that the widget can accept.

           sizes ARRAY
               Contains arrays of points in (X,Y) format; each point
               represents an acceptable size of the widget. If "sizeable"
               flags are set to 0, and none of "sizes" can be accepted by the
               dock widget, "open_session" fails.

       query SESSION [ X1, Y1, X2, Y2 ]
           Checks if a dockable widget can be landed into the dock.  If it
           can, returns a rectangle that the widget must be set to.  If
           coordinates ( X1 .. Y2 ) are specified, returns the rectangle
           closest to these. If "sizes" or "sizeable" keys of "open_session"
           profile were set, the returned size might be different from the
           current docking widget size.

           Once the caller finds the result appropriate, it is allowed to
           change its owner to the dock; after that, it must change its origin
           and size correspondingly to the result, and then call "dock".

           If the dock cannot accept the widget, but contains lower-lever dock
           widgets, returns the first lower-lever widget. The caller can use
           subsequent calls to "next_docker" to enumerate all lower-level dock
           widgets. A call to "query" resets the internal enumeration pointer.

           If the widget cannot be landed, an empty array is returned.

           Effectively re-docks all the docked widgets. The effect is as same
           as of

                   $self-> redock_widget($_) for $self-> docklings;

           but usually "rearrange" is faster.

       redock_widget WIDGET
           Effectively re-docks the docked WIDGET. If WIDGET has "redock"
           method in its namespace, it is called instead.

       remove_subdocker SUBDOCK
           Removes SUBDOCK from the list of lower-level docker widgets.  See
           also add_subdocker.

       replace FROM, TO
           Assigns widget TO same owner and rectangle as FROM. The FROM widget
           must be a docked widget.

       undock WIDGET
           Removes WIDGET from list of docked widgets. The layout of the dock
           widget can be changed after execution of this method. The method
           does not change "owner" property of WIDGET.

           The method must not be called directly.


       A simple dock widget; accepts any widget that geometrically fits into.
       Allows overlapping of the docked widgets.


       A simple dock widget; accepts any widget that can be fit to cover all
       dock’s interior.


       A toolbar-like docking widget class. The implementation does not allow
       tiling, and can reshape the dock widget and rearrange the docked
       widgets if necessary.

       "Prima::LinearWidgetDocker" is orientation-dependent; its main axis,
       governed by "vertical" property, is used to align docked widgets in
       ’lines’, which in turn are aligned by the opposite axis ( ’major’ and
       ’minor’ terms are used in the code for the axes ).

       growable INTEGER
           A combination of "grow::XXX" constants, that describes how the dock
           widget can be resized. The constants are divided in two sets,
           direct and indirect, or, "vertical" property independent and

           The first set contains explicitly named constants:

                   grow::Left       grow::ForwardLeft       grow::BackLeft
                   grow::Down       grow::ForwardDown       grow::BackDown
                   grow::Right      grow::ForwardRight      grow::BackRight
                   grow::Up         grow::ForwardUp         grow::BackUp

           that select if the widget can be grown to the direction shown.
           These do not change meaning when "vertical" changes, though they do
           change the dock widget behavior. The second set does not affect
           dock widget behavior when "vertical" changes, however the names are
           not that illustrative:

                   grow::MajorLess  grow::ForwardMajorLess  grow::BackMajorLess
                   grow::MajorMore  grow::ForwardMajorMore  grow::BackMajorMore
                   grow::MinorLess  grow::ForwardMinorLess  grow::BackMinorLess
                   grow::MinorMore  grow::ForwardMinorMore  grow::BackMinorMore

           "Forward" and "Back" prefixes select if the dock widget can be
           respectively expanded or shrunk in the given direction. "Less" and
           "More" are equivalent to "Left" and "Right" when "vertical" is 0,
           and to "Up" and "Down" otherwise.

           The use of constants from the second set is preferred.

           Default value: 0

       hasPocket BOOLEAN
           A boolean flag, affects the possibility of a docked widget to
           reside outside the dock widget inferior. If 1, a docked wigdet is
           allowed to stay docked ( or dock into a position ) further on the
           major axis ( to the right when "vertical" is 0, up otherwise ), as
           if there’s a ’pocket’. If 0, a widget is neither allowed to dock
           outside the inferior, nor is allowed to stay docked ( and is
           undocked automatically ) when the dock widget shrinks so that the
           docked widget cannot stay in the dock boundaries.

           Default value: 1

       vertical BOOLEAN
           Selects the major axis of the dock widget. If 1, it is vertical,
           horizontal otherwise.

           Default value: 0

           Called when "dock" is successfully finished.

       DockError WIDGET
           Called when "dock" is unsuccessfully finished. This only happens if
           WIDGET does not follow the docking protocol, and inserts itself
           into a non-approved area.

           Called when "undock" is finished.


       Descendant of "Prima::LinearWidgetDocker". In addition to the
       constraints, introduced by the ascendant class,
       "Prima::SingleLinearWidgetDocker" allows only one line ( or row,
       depending on "vertical" property value ) of docked widgets.


       Implementation of a docking widget, with its four sides acting as
       ’rubber’ docking areas.

       indents ARRAY
           Contains four integers, specifying the breadth of offset for each
           side. The first integer is width of the left side, the second -
           height of the bottom side, the third - width of the right side, the
           fourth - height of the top side.

       dockerClassLeft STRING
           Assigns class of left-side dock window.

           Default value: "Prima::LinearWidgetDocker".  Create-only property.

       dockerClassRight STRING
           Assigns class of right-side dock window.

           Default value: "Prima::LinearWidgetDocker".  Create-only property.

       dockerClassTop STRING
           Assigns class of top-side dock window.

           Default value: "Prima::LinearWidgetDocker".  Create-only property.

       dockerClassBottom STRING
           Assigns class of bottom-side dock window.

           Default value: "Prima::LinearWidgetDocker".  Create-only property.

       dockerClassClient STRING
           Assigns class of center dock window.

           Default value: "Prima::ClientWidgetDocker".  Create-only property.

       dockerProfileLeft HASH
           Assigns hash of properties, passed to the left-side dock widget
           during the creation.

           Create-only property.

       dockerProfileRight HASH
           Assigns hash of properties, passed to the right-side dock widget
           during the creation.

           Create-only property.

       dockerProfileTop HASH
           Assigns hash of properties, passed to the top-side dock widget
           during the creation.

           Create-only property.

       dockerProfileBottom HASH
           Assigns hash of properties, passed to the bottom-side dock widget
           during the creation.

           Create-only property.

       dockerProfileClient HASH
           Assigns hash of properties, passed to the center dock widget during
           the creation.

           Create-only property.

       dockerDelegationsLeft ARRAY
           Assigns the left-side dock list of delegated notifications.

           Create-only property.

       dockerDelegationsRight ARRAY
           Assigns the right-side dock list of delegated notifications.

           Create-only property.

       dockerDelegationsTop ARRAY
           Assigns the top-side dock list of delegated notifications.

           Create-only property.

       dockerDelegationsBottom ARRAY
           Assigns the bottom-side dock list of delegated notifications.

           Create-only property.

       dockerDelegationsClient ARRAY
           Assigns the center dock list of delegated notifications.

           Create-only property.

       dockerCommonProfile HASH
           Assigns hash of properties, passed to all five dock widgets during
           the creation.

           Create-only property.


       The class provides a container, or a ’shuttle’, for a client widget,
       while is docked to an "Prima::AbstractDocker::Interface" descendant
       instance. The functionality includes communicating with dock widgets,
       the user interface for dragging and interactive dock selection, and a
       client widget container for non-docked state. The latter is implemented
       by reparenting of the client widget to an external shuttle widget,
       selected by "externalDockerClass" property. Both user interfaces for
       the docked and the non-docked shuttle states are minimal.

       The class implements dockable widget functionality, served by
       "Prima::AbstractDocker::Interface", while itself it is derived from
       "Prima::Widget" only.

       See also: "Prima::ExternalDockerShuttle".

       client WIDGET
           Provides access to the client widget, which always resides either
           in the internal or the external shuttle. By default there is no
           client, and any widget capable of changing its parent can be set as
           one.  After a widget is assigned as a client, its "owner" and
           "clipOwner" properties must not be used.

           Run-time only property.

       dock WIDGET
           Selects the dock widget that the shuttle is landed on. If "undef",
           the shuttle is in the non-docked state.

           Default value: "undef"

       dockingRoot WIDGET
           Selects the root of dock widgets hierarchy.  If "undef", the
           shuttle can only exist in the non-docked state.

           Default value: "undef"

           See "USAGE" for reference.

       externalDockerClass STRING
           Assigns class of external shuttle widget.

           Default value: "Prima::ExternalDockerShuttle"

       externalDockerModule STRING
           Assigns module that contains the external shuttle widget class.

           Default value: "Prima::MDI" ( "Prima::ExternalDockerShuttle" is
           derived from "Prima::MDI" ).

       externalDockerProfile HASH
           Assigns hash of properties, passed to the external shuttle widget
           during the creation.

       fingerprint INTEGER
           A custom bit mask, used to reject inappropriate dock widgets on
           early stage.

           Default value: 0x0000FFFF

       indents ARRAY
           Contains four integers, specifying the breadth of offset in pixels
           for each widget side in the docked state.

           Default value: "5,5,5,5".

       snapDistance INTEGER
           A maximum offset, in pixels, between the actual shuttle coordinates
           and the coordinates proposed by the dock widget, where the shuttle
           is allowed to land.  In other words, it is the distance between the
           dock and the shuttle when the latter ’snaps’ to the dock during the
           dragging session.

           Default value: 10

       x_sizeable BOOLEAN
           Selects whether the shuttle can change its width in case the dock
           widget suggests so.

           Default value: 0

       y_sizeable BOOLEAN
           Selects whether the shuttle can change its height in case the dock
           widget suggests so.

           Default value: 0

       client2frame X1, Y1, X2, Y2
           Returns a rectangle that the shuttle would occupy if its client
           rectangle is assigned to X1, Y1, X2, Y2 rectangle.

           Docks to the recent dock widget, if it is still available.

           Initiates or aborts the dragging session, depending on STATE
           boolean flag.

           If it is 1, RECT is an array with the coordinates of the shuttle
           rectangle before the drag has started; ANCHOR_X and ANCHOR_Y are
           coordinates of the aperture point where the mouse event occurred
           that has initiated the drag.  Depending on how the drag session
           ended, the shuttle can be relocated to another dock, undocked, or
           left intact. Also, "Dock", "Undock", or "FailDock" notifications
           can be triggered.

           If STATE is 0, RECT, ANCHOR_X ,and ANCHOR_Y parameters are not

       find_docking DOCK, [ POSITION ]
           Opens a session with DOCK, unless it is already opened, and
           negotiates about the possibility of landing ( at particular
           POSITION, if this parameter is present ).

           "find_docking" caches the dock widget sessions, and provides a
           possibility to select different parameters passed to "open_session"
           for different dock widgets. To achieve this, "GetCaps" request
           notification is triggered, which fills the parameters. The default
           action sets "sizeable" options according to "x_sizeable" and
           "y_sizeable" properties.

           In case an appropriate landing area is found, "Landing"
           notification is triggered with the proposed dock widget and the
           target rectangle. The area can be rejected on this stage if
           "Landing" returns negative answer.

           On success, returns a dock widget found and the target rectangle;
           the widget is never docked though. On failure returns an empty

           This method is used by the dragging routine to provide a visual
           feedback to the user, to indicate that a shuttle may or may not
           land in a particular area.

       frame2client X1, Y1, X2, Y2
           Returns a rectangle that the client would occupy if the shuttle
           rectangle is assigned to X1, Y1, X2, Y2 rectangle.

           If docked, undocks form the dock widget and docks back.  If not
           docked, does not perform anything.

           Called when shuttle is docked.

           Triggered when the user presses close button or otherwise activates
           the "close" function of the EDS ( external docker shuttle ). To
           cancel the closing, "clear_event" must be called inside the event

       FailDock X, Y
           Called after the dragging session in the non-docked stage is
           finished, but did not result in docking. X and Y are the
           coordinates of the new external shuttle position.

       GetCaps DOCK, PROFILE
           Called before the shuttle opens a docking session with DOCK widget.
           PROFILE is a hash reference, which is to be filled inside the event
           handler. After that PROFILE is passed to "open_session" call.

           The default action sets "sizeable" options according to
           "x_sizeable" and "y_sizeable" properties.

       Landing DOCK, X1, Y1, X2, Y2
           Called inside the docking session, after an appropriate dock widget
           is selected and the landing area is defined as X1, Y1, X2, Y2. To
           reject the landing on either DOCK or area, "clear_event" must be

           Called when shuttle is switched to the non-docked state.


       A shuttle class, used to host a client of
       "Prima::InternalDockerShuttle" widget when it is in the non-docked
       state. The class represents an emulation of a top-level window, which
       can be moved, resized ( this feature is not on by default though ), and

       "Prima::ExternalDockerShuttle" is inherited from "Prima::MDI" class,
       and its window emulating functionality is a subset of its ascendant.
       See also Prima::MDI.

       shuttle WIDGET
           Contains reference to the dockable WIDGET


       A simple descendant of "Prima::InternalDockerShuttle", used for
       toolbars. Introduces orientation and draws a tiny header along the
       minor shuttle axis. All its properties concern only the way the shuttle
       draws itself.

       headerBreadth INTEGER
           Breadth of the header in pixels.

           Default value: 8

       indent INTEGER
           Provides a wrapper to "indents" property; besides the space for the
           header, all indents are assigned to "indent" property value.

       vertical BOOLEAN
           If 1, the shuttle is drawn as a vertical bar.  If 0, the shuttle is
           drawn as a horizontal bar.

           Default value: 0


       Dmitry Karasik, <>.


       Prima, Prima::Widget, Prima::MDI, Prima::DockManager, examples/