com.vlsolutions.swing.docking

Class DockingDesktop

public class DockingDesktop extends JLayeredPane

The DockingDesktop is the main class of the VLDocking Framework.

It is the equivalent of what is JDesktopPane for JInternalWindow : a JLayeredPane customized to include :

UNKNOWN: 2005/10/06 Lilian Chamontin : added support for dnd to floatables 2005/10/07 Lilian Chamontin : cancel drag operation with ESCAPE key 2005/11/08 Lilian Chamontin : added support for global width/height drop (in split method) 2005/11/14 Lilian Chamontin : reworked setFloating methods. 2005/12/08 Lilian Chamontin : fixed a bug related to multiple desktop usage (when moving a window after the desktop has been removed from hierarchy, the listeners were still invoked and caused a NPE in moveFloatingWindows).

Field Summary
protected AutoHideButtonPanel[]borderPanes
array containing the border panes
protected AutoHideButtonPanelbottomBorderPane
panel used to display autohide buttons
protected HashMapdockableStates
inner state of the dockables
protected DockingPaneldockingPanel
main central container for dockables
protected AutoHideExpandPanelexpandPanel
container responsible for auto-hidden components expansion
protected AutoHideButtonPanelleftBorderPane
panel used to display autohide buttons
protected HashMappreviousFloatingDockableStates
return state for floating dockables
protected ArrayListregisteredDockables
All dockables must be registered (even if not shown) in order to be processed by the XML Parser or to be displayed in the DockingSelectorDialog
protected AutoHideButtonPanelrightBorderPane
panel used to display autohide buttons
protected HashMaptabbedGroups
groups of tabs (used to re-tab autohidden dockable)
protected AutoHideButtonPaneltopBorderPane
panel used to display autohide buttons
Constructor Summary
DockingDesktop()
Method Summary
voidaddDockable(Dockable dockable)
Adds a dockable in the docking desktop.
voidaddDockable(Dockable dockable, RelativeDockablePosition position)
Adds a dockable in the docking desktop, and tries to respect the relative positionning provided.
voidaddDockableSelectionListener(DockableSelectionListener listener)
Adds a new DockableSelectionListener to this desktop.
voidaddDockableStateChangeListener(DockableStateChangeListener listener)
Adds a new DockableStateChangeListener to this desktop.
voidaddDockableStateWillChangeListener(DockableStateWillChangeListener listener)
Adds a new DockableStateWillChangeListener to this desktop.
voidaddHiddenDockable(Dockable dockable, RelativeDockablePosition dockedPosition)
Registers and add a dockable on an auto-hidde border.
voidaddToTabbedGroup(Dockable base, Dockable newTab)
Registers a dockable as belonging to a tab group.
voidclose(Dockable dockable)
Disposes the dockable container of this dockable.
voidcloseAllDockablesInTab(Dockable base)
Convenience method to close all dockables of the tabbedContainer containing "base" (including the base dockable).
voidcloseAllOtherDockablesInTab(Dockable exception)
Convenience method to close all dockables of a TabbedDockableContainer except one.
protected AutoHideExpandPanelcreateAutoHideExpandPanel()
Creates the autohide expand panel to be used in this desktop.
protected FloatingDockableContainercreateFloatingDockableContainer(Dockable dockable)
Creates a floating JDialog to be used with this dockable.
protected FloatingDockableContainercreateFloatingDockableContainer(TabbedDockableContainer tdc)
Creates a floating JDialog to be used for a whole TabbedDockableContainer.
voidcreateTab(Dockable base, Dockable dockable, int order)
Adds a view in a tab, or create it if it doesn't exist.
voidcreateTab(Dockable base, Dockable dockable, int order, boolean select)
Add a view in a tab, or create it if it doesn't exist.
voiddropRemove(DockableDragSource dragSource)
Removes a visible dockable : called from a drag and drop operation.
DockableState[]getDockables()
Creates and returns an array of all registered dockable with their current state.
DockableStategetDockableState(Dockable dockable)
Returns the current state of a dockable (CLOSED, HIDDEN, DOCKED, MAXIMIZED, FLOATING)
static StringgetDockingFrameworkBuildDate()
Returns a String containing the release date of the current version.
static StringgetDockingFrameworkVersion()
Returns a String containing the version of the docking framework in the format M.m.r where M is the major , m the minor and r the release.
InsetsgetDockingPanelInsets()
recalculates and returns the insets taken by autoexpand borders around the docking panel.
DimensiongetPreferredSize()
Evaluates and returns the preferred size of the desktop, according to its contents and auto-hide borders.
DockableStategetPreviousDockableState(Dockable dockable)
Returns the previous state of a hidden or floating dockable (when that dockable was in the DOCKED state.
DockablegetSelectedDockable()
Returns the currently selected dockable, or null if none is selected.
voidinstallDockableDragSource(DockableDragSource source)
This method is used by DockableContainers in order to register their DockableDragSource(s) to the DragControler.
voidinstallDockableDragSources(DockableDragSource[] sources)
Installs multiple drag sources.
booleanisOpaqueContents()
Returns whether this desktop's contents are opaque or not.
voidmaximize(Dockable dockable)
Extends the size of this dockable to fill the docking panel.
voidmove(Dockable base, Dockable dockable, DockingConstants.Split position)
Moves a dockable to another position (relative to a destination dockable)
voidreadXML(InputStream in)
Reads an XML encoded stream as the new desktop configuration.
voidregisterDockable(Dockable dockable)
Every dockable must be registered in order to be shown in the DockingDesktop.
voidremove(Dockable dockable)
Removes a visible dockable from the containment hierarchy (including autohide border buttons).
protected voidremoveContainer(SingleDockableContainer dc)
Removes a dockable container.
voidremoveDockableSelectionListener(DockableSelectionListener listener)
Removes a DockableSelectionListener from this desktop.
voidremoveDockableStateChangeListener(DockableStateChangeListener listener)
Removes a DockableStateChangeListener from this desktop.
voidremoveDockableStateWillChangeListener(DockableStateWillChangeListener listener)
Removes a DockableStateWillChangeListener from this desktop.
voidremoveFromTabbedGroup(Dockable dockable)
Unregisters a dockable from its current tab group (when it's removed from it).
voidresetToPreferredSize()
Request this desktop to reset it's contained views to their preferred size, if possible.
voidrestore(Dockable dockable)
Restore the dockable to the docking position it was before beeing maximized.
voidsetAutoHide(Dockable dockable, boolean hide)
Toggles the position of a view between hidden (true) and docked (false).
voidsetAutoResizableDockable(Dockable dockable)
Updates the resizing behaviour of the desktop in order to resize this dockable (and keep others at fixed size).
voidsetDockableHeight(Dockable dockable, double height)
Changes the height of a dockable (the dockable must already be visible).
voidsetDockableWidth(Dockable dockable, double width)
Changes the width of a dockable (the dockable must already be visible).
voidsetFloating(Dockable dockable, boolean floating)
Detach or attach the dockable from/to the desktop.
voidsetFloating(Dockable dockable, boolean floating, Point screenPosition)
Detach or attach the dockable from/to the desktop.
voidsetOpaqueContents(boolean opaque)
Set the desktop contents to be opaque or transparent.
voidsplit(Dockable base, Dockable newDockable, DockingConstants.Split position)
Splits a Dockable in 2 parts, if possible.
voidsplitComponent(Component base, Dockable dockable, DockingConstants.Split position)
Replaces the base component by a split pane oriented according to position, and put dockable at position.
voidsplitComponent(Component base, Container dockablesContainer, DockingConstants.Split position)
Replaces the base component by a split pane oriented according to position, and put the dockablesContainer at position.
voiduninstallDockableDragSource(DockableDragSource source)
This method is used by DockableContainers in order to unregister their DockableDragSource(s) to the DragControler.
voiduninstallDockableDragSources(DockableDragSource[] sources)
Uninstalls multiple drag sources.
voidunregisterDockable(Dockable dockable)
Unregisters the dockable, which can be garbage collected (no longer used by the docking desktop.
voidwriteXML(OutputStream stream)
Saves the current desktop configuration into an XML stream.

Field Detail

borderPanes

protected AutoHideButtonPanel[] borderPanes
array containing the border panes

bottomBorderPane

protected AutoHideButtonPanel bottomBorderPane
panel used to display autohide buttons

dockableStates

protected HashMap dockableStates
inner state of the dockables

dockingPanel

protected DockingPanel dockingPanel
main central container for dockables

expandPanel

protected AutoHideExpandPanel expandPanel
container responsible for auto-hidden components expansion

leftBorderPane

protected AutoHideButtonPanel leftBorderPane
panel used to display autohide buttons

previousFloatingDockableStates

protected HashMap previousFloatingDockableStates
return state for floating dockables

registeredDockables

protected ArrayList registeredDockables
All dockables must be registered (even if not shown) in order to be processed by the XML Parser or to be displayed in the DockingSelectorDialog

rightBorderPane

protected AutoHideButtonPanel rightBorderPane
panel used to display autohide buttons

tabbedGroups

protected HashMap tabbedGroups
groups of tabs (used to re-tab autohidden dockable)

topBorderPane

protected AutoHideButtonPanel topBorderPane
panel used to display autohide buttons

Constructor Detail

DockingDesktop

public DockingDesktop()

Method Detail

addDockable

public void addDockable(Dockable dockable)
Adds a dockable in the docking desktop.

This method can be used mainly in two situations :

addDockable

public void addDockable(Dockable dockable, RelativeDockablePosition position)
Adds a dockable in the docking desktop, and tries to respect the relative positionning provided.

This method is used to reposition a closed dockable at its previous location on the desktop. As it relies on the Component.findComponentAt(Point) method , the desktop must already be visible.

The preferred way to obtain a particular visual docking confuguration is to use a combination of add(), split() and createTab() methods, as these methods do not rely on an interpretation (and approximation) of constraints.

Precision of constraints : as the docking management is based on a mix of horizontal and vertical splitting zones, it is not always possible to respect the constraints given.

The current implementation will do the following :

Parameters: dockable the dockable to add (must not be already visible) position relative position of the dockable

Throws: IllegalArgumentException if the dockable already belongs to the desktop containment hierarchy.

addDockableSelectionListener

public void addDockableSelectionListener(DockableSelectionListener listener)
Adds a new DockableSelectionListener to this desktop.

DockableSelection Events are triggered when a dockable takes the focus.

addDockableStateChangeListener

public void addDockableStateChangeListener(DockableStateChangeListener listener)
Adds a new DockableStateChangeListener to this desktop.

DockableStateChange Events are triggered after the state change.

As of version 2.0 of the framework, this method can also be replaced by adding a propertychangeListener on the DockKey object (and react to its DockableState property).

addDockableStateWillChangeListener

public void addDockableStateWillChangeListener(DockableStateWillChangeListener listener)
Adds a new DockableStateWillChangeListener to this desktop.

DockableStateWillChange Events are triggered before the state change, and are vetoable.

addHiddenDockable

public void addHiddenDockable(Dockable dockable, RelativeDockablePosition dockedPosition)
Registers and add a dockable on an auto-hidde border.

this method should be called at startup time (when the dockable isn't yet displayed). to toggle a dockable from docked to auto-hide, please use setAutoHide(Dockable, boolean) instead.

However, this method will not fail if the dockable is already displayed : in that case, it will delegate autohide to setAutoHide(Dockable, boolean), thus dropping the dockedPosition argument.

Parameters: dockable the dockable to add (to select the border where the dockable will be positionned, use the DockKey.setAuhideBorder mehod dockedPosition relative positionning (may be null) indicating where to dock the dockable when leaving its auto-hide border.

addToTabbedGroup

public void addToTabbedGroup(Dockable base, Dockable newTab)
Registers a dockable as belonging to a tab group.

It is used to have a memory of grouped (tabbed) dockables in order to keep the group together when dockable are restored from auto-hide mode.

This method is generally called by the tabbed container management, and not directly by the developper.

However, there is a case where calling this method can be usefull : when, at startup, a desktop is built with multiple hidden dockables, and the developper wants them to be grouped in a tab container when they are restored to the desktop.

note that the method is symetric when a group is empty : it such a case base and newTab args can be swapped.

Parameters: base an already tabbed dockable newTab a dockable to add to the tab group

Since: 1.1.2

close

public void close(Dockable dockable)
Disposes the dockable container of this dockable.

If the dockable is not currently displayed (or auto-hidden), this method will do nothing.

the dockable remains registered and can later be shown again at the same location.

closeAllDockablesInTab

public void closeAllDockablesInTab(Dockable base)
Convenience method to close all dockables of the tabbedContainer containing "base" (including the base dockable).

see also {@link #closeAllOtherDockablesInTab(Dockable)}.

Note : is a dockable is not allowed to close (key.isCloseEnabled() returns false) then it won't be closed by this method.

If the 'base' dockable isn't contained in a tab, then nothing will happen.

closeAllOtherDockablesInTab

public void closeAllOtherDockablesInTab(Dockable exception)
Convenience method to close all dockables of a TabbedDockableContainer except one.

Note : is a dockable is not allowed to close (key.isCloseEnabled() returns false) then it won't be closed by this method.

If the 'exception' dockable isn't contained in a tab, then nothing will happen.

createAutoHideExpandPanel

protected AutoHideExpandPanel createAutoHideExpandPanel()
Creates the autohide expand panel to be used in this desktop.

This method gives a chance to the developer to override expand panel creation and provide a custom subclass.

createFloatingDockableContainer

protected FloatingDockableContainer createFloatingDockableContainer(Dockable dockable)
Creates a floating JDialog to be used with this dockable.

This method is protected to give access to implementors wanting to customize its look and feel (for example : removing the title bar by setting it to "undecorated").

The old API has been removed (it returned a JDialog) as the DockingDesktop can only work with FloatingDockableContainers.

createFloatingDockableContainer

protected FloatingDockableContainer createFloatingDockableContainer(TabbedDockableContainer tdc)
Creates a floating JDialog to be used for a whole TabbedDockableContainer.

This method is protected to give access to implementors wanting to customize its look and feel (for example : removing the title bar by setting it to "undecorated").

The old API has been removed (it returned a JDialog) as the DockingDesktop can only work with FloatingDockableContainers.

createTab

public void createTab(Dockable base, Dockable dockable, int order)
Adds a view in a tab, or create it if it doesn't exist.

Parameters: base the reference dockable dockable a dockable to add at the same position than base. if base is not already child of a tabbedpane, a new tabbedpane will be created and inserted at base's location. order the tab order of view in its tabbed pane.

createTab

public void createTab(Dockable base, Dockable dockable, int order, boolean select)
Add a view in a tab, or create it if it doesn't exist.

Optional added tab selection.

Parameters: base an existing dockable, either displayed in a DockableContainer or in a TabbedDockableContainer.

If base is displayed by a DockableContainer, this container will be replaced by a TabbedDockableContainer. dockable the dockable to add order the tab order of view in its tabbed pane. select if true, will select the added tab (make it appear at front)

dropRemove

public void dropRemove(DockableDragSource dragSource)
Removes a visible dockable : called from a drag and drop operation.

Don't call this method directly, as it is meant to be used only by the drag and drop event components.

getDockables

public DockableState[] getDockables()
Creates and returns an array of all registered dockable with their current state.

Visibility states are [DockableState.STATE_CLOSED, STATE_DOCKED, STATE_HIDDEN]

Returns: an array of DockableState

getDockableState

public DockableState getDockableState(Dockable dockable)
Returns the current state of a dockable (CLOSED, HIDDEN, DOCKED, MAXIMIZED, FLOATING)

getDockingFrameworkBuildDate

public static String getDockingFrameworkBuildDate()
Returns a String containing the release date of the current version.

Since: 2.0

getDockingFrameworkVersion

public static String getDockingFrameworkVersion()
Returns a String containing the version of the docking framework in the format M.m.r where M is the major , m the minor and r the release.

Since: 2.0

getDockingPanelInsets

public Insets getDockingPanelInsets()
recalculates and returns the insets taken by autoexpand borders around the docking panel.

getPreferredSize

public Dimension getPreferredSize()
Evaluates and returns the preferred size of the desktop, according to its contents and auto-hide borders.

getPreviousDockableState

public DockableState getPreviousDockableState(Dockable dockable)
Returns the previous state of a hidden or floating dockable (when that dockable was in the DOCKED state.

Since: 2.0.4

getSelectedDockable

public Dockable getSelectedDockable()
Returns the currently selected dockable, or null if none is selected.

A selected dockable is a dockable whose component contains the keyboard focus.

installDockableDragSource

public void installDockableDragSource(DockableDragSource source)
This method is used by DockableContainers in order to register their DockableDragSource(s) to the DragControler.

Adds a MouseListener and a MouseMotionListener to the Component-DockableDragSource source. These listeners are used to perform start-dragging-docking actions over the source component

installDockableDragSources

public void installDockableDragSources(DockableDragSource[] sources)
Installs multiple drag sources.

See Also:

isOpaqueContents

public boolean isOpaqueContents()
Returns whether this desktop's contents are opaque or not.

Default value is true (opaque).

Since: 2.0.4

See Also: .

maximize

public void maximize(Dockable dockable)
Extends the size of this dockable to fill the docking panel.

The component must be docked before beeing maximized, otherwise an IllegalArgumentException will be thrown.

The opposite method of maximize is restore(Dockable).

See Also:

move

public void move(Dockable base, Dockable dockable, DockingConstants.Split position)
Moves a dockable to another position (relative to a destination dockable)

Parameters: dockable must be a registered Dockable base must be a visible Dockable position relative positionning

readXML

public void readXML(InputStream in)
Reads an XML encoded stream as the new desktop configuration.

When the method returns, the desktop is totally reconfigured with posiibly different dockable at different positions.

Note : The DockKeys of the stream must be registered with the {@link #registerDockable(Dockable) registerDockable} method, prior readXML.
This is the case if the desktop is already open and dockables laid out, but might not be the case if this method is used at application startup to populate an empty desktop.

Dismisses all visible dockables (docked and auto-hidden), and clear their DockableState.

The stream is not closed at the end of the operation.

See Also: writeXML

registerDockable

public void registerDockable(Dockable dockable)
Every dockable must be registered in order to be shown in the DockingDesktop.

Registration is automatic for shown dockables : methods setCentralDockable(), split(), createTab(), hide()... leading to have the dockable visible call registerDockable() )

for not shown dockable (in order to read a configuration from an XML stream, or to list the dockable in DockingSelectorDialog ), this method must be called manually.

remove

public void remove(Dockable dockable)
Removes a visible dockable from the containment hierarchy (including autohide border buttons).

This method shouldn't be used by user applications (only by the framework).

To poperly remove a component from the desktop, use the close(Dockable) method instead

If the dockable is not visible, an error will occur

This method does not unregister the dockable.

Throws: IllegalArgumentException if the dockable is not visible (docked or auto-hide)

removeContainer

protected void removeContainer(SingleDockableContainer dc)
Removes a dockable container.

removeDockableSelectionListener

public void removeDockableSelectionListener(DockableSelectionListener listener)
Removes a DockableSelectionListener from this desktop.

removeDockableStateChangeListener

public void removeDockableStateChangeListener(DockableStateChangeListener listener)
Removes a DockableStateChangeListener from this desktop.

removeDockableStateWillChangeListener

public void removeDockableStateWillChangeListener(DockableStateWillChangeListener listener)
Removes a DockableStateWillChangeListener from this desktop.

removeFromTabbedGroup

public void removeFromTabbedGroup(Dockable dockable)
Unregisters a dockable from its current tab group (when it's removed from it).

For an application developper, there should be no need to call this method as it is managed internally by the framework, unless the developper wants to explicitely remove a component from a tab group when this component is in the auto-hide state.

Since: 1.1.2

resetToPreferredSize

public void resetToPreferredSize()
Request this desktop to reset it's contained views to their preferred size, if possible.

This method should be invoked when the component is realized (visible) due to Split Panes implementation.

restore

public void restore(Dockable dockable)
Restore the dockable to the docking position it was before beeing maximized.

The dockable must be already maximized (otherwise an IllegalArgumentException will be thrown)

See Also:

setAutoHide

public void setAutoHide(Dockable dockable, boolean hide)
Toggles the position of a view between hidden (true) and docked (false).

setAutoResizableDockable

public void setAutoResizableDockable(Dockable dockable)

Deprecated: use setResizeWeight() in every dockKey for a better resizing behaviour

Updates the resizing behaviour of the desktop in order to resize this dockable (and keep others at fixed size).

This method should be called at least once (prior to showing the desktop) with an already docked dockable.

If the dockable doesn't belong to the desktop containment hierarchy, this method will do nothing.

setDockableHeight

public void setDockableHeight(Dockable dockable, double height)
Changes the height of a dockable (the dockable must already be visible).

Note that this method works by modifying the divider location of the nearest SplitContainer ancestor of the dockable (the first splitted vertically).

As this method must be called when the desktop is visible, a simple way to do this is to add a window listener to the parent frame of the desktop, and call this method from the windowOpened(WindowEvent) notification.

Parameters: height new height (if between 0 and 1, height is taken as a proportional height, otherwise it is a pixel height.

setDockableWidth

public void setDockableWidth(Dockable dockable, double width)
Changes the width of a dockable (the dockable must already be visible).

Note that this method works by modifying the divider location of the nearest SplitContainer ancestor of the dockable (the first splitted horizontally).

As this method must be called when the desktop is visible, a simple way to do this is to add a window listener to the parent frame of the desktop, and call this method from the windowOpened(WindowEvent) notification.

Parameters: width new width (if between 0 and 1, width is taken as a proportional width, otherwise it is a pixel width.

setFloating

public void setFloating(Dockable dockable, boolean floating)
Detach or attach the dockable from/to the desktop.

When detached, the dockable is centered on the desktop.

setFloating

public void setFloating(Dockable dockable, boolean floating, Point screenPosition)
Detach or attach the dockable from/to the desktop.

show the dockable at sceenPosition (when not null) or centered (if screenPosition is null)

setOpaqueContents

public void setOpaqueContents(boolean opaque)
Set the desktop contents to be opaque or transparent.

Transparent contents allow adding background images/information when no dockable is visible (everything closed or autohidden).

Default value is true (opaque).

Since: 2.0.4

split

public void split(Dockable base, Dockable newDockable, DockingConstants.Split position)
Splits a Dockable in 2 parts, if possible.

The base dockable is the reference, the second newDockable will be added according to the position parameter.

If base is contained in a non splitable container (like a tab of DockTabbedPane) then, a splitable ancestor will be searched (until the root desktop pane is reached) to apply splitting.

Parameters: base an already docked Dockable newDockable the added dockable position position of newDockable relative to base

splitComponent

public void splitComponent(Component base, Dockable dockable, DockingConstants.Split position)
Replaces the base component by a split pane oriented according to position, and put dockable at position.

Note : This method is for DockableContainers. API users should use the {@link #split(Dockable,Dockable,DockingConstants.Split) split} method.

Parameters: base the reference component (a dockablecontainer or a split container) dockable the dockable to add position the position of dockable.

splitComponent

public void splitComponent(Component base, Container dockablesContainer, DockingConstants.Split position)
Replaces the base component by a split pane oriented according to position, and put the dockablesContainer at position.

Note : This method is for DockableContainers. API users should use the {@link #split(Dockable,Dockable,DockingConstants.Split) split} method.

Parameters: base the reference component (a dockablecontainer or a split container) dockablesContainer the dockable container position the position of dockable.

uninstallDockableDragSource

public void uninstallDockableDragSource(DockableDragSource source)
This method is used by DockableContainers in order to unregister their DockableDragSource(s) to the DragControler.

Removes the MouseListener and MouseMotionListener added on installDockableDragSource()

See Also:

uninstallDockableDragSources

public void uninstallDockableDragSources(DockableDragSource[] sources)
Uninstalls multiple drag sources.

See Also:

unregisterDockable

public void unregisterDockable(Dockable dockable)
Unregisters the dockable, which can be garbage collected (no longer used by the docking desktop.

writeXML

public void writeXML(OutputStream stream)
Saves the current desktop configuration into an XML stream.

The stream is not closed at the end of the operation.

See Also:

© Copyright 2004-2005 VLSolutions. All Rights Reserved.
www.vlsolutions.com : Java Components - Smart Client Applications