pub.vlsolutions.swing.docking

Class DockingContext

java.lang.Object

pub.vlsolutions.swing.docking.DockingContext

public class DockingContext
extends java.lang.Object

A context that can be shared by multiple docking desktops.

Keeps track of registered dockables and manages import export.

A DockingContext can be seen as the top-most grouping element of docking (as DockingDesktop can be contained is a context), and as such, all methods related to workspace management have been promoted to this class.

Since:

2.1

Author:

Lilian Chamontin, VLSolutions

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.HashMap<Dockable,DockableState>	dockableStates inner state of the dockables
protected java.util.ArrayList<Dockable>	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

Constructor Summary

Constructors

Constructor and Description
DockingContext() Constructs a new DockingContext

Method Summary

Methods

Modifier and Type	Method and Description
void	addDesktop(DockingDesktop desktop) Adds a desktop to this context
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)
void	close(Dockable dockable) Close this dockable
java.util.ArrayList<DockingDesktop>	getDesktopList() Returns a list of the desktops sharing this context
Dockable	getDockableByKey(java.lang.String dockKey) Returns the (registered) dockable corresponding to the given key id, or null if not found
DockableResolver	getDockableResolver() Returns the dockable resolver used by this context (or null if none defined)
DockableState[]	getDockables() Creates and returns an array of all registered dockable with their current state.
java.util.ArrayList<Dockable>	getDockablesByState(DockingDesktop desktop, DockableState.Location state) constructs and returns the list of dockables corresponding to a desktop, at a specific state
DockableState	getDockableState(Dockable dockable) Returns the current state of a dockable (CLOSED, HIDDEN, DOCKED, MAXIMIZED, FLOATING)
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 managed by a DockingDesktop.
void	removeDesktop(DockingDesktop desktop) Removes a desktop from this context
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)
void	setDockableResolver(DockableResolver dockableResolver) Updates the dockable resolver used by this context (can be set to null)
void	setDockableState(Dockable dockable, DockableState state) Updates the current state of a dockable
void	unregisterDockable(Dockable dockable) Unregisters the dockable, which can be garbage collected (no longer used by docking desktops.
void	writeXML(java.io.OutputStream stream) Saves the current desktop configuration into an XML stream.

Methods inherited from class java.lang.Object

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

Field Detail

registeredDockables

protected java.util.ArrayList<Dockable> 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

dockableStates

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

inner state of the dockables

Constructor Detail

DockingContext

public DockingContext()

Constructs a new DockingContext

Method Detail

addDesktop

public void addDesktop(DockingDesktop desktop)

Adds a desktop to this context

removeDesktop

public void removeDesktop(DockingDesktop desktop)

Removes a desktop from this context

registerDockable

public void registerDockable(Dockable dockable)

Every dockable must be registered in order to be managed by a DockingDesktop.

if this method is invoked and the dockable is already registered, nothing happens. if the dockable is still unknown, it is added to the dockables set and (since 2.1.3) its state is set to CLOSED (prior 2.1.3, the state was null).

unregisterDockable

public void unregisterDockable(Dockable dockable)

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

close

public void close(Dockable dockable)

Close this dockable

getDockableState

public DockableState getDockableState(Dockable dockable)

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

setDockableState

public void setDockableState(Dockable dockable,
                    DockableState state)

Updates the current state of a dockable

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.

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

writeXML

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

Saves the current desktop configuration into an XML stream.

The workspace is composed of every desktop layouts associated with this context (desktops are identified by their 'desktopName' property).

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

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 desktops associated to this context are totally reconfigured with posiibly different dockables 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.

Note : altenatively (since 2.1.2) if a DockableResolver has been set, it will be use to auto-register the new dockables encountered along the stream.

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

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

Note : When multiple desktops are loaded from the stream, the context uses their "desktopName" property (desk.getDesktopName()) to identify them.

Throws:

javax.xml.parsers.ParserConfigurationException

java.io.IOException

org.xml.sax.SAXException

See Also:

writeXML(OutputStream), registerDockable(Dockable), setDockableResolver(DockableResolver)

getDockablesByState

public java.util.ArrayList<Dockable> getDockablesByState(DockingDesktop desktop,
                                                DockableState.Location state)

constructs and returns the list of dockables corresponding to a desktop, at a specific state

getDockableByKey

public Dockable getDockableByKey(java.lang.String dockKey)

Returns the (registered) dockable corresponding to the given key id, or null if not found

Note : since VLDocking 2.1.2, this method also tries to use its DockableResolver if null would have been returned.

See Also:

DockableResolver

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.

addDockingActionListener

public void addDockingActionListener(DockingActionListener listener)

removeDockingActionListener

public void removeDockingActionListener(DockingActionListener listener)

getDesktopList

public java.util.ArrayList<DockingDesktop> getDesktopList()

Returns a list of the desktops sharing this context

getDockableResolver

public DockableResolver getDockableResolver()

Returns the dockable resolver used by this context (or null if none defined)

Since:

2.1.2

setDockableResolver

public void setDockableResolver(DockableResolver dockableResolver)

Updates the dockable resolver used by this context (can be set to null)

Since:

2.1.2