Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Prima::Docks(3)	      User Contributed Perl Documentation      Prima::Docks(3)

NAME
       Prima::Docks - dockable widgets

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

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

Prima::AbstractDocker::Interface
       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.

   Properties
       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};

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

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

Prima::ClientWidgetDocker
       A simple	dock widget; accepts any widget	that can be fit	to cover all
       dock's interior.

Prima::LinearWidgetDocker
       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 ).

   Properties
       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

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

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

Prima::FourPartDocker
       Implementation of a docking widget, with	its four sides acting as
       'rubber'	docking	areas.

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

Prima::InternalDockerShuttle
       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".

   Properties
       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

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

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

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

   Properties
       shuttle WIDGET
	   Contains reference to the dockable WIDGET

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

   Properties
       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

AUTHOR
       Dmitry Karasik, <dmitry@karasik.eu.org>.

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

perl v5.24.1			  2017-02-28		       Prima::Docks(3)

NAME | DESCRIPTION | USAGE | Prima::AbstractDocker::Interface | Prima::SimpleWidgetDocker | Prima::ClientWidgetDocker | Prima::LinearWidgetDocker | Prima::SingleLinearWidgetDocker | Prima::FourPartDocker | Prima::InternalDockerShuttle | Prima::ExternalDockerShuttle | Prima::LinearDockerShuttle | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Prima::Docks&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help