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);
			return;
		}
	} 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);
				return;
			}
			$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:

	Prima::AbstractDocker::Interface
		Prima::SimpleWidgetDocker
		Prima::ClientWidgetDocker
		Prima::LinearWidgetDocker 
		Prima::FourPartDocker

	Prima::InternalDockerShuttle 
		Prima::LinearDockerShuttle 
		Prima::SingleLinearWidgetDocker 

	Prima::ExternalDockerShuttle

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 Prima::DockManager.

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

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

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

docklings

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.

rearrange

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

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

Dock

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.

Undock

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.

dock_back

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

drag STATE, RECT, ANCHOR_X, ANCHOR_Y

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

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

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.

redock

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

Dock

Called when shuttle is docked.

EDSClose

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

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.

Undock

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

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, <dmitry@karasik.eu.org>.

Prima, Prima::Widget, Prima::MDI, Prima::DockManager, examples/dock.pl