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.
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 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 :
- 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).
dockable
- the dockable to add (must not be already visible)position
- relative position of the dockable
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.
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.
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.
dockable
- the dockable to add (to select the border where the dockable
will be positionned, use the DockKey.setAutoHideBorder mehoddockedPosition
- 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.
base
- an already tabbed dockablenewTab
- a dockable to add to the tab group
clear
public void clear()
removes every dockables from this desktop
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
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.
base
- the reference dockabledockable
- 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.
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 addorder
- 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.
getContext
public DockingContext getContext()
Returns the docking context used by this desktop (might be shared with other desktop).
getDesktopName
public String getDesktopName()
Returns the name of this desktop (used by workspace management)
getDockableState
public DockableState getDockableState(Dockable dockable)
Returns the current state of a dockable (CLOSED, HIDDEN, DOCKED, MAXIMIZED, FLOATING)
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]
- an array of DockableState
getDockingFrameworkBuildDate
public static String getDockingFrameworkBuildDate()
Returns a String containing the release date of the current version.
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.
getDockingPanelInsets
public Insets getDockingPanelInsets()
recalculates and returns the insets taken by autoexpand
borders around the docking panel.
getMaximizedDockable
public Dockable getMaximizedDockable()
returns the currently maximized dockable
(or null if no dockable is in that state)
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.
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.
isOpaqueContents
public boolean isOpaqueContents()
Returns whether this desktop's contents are opaque or not.
Default value is true (opaque).
setOpaqueContents(boolean).
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).
move
public void move(Dockable base,
Dockable dockable,
DockingConstants.Split position)
Moves a dockable to another position (relative to a destination dockable)
base
- must be a visible Dockabledockable
- must be a registered Dockableposition
- relative positionning
readXML
public void readXML(InputStream in)
throws ParserConfigurationException,
IOException,
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
DockKey
s 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.
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
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.
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.
removeDockingActionListener
public void removeDockingActionListener(DockingActionListener listener)
Removes a DockingActionListener 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.
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.
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)
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)
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.
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.
setDesktopName
public void setDesktopName(String desktopName)
Updates the name of this desktop (used by workspace management)
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.
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.
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).
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.
base
- an already docked DockablenewDockable
- the added dockableposition
- position of newDockable relative to base
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
split
method.
base
- the reference component (a dockablecontainer or a split container)dockablesContainer
- the dockable containerposition
- the position of dockable
.
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
split
method.
base
- the reference component (a dockablecontainer or a split container)dockable
- the dockable to addposition
- 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()
uninstallDockableDragSources
public void uninstallDockableDragSources(DockableDragSource[] sources)
Uninstalls multiple drag sources.
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
writeXML
public void writeXML(OutputStream stream)
throws 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)