pub.vlsolutions.swing.docking

Class DockingDesktop

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JLayeredPane

pub.vlsolutions.swing.docking.DockingDesktop

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

public class DockingDesktop
extends javax.swing.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 :

• Four auto-hide borders used to show Dockable iconified as buttons.
• A nested containment hierarchy (made of JSplitPanes) with drag and drop (dock) capabilities.
• An extensive API to programmatically change its contents.
• An XML encoder/decoder to create / save / reload workspaces (sets of dockable components)
• An abstraction of the Dockable notion, with factories to allow different implementations or customization of the Dockable containers.
• An event model to track changes and react to them.

Version:

2.0

Author:

Lilian Chamontin, VLSolutions.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JLayeredPane

javax.swing.JLayeredPane.AccessibleJLayeredPane

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

Fields

Modifier and Type	Field and Description
protected AutoHideButtonPanel[]	borderPanes array containing the border panes
protected AutoHideButtonPanel	bottomBorderPane panel used to display autohide buttons
protected DockingPanel	dockingPanel main central container for dockables
protected AutoHideExpandPanel	expandPanel container responsible for auto-hidden components expansion
protected AutoHideButtonPanel	leftBorderPane panel used to display autohide buttons
protected java.util.HashMap<Dockable,DockableState>	previousFloatingDockableStates return state for floating dockables
protected AutoHideButtonPanel	rightBorderPane panel used to display autohide buttons
protected java.util.HashMap<Dockable,java.util.LinkedList<Dockable>>	tabbedGroups groups of tabs (used to re-tab autohidden dockable)
protected AutoHideButtonPanel	topBorderPane panel used to display autohide buttons

Fields inherited from class javax.swing.JLayeredPane

DEFAULT_LAYER, DRAG_LAYER, FRAME_CONTENT_LAYER, LAYER_PROPERTY, MODAL_LAYER, PALETTE_LAYER, POPUP_LAYER

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
DockingDesktop() Constructs a DockingDesktop with a default name (suitable for single-desktop applications).
DockingDesktop(java.lang.String desktopName) Constructs a DockingDesktop with a given name (suitable for multiple-desktop applications).
DockingDesktop(java.lang.String desktopName, DockingContext context) Constructs a DockingDesktop with a given name (suitable for multiple-desktop applications).

Method Summary

Methods

Modifier and Type	Method and Description
void	addDockable(CompoundDockable base, Dockable dockable) Adds a dockable inside a compound dockable.
void	addDockable(Dockable dockable) Adds a dockable in the docking desktop.
void	addDockable(Dockable dockable, RelativeDockablePosition position) Adds a dockable in the docking desktop, and tries to respect the relative positionning provided.
void	addDockableSelectionListener(DockableSelectionListener listener) Adds a new DockableSelectionListener to this desktop.
void	addDockableStateChangeListener(DockableStateChangeListener listener) Adds a new DockableStateChangeListener to this desktop.
void	addDockableStateWillChangeListener(DockableStateWillChangeListener listener) Adds a new DockableStateWillChangeListener to this desktop.
void	addDockingActionListener(DockingActionListener listener) Adds a new DockingActionListener to this desktop.
void	addHiddenDockable(Dockable dockable, RelativeDockablePosition dockedPosition) Registers and add a dockable on an auto-hide border.
void	addToTabbedGroup(Dockable base, Dockable newTab) Registers a dockable as belonging to a tab group.
void	clear() removes every dockables from this desktop
void	close(Dockable dockable) Disposes the dockable container of this dockable.
void	closeAllDockablesInTab(Dockable base) Convenience method to close all dockables of the tabbedContainer containing "base" (including the base dockable).
void	closeAllOtherDockablesInTab(Dockable exception) Convenience method to close all dockables of a TabbedDockableContainer except one.
protected AutoHideExpandPanel	createAutoHideExpandPanel() Creates the autohide expand panel to be used in this desktop.
protected FloatingDockableContainer	createFloatingDockableContainer(Dockable dockable) Creates a floating JDialog to be used with this dockable.
protected FloatingDockableContainer	createFloatingDockableContainer(TabbedDockableContainer tdc) Creates a floating JDialog to be used for a whole TabbedDockableContainer.
void	createTab(Dockable base, Dockable dockable, int order) Adds a view in a tab, or create it if it doesn't exist.
void	createTab(Dockable base, Dockable dockable, int order, boolean select) Add a view in a tab, or create it if it doesn't exist.
void	dropRemove(DockableDragSource dragSource) Removes a visible dockable : called from a drag and drop operation.
DockingContext	getContext() Returns the docking context used by this desktop (might be shared with other desktop).
java.lang.String	getDesktopName() Returns the name of this desktop (used by workspace management)
DockableState[]	getDockables() Creates and returns an array of all registered dockable with their current state.
DockableState	getDockableState(Dockable dockable) Returns the current state of a dockable (CLOSED, HIDDEN, DOCKED, MAXIMIZED, FLOATING)
static java.lang.String	getDockingFrameworkBuildDate() Returns a String containing the release date of the current version.
static java.lang.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.
java.awt.Insets	getDockingPanelInsets() recalculates and returns the insets taken by autoexpand borders around the docking panel.
Dockable	getLastSelectedDockable()
Dockable	getMaximizedDockable() returns the currently maximized dockable (or null if no dockable is in that state)
java.awt.Dimension	getPreferredSize() Evaluates and returns the preferred size of the desktop, according to its contents and auto-hide borders.
DockableState	getPreviousDockableState(Dockable dockable) Returns the previous state of a hidden or floating dockable (when that dockable was in the DOCKED state.
Dockable	getSelectedDockable() Returns the currently selected dockable, or null if none is selected.
void	installDockableDragSource(DockableDragSource source) This method is used by DockableContainers in order to register their DockableDragSource(s) to the OldDragControler.
void	installDockableDragSources(DockableDragSource[] sources) Installs multiple drag sources.
boolean	isOpaqueContents() Returns whether this desktop's contents are opaque or not.
void	maximize(Dockable dockable) Extends the size of this dockable to fill the docking panel.
void	move(Dockable base, Dockable dockable, DockingConstants.Split position) Moves a dockable to another position (relative to a destination dockable)
void	readXML(java.io.InputStream in) Reads an XML encoded stream as the new desktop configuration.
void	registerDockable(Dockable dockable) Every dockable must be registered in order to be shown in the DockingDesktop.
void	remove(Dockable dockable) Removes a visible dockable from the containment hierarchy (including autohide border buttons).
protected void	removeContainer(SingleDockableContainer dc) Removes a dockable container.
void	removeDockableSelectionListener(DockableSelectionListener listener) Removes a DockableSelectionListener from this desktop.
void	removeDockableStateChangeListener(DockableStateChangeListener listener) Removes a DockableStateChangeListener from this desktop.
void	removeDockableStateWillChangeListener(DockableStateWillChangeListener listener) Removes a DockableStateWillChangeListener from this desktop.
void	removeDockingActionListener(DockingActionListener listener) Removes a DockingActionListener from this desktop.
void	removeFromTabbedGroup(Dockable dockable) Unregisters a dockable from its current tab group (when it's removed from it).
void	replace(Dockable base, Dockable replacer) Replaces a dockable by another one.
void	resetToPreferredSize() Request this desktop to reset it's contained views to their preferred size, if possible.
void	restore(Dockable dockable) Restore the dockable to the docking position it was before beeing maximized.
void	setAutoHide(Dockable dockable, boolean hide) Toggles the position of a view between hidden (true) and docked (false).
void	setAutoResizableDockable(Dockable dockable) Deprecated. use setResizeWeight() in every dockKey for a better resizing behaviour
void	setContext(DockingContext context) Updates the docking context used by this desktop.
void	setDesktopName(java.lang.String desktopName) Updates the name of this desktop (used by workspace management)
void	setDockableHeight(Dockable dockable, double height) Changes the height of a dockable (the dockable must already be visible).
void	setDockableWidth(Dockable dockable, double width) Changes the width of a dockable (the dockable must already be visible).
void	setFloating(Dockable dockable, boolean floating) Detach or attach the dockable from/to the desktop.
void	setFloating(Dockable dockable, boolean floating, java.awt.Point screenPosition) Detach or attach the dockable from/to the desktop.
void	setOpaqueContents(boolean opaque) Set the desktop contents to be opaque or transparent.
void	split(Dockable base, Dockable newDockable, DockingConstants.Split position) Splits a Dockable in 2 parts, if possible.
void	split(Dockable base, Dockable newDockable, DockingConstants.Split position, double proportion) Splits a Dockable in 2 parts, if possible.
void	splitComponent(java.awt.Component base, java.awt.Container dockablesContainer, DockingConstants.Split position) Replaces the base component by a split pane oriented according to position, and put the dockablesContainer at position.
void	splitComponent(java.awt.Component base, Dockable dockable, DockingConstants.Split position) Replaces the base component by a split pane oriented according to position, and put dockable at position.
void	uninstallDockableDragSource(DockableDragSource source) This method is used by DockableContainers in order to unregister their DockableDragSource(s) to the OldDragControler.
void	uninstallDockableDragSources(DockableDragSource[] sources) Uninstalls multiple drag sources.
void	unregisterDockable(Dockable dockable) Unregisters the dockable, which can be garbage collected (no longer used by the docking desktop.
void	writeXML(java.io.OutputStream stream) Saves the current desktop configuration into an XML stream.

Methods inherited from class javax.swing.JLayeredPane

addImpl, getAccessibleContext, getComponentCountInLayer, getComponentsInLayer, getComponentToLayer, getIndexOf, getLayer, getLayer, getLayeredPaneAbove, getObjectForLayer, getPosition, highestLayer, insertIndexForLayer, isOptimizedDrawingEnabled, lowestLayer, moveToBack, moveToFront, paint, paramString, putLayer, remove, removeAll, setLayer, setLayer, setPosition

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

dockingPanel

protected DockingPanel dockingPanel

main central container for dockables

expandPanel

protected AutoHideExpandPanel expandPanel

container responsible for auto-hidden components expansion

topBorderPane

protected AutoHideButtonPanel topBorderPane

panel used to display autohide buttons

leftBorderPane

protected AutoHideButtonPanel leftBorderPane

panel used to display autohide buttons

bottomBorderPane

protected AutoHideButtonPanel bottomBorderPane

panel used to display autohide buttons

rightBorderPane

protected AutoHideButtonPanel rightBorderPane

panel used to display autohide buttons

borderPanes

protected AutoHideButtonPanel[] borderPanes

array containing the border panes

tabbedGroups

protected java.util.HashMap<Dockable,java.util.LinkedList<Dockable>> tabbedGroups

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

previousFloatingDockableStates

protected java.util.HashMap<Dockable,DockableState> previousFloatingDockableStates

return state for floating dockables

Constructor Detail

DockingDesktop

public DockingDesktop()

Constructs a DockingDesktop with a default name (suitable for single-desktop applications).

DockingDesktop

public DockingDesktop(java.lang.String desktopName)

Constructs a DockingDesktop with a given name (suitable for multiple-desktop applications).

This also constructs a new Docking Context, that can be shared with other Desktops.

DockingDesktop

public DockingDesktop(java.lang.String desktopName,
              DockingContext context)

Constructs a DockingDesktop with a given name (suitable for multiple-desktop applications).

Method Detail

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.

getLastSelectedDockable

public Dockable getLastSelectedDockable()

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

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:

setOpaqueContents(boolean).

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.

As of version 2.1, this method call is forwarded to the DockingContext

unregisterDockable

public void unregisterDockable(Dockable dockable)

Unregisters the dockable, which can be garbage collected (no longer used by the docking desktop.

As of version 2.1, this method call is forwarded to the DockingContext

getDockingFrameworkVersion

public static java.lang.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

getDockingFrameworkBuildDate

public static java.lang.String getDockingFrameworkBuildDate()

Returns a String containing the release date of the current version.

Since:

2.0

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)

split

public void split(Dockable base,
         Dockable newDockable,
         DockingConstants.Split position,
         double proportion)

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

proportion - proportion of the initial dockable space taken by the new dockable a negative proportion, like -1, will be ignored (and split will be based on component preferred sizes and weights). This parameter is an alternative to DockingDesktop.setDockableHeight() and setDockableWidth() methods

See Also:

DockingDesktop#setDockableHeight(com.vlsolutions.swing.docking.Dockable, double), DockingDesktop#setDockableWidth(com.vlsolutions.swing.docking.Dockable, double)

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(java.awt.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 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(java.awt.Component base,
                  java.awt.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 split method.

Parameters:

base - the reference component (a dockablecontainer or a split container)

dockablesContainer - the dockable container

position - the position of dockable.

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

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:

java.lang.IllegalArgumentException - if the dockable is not visible (docked or auto-hide)

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.

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:

restore(Dockable)

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:

maximize(Dockable)

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,
               java.awt.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)

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

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.

removeContainer

protected void removeContainer(SingleDockableContainer dc)

Removes a dockable container.

getDockableState

public DockableState getDockableState(Dockable dockable)

Returns the current state of a dockable (CLOSED, HIDDEN, DOCKED, MAXIMIZED, FLOATING)

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, using addDockable(Dockable, RelativeDockablePosition).

To have access to the RelativeDockablePosition at closing time, one has to install a DockableEventListener like this :

 desk.addDockingActionListener(new DockingActionListener() {
     public boolean acceptDockingAction(DockingActionEvent event) {
       return true;
     }
     public void dockingActionPerformed(DockingActionEvent event) {
       if (event.getActionType() == DockingActionEvent.ACTION_CLOSE){
         closedDockable = ((DockingActionCloseEvent)event).getDockable();
          RelativeDockablePostion position = desk.getLocation(closedDockable).getPosition();
          // we now have a position we'll be able to reuse in addDockable()
       }
     }
   });

 

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.

closeAllDockablesInTab

public void closeAllDockablesInTab(Dockable base)

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

see also 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.

setAutoHide

public void setAutoHide(Dockable dockable,
               boolean hide)

Toggles the position of a view between hidden (true) and docked (false).

getDockingPanelInsets

public java.awt.Insets getDockingPanelInsets()

recalculates and returns the insets taken by autoexpand borders around the docking panel.

getDockables

public DockableState[] getDockables()

Creates and returns an array of all registered dockable with their current state.

Visibility states are [DockableState.CLOSED, DOCKED, HIDDEN]

Returns:

an array of DockableState

installDockableDragSources

public void installDockableDragSources(DockableDragSource[] sources)

Installs multiple drag sources.

See Also:

installDockableDragSource(DockableDragSource)

uninstallDockableDragSources

public void uninstallDockableDragSources(DockableDragSource[] sources)

Uninstalls multiple drag sources.

See Also:

uninstallDockableDragSource(DockableDragSource)

installDockableDragSource

public void installDockableDragSource(DockableDragSource source)

This method is used by DockableContainers in order to register their DockableDragSource(s) to the OldDragControler.

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

uninstallDockableDragSource

public void uninstallDockableDragSource(DockableDragSource source)

This method is used by DockableContainers in order to unregister their DockableDragSource(s) to the OldDragControler.

Removes the MouseListener and MouseMotionListener added on installDockableDragSource()

See Also:

installDockableDragSource(DockableDragSource)

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.

writeXML

public void writeXML(java.io.OutputStream stream)
              throws java.io.IOException

Saves the current desktop configuration into an XML stream.

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

As of version 2.1, this method delegates the work to DockingContext.writeXML, which will export every dekstop sharing the same context (and not only this one)

Throws:

java.io.IOException

See Also:

readXML(InputStream)

readXML

public void readXML(java.io.InputStream in)
             throws javax.xml.parsers.ParserConfigurationException,
                    java.io.IOException,
                    org.xml.sax.SAXException

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

Throws:

javax.xml.parsers.ParserConfigurationException

java.io.IOException

org.xml.sax.SAXException

See Also:

writeXML(OutputStream), registerDockable(Dockable)

clear

public void clear()

removes every dockables from this desktop

addDockable

public void addDockable(Dockable dockable)

Adds a dockable in the docking desktop.

This method can be used mainly in two situations :

• the desktop is empty (when not empty, you can use split() or createTab() to add a dockable relatively to another)
• the dockable is currently closed, and it must be shown again
• note that if the desktop is not empty, the dockable will be added in the bottom of the desktop (equivalent to addDockable(dockable 0,0.8,1,0.2)).

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

• find the splitter containing the given center (x + width/2, y + height/2) of the dockable
• try to respect the x and y, constraints.
• try to respect the width and height constraints.
• sub-split the splitter (horizontally or vertically) zone and position the Dockable in the most appropriate zone (top, left, bottom, right).

Parameters:

dockable - the dockable to add (must not be already visible)

position - relative position of the dockable

Throws:

java.lang.IllegalArgumentException - if the dockable already belongs to the desktop containment hierarchy.

replace

public void replace(Dockable base,
           Dockable replacer)

Replaces a dockable by another one.

Useful for example to reserve some space on a desktop by using a "placeholder' when other dockables aren't visible (Multiple Tabbed Document Interface with always a dockable visible even when no document is loaded).

Implementation note : this method assumes only the "base" dockable is visible (the replacer must be in the CLOSED state). It also assumes the base dockable isn't a compound dockable. These limitations will be removed in a later release.

There is currently no DnD gesture associated to this action (although the "HotSwap" gesture would be a good candidate). So this method currently doesn't trigger any event (state change, action), yet it could change later.

Throws:

java.lang.IllegalArgumentException - when dockables aren't in the appropriate state or hierarchy.

Since:

2.1

addDockable

public void addDockable(CompoundDockable base,
               Dockable dockable)

Adds a dockable inside a compound dockable.

This is the method to start a nesting hierarchy inside a compound dockable (once the first dockable is added, you add subsequent dockables with standard split/createTab methods)

• note that if the compound dockable is not empty, this method will raise an exception.

Since:

2.1

getPreferredSize

public java.awt.Dimension getPreferredSize()

Evaluates and returns the preferred size of the desktop, according to its contents and auto-hide borders.

Overrides:

getPreferredSize in class javax.swing.JComponent

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

removeDockableStateChangeListener

public void removeDockableStateChangeListener(DockableStateChangeListener listener)

Removes a DockableStateChangeListener from this desktop.

addDockableStateWillChangeListener

public void addDockableStateWillChangeListener(DockableStateWillChangeListener listener)

Adds a new DockableStateWillChangeListener to this desktop.

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

removeDockableStateWillChangeListener

public void removeDockableStateWillChangeListener(DockableStateWillChangeListener listener)

Removes a DockableStateWillChangeListener from this desktop.

addDockingActionListener

public void addDockingActionListener(DockingActionListener listener)

Adds a new DockingActionListener to this desktop.

DockingAction Events are triggered before and after any docking action (split, tab, close, hide...) and allow for precise tracking (and vetoing) of these operations.

See Also:

removeDockingActionListener(DockingActionListener)

removeDockingActionListener

public void removeDockingActionListener(DockingActionListener listener)

Removes a DockingActionListener from this desktop.

See Also:

addDockingActionListener(DockingActionListener)

addDockableSelectionListener

public void addDockableSelectionListener(DockableSelectionListener listener)

Adds a new DockableSelectionListener to this desktop.

DockableSelection Events are triggered when a dockable takes the focus.

removeDockableSelectionListener

public void removeDockableSelectionListener(DockableSelectionListener listener)

Removes a DockableSelectionListener from this desktop.

addHiddenDockable

public void addHiddenDockable(Dockable dockable,
                     RelativeDockablePosition dockedPosition)

Registers and add a dockable on an auto-hide 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.setAutoHideBorder mehod

dockedPosition - relative positionning (may be null) indicating where to dock the dockable when leaving its auto-hide border.

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.

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.

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.

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

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

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.

getDesktopName

public java.lang.String getDesktopName()

Returns the name of this desktop (used by workspace management)

setDesktopName

public void setDesktopName(java.lang.String desktopName)

Updates the name of this desktop (used by workspace management)

getContext

public DockingContext getContext()

Returns the docking context used by this desktop (might be shared with other desktop).

Since:

2.1

setContext

public void setContext(DockingContext context)

Updates the docking context used by this desktop.

Warning : this method should only be used by the framework itself : changing a context "live" can have unpredicted and undesired side effect.

Since:

2.1

getMaximizedDockable

public Dockable getMaximizedDockable()

returns the currently maximized dockable (or null if no dockable is in that state)