public class DefaultDockingPort extends javax.swing.JPanel implements DockingPort, DockingConstants
Container
that implements the DockingPort
interface. It provides a default implementation of DockingPort
to
allow ease of development within docking-enabled applications.
The DefaultDockingPort
handles docking in one of three ways. If the
port is empty, then all incoming Dockables
are docked to the CENTER
region. If the port is not empty, then all incoming Dockables
docked
to the CENTER region are embedded within a JTabbedPane
. All incoming
Dockables
docked to an outer region (NORTH, SOUTH, EAST, and WEST) of
a non-empty port are placed into a split layout using a JSplitPane
.
For centrally docked Components
, the immediate child of the
DefaultDockingPort
may or may not be a JTabbedPane
. If
isSingleTabAllowed()
returns true
for the current
DefaultDockingPort
, then the immediate child returned by
getDockedComponent()
will return a JTabbedPane
instance even
if there is only one Dockable
embedded within the port. If there is a
single Dockable
in the port, but isSingleTabAllowed()
returns
false
, then getDockedComponent()
will return the
Component
that backs the currently docked Dockable
, returned
by the Dockable's
getComponent()
method.
isSingleTabAllowed()
is a scoped property that may apply to this
port, all ports across the JVM, or all ports within a user defined scope.
getDockedComponent()
will return a JTabbedPane
at all times
if there is more than one centrally docked Dockable
within the port,
and all docked Components
will reside within the tabbed pane.
Components that are docked in the NORTH, SOUTH, EAST, or WEST regions are
placed in a JSplitPane
splitting the layout of the
DockingPort
between child components. Each region of the
JSplitPane
contains a new DefaultDockingPort
, which, in
turn, contains the docked components. In this situation,
getDockedComponent()
will return a JSplitPane
reference.
A key concept that drives the DefaultDockingPort
, then, is the
notion that this DockingPort
implementation may only ever have one
single child component, which may or may not be a wrapper for other child
components. Because JSplitPane
contains child
DefaultDockingPorts
, each of those DefaultDockingPorts
is
available for further sub-docking operations.
Since a DefaultDockingPort
may only contain one child component,
there is a container hierarchy to manage tabbed interfaces, split layouts,
and sub-docking. As components are removed from this hierarchy, the hierarchy
itself must be reevaluated. Removing a component from a child
DefaultDockingPort
within a JSplitPane
renders the child
DefaultDockingPort
unnecessary, which, in turn, renders the notion of
splitting the layout with a JSplitPane
unnecessary (since there are
no longer two components to split the layout between). Likewise, removing a
child component from a JTabbedPane
such that there is only one child
left within the JTabbedPane
removes the need for a tabbed interface
to begin with.
When the DockingManager
removes a component from a
DockingPort
via DockingManager.undock(Dockable dockable)
it
uses a call to undock()
on the current DockingPort
.
undock()
automatically handles the reevaluation of the container
hierarchy to keep wrapper-container usage at a minimum. Since
DockingManager
makes this callback automatic, developers normally
will not need to call this method explicitly. However, when removing a
component from a DefaultDockingPort
using application code,
developers should keep in mind to use undock()
instead of
remove()
.
Border management after docking and undocking operations are accomplished
using a BorderManager
. setBorderManager()
may be used to set
the border manager instance and customize border management.
Modifier and Type | Class and Description |
---|---|
protected class |
DefaultDockingPort.PortLayout |
javax.swing.JPanel.AccessibleJPanel
javax.swing.JComponent.AccessibleJComponent
java.awt.Container.AccessibleAWTContainer
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
DockingListener.Stub
Modifier and Type | Field and Description |
---|---|
protected java.util.ArrayList |
dockingListeners |
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
INITIAL_TAB_POSITION
ACTIVE_WINDOW, BOTTOM, CENTER, CENTER_REGION, CLOSE_ACTION, DEFAULT_PERSISTENCE_KEY, DOCKING_ID, EAST_REGION, HEAVYWEIGHT_DOCKABLES, HORIZONTAL, LEFT, MOUSE_PRESSED, NORTH_REGION, PERMANENT_FOCUS_OWNER, PIN_ACTION, REGION, RIGHT, SOUTH_REGION, TOP, UNINITIALIZED, UNINITIALIZED_RATIO, UNKNOWN_REGION, UNSPECIFIED_SIBLING_PREF, VERTICAL, WEST_REGION
Constructor and Description |
---|
DefaultDockingPort()
Creates a new
DefaultDockingPort with a persistent ID equal to
the String value of this a random UUID. |
DefaultDockingPort(java.lang.String id)
Creates a new
DefaultDockingPort with the specified persistent
ID. |
Modifier and Type | Method and Description |
---|---|
java.awt.Component |
add(java.awt.Component comp)
Overridden to set the currently docked component.
|
java.awt.Component |
add(java.awt.Component comp,
int index)
Overridden to set the currently docked component.
|
void |
add(java.awt.Component comp,
java.lang.Object constraints)
Overridden to set the currently docked component.
|
void |
add(java.awt.Component comp,
java.lang.Object constraints,
int index)
Overridden to set the currently docked component.
|
java.awt.Component |
add(java.lang.String name,
java.awt.Component comp)
Overridden to set the currently docked component.
|
void |
addDockingListener(DockingListener listener)
Adds a
DockingListener to observe docking events for this
DockingPort . |
void |
clear()
Removes all
Dockables from this DockingPort . |
protected BorderManager |
createBorderManager()
Creates a standard border manager for this docking port.
|
protected java.awt.LayoutManager |
createLayout() |
protected javax.swing.JTabbedPane |
createTabbedPane()
If this method returns
null , implementations may throw
NullPointerExceptions. |
boolean |
dock(java.awt.Component comp,
java.lang.String region)
Docks the specified component within the specified region.
|
boolean |
dock(Dockable dockable,
java.lang.String region)
Docks the specified
Dockable within the specified region. |
void |
dockingCanceled(DockingEvent evt)
No operation.
|
void |
dockingComplete(DockingEvent evt)
Requests activation for the newly docked Dockable.
|
void |
dragStarted(DockingEvent evt)
No operation.
|
void |
dropStarted(DockingEvent evt)
No operation.
|
LayoutNode |
exportLayout()
Returns a
LayoutNode containing metadata that describes the
current layout contained within this DefaultDockingPort . |
BorderManager |
getBorderManager()
Returns the currently intalled
BorderManager . |
protected Dockable |
getCenterDockable() |
java.awt.Component |
getComponent(java.lang.String region)
Returns the
Component currently docked within the specified
region . |
Dockable |
getDockable(java.lang.String region)
Returns the
Dockable currently docked within the specified
region . |
Dockable |
getDockableAt(java.awt.Point location)
Returns the direct child
Dockable located at the specified
Point . |
java.util.Set |
getDockables()
Returns all
Dockables docked within this DockingPort and
all sub-DockingPorts . |
protected java.util.Set |
getDockableSet(int depth,
int level,
java.lang.Class desiredClass) |
java.awt.Component |
getDockedComponent()
Returns the child
Component currently embedded within with
DockingPort . |
DockingListener[] |
getDockingListeners()
Returns an array of all
DockingListeners added to this
DockingPort . |
DockingPortPropertySet |
getDockingProperties()
Returns a
DockingPortPropertySet instance associated with this
DockingPort . |
DockingStrategy |
getDockingStrategy()
Returns the
DockingStrategy used by this DockingPort . |
protected int |
getInitTabPlacement() |
java.lang.String |
getPersistentId()
Returns a
String identifier that is unique to
DockingPorts within a JVM instance, but persistent across JVM
instances. |
java.lang.String |
getRegion(java.awt.Point location)
Returns the docking region within this
DockingPort that contains
the specified Point . |
RegionChecker |
getRegionChecker()
Returns the
RegionChecker currently used by this
DockingPort . |
void |
importLayout(LayoutNode node)
Clears out the existing layout within this
DockingPort and
reconstructs a new layout based upon the specified LayoutNode . |
void |
installMaximizedDockable(Dockable dockable)
Asks this
DockingPort to temporarily install the specified
Dockable and maximize its component. |
boolean |
isDockingAllowed(java.awt.Component comp,
java.lang.String region)
Returns
true if docking is allowed for the specified
Component within the supplied region , false
otherwise. |
boolean |
isParentDockingPort(java.awt.Component comp)
Indicates whether or not the specified component is docked somewhere
within this
DefaultDockingPort . |
boolean |
isRoot()
Returns a boolean indicating whether or not this
DockingPort is
nested within another DockingPort . |
boolean |
isSingleTabAllowed()
Returns
true if single tabs are allowed within this
DockingPort , false otherwise. |
boolean |
isTabsAsDragSource()
Returns
true if drag-to-dock support is enabled for tabs and
their associated Dockables , false otherwise. |
protected boolean |
isValidDockableChild(java.awt.Component c,
java.lang.Class desiredClass) |
protected boolean |
isValidDockingRegion(java.lang.String region) |
void |
paint(java.awt.Graphics g)
Overridden to provide enhancements during drag operations.
|
void |
releaseForMaximization(Dockable dockable)
Asks this
DockingPort to temporarily release its child
Dockable for use by another DockingPort to achieve
maximization. |
void |
remove(int index)
Overridden to decorate superclass method, keeping track of internal
docked-component reference.
|
void |
removeAll()
Overridden to decorate superclass method, keeping track of internal
docked-component reference.
|
void |
removeDockingListener(DockingListener listener)
Removes the specified
DockingListener from this
DockingPort . |
void |
returnFromMaximization()
Notifies this
DockingPort that the Dockable previously
released for maximization via a call to
DockingPort.releaseForMaximization(Dockable) is now ready to be returned to
its original state inside this DockingPort . |
void |
setBorderManager(BorderManager mgr)
Sets the currently installed
BorderManager . |
void |
setDragInProgress(boolean inProgress)
This method is used internally by the framework to notify
DefaultDockingPorts whether a drag operation is or is not
currently in progress and should not be called by application-level
developers. |
void |
setPersistentId(java.lang.String id)
Sets the persisent ID to be used for this
DockingPort . |
void |
setRoot(boolean root)
This method is used internally by the framework to notify
DefaultDockingPorts whether they are "root" DockingPorts
according to the rules specified by isRoot() on the
DockingPort interface. |
void |
setSingleTabAllowed(boolean allowed)
Sets the "single tab" property for this
DockingPort , allowing or
disallowing a single Dockable within the DockingPort to
appear within a tabbed layout. |
void |
setTabsAsDragSource(boolean enabled)
Enables or disables drag support for docking operations on the tabs used
within an embedded tabbed layout.
|
boolean |
undock(java.awt.Component comp)
Undocks the specified
Component and returns a boolean indicating
the success of the operation. |
void |
undockingComplete(DockingEvent evt)
No operation.
|
void |
undockingStarted(DockingEvent evt)
No operation.
|
void |
uninstallMaximizedDockable()
Notifies this
DockingPort that the Dockable previously
installed for maximization via a call to
DockingPort.installMaximizedDockable(Dockable) should now be returned to its
original DockingPort and that this DockingPort should
return to its original state from before the call to
DockingPort.installMaximizedDockable(Dockable) . |
protected void |
updateTab(Dockable dockable) |
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
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, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, 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
addContainerListener, addImpl, 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
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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getClientProperty, putClientProperty
public DefaultDockingPort()
DefaultDockingPort
with a persistent ID equal to
the String
value of this a random UUID.UUID
public DefaultDockingPort(java.lang.String id)
DefaultDockingPort
with the specified persistent
ID. If id
is null
, then the String
value of this
Object's
hash code is used. The persistent ID will be the same
value returned by invoking getPersistentId()
for this
DefaultDockingPort
.id
- the persistent ID for the new DefaultDockingPort
instance.protected java.awt.LayoutManager createLayout()
protected BorderManager createBorderManager()
This method is called from the constructor.
public java.awt.Component add(java.awt.Component comp)
add
in class java.awt.Container
comp
- the component to be addedpublic java.awt.Component add(java.awt.Component comp, int index)
add
in class java.awt.Container
comp
- the component to be addedindex
- the position at which to insert the component, or -1
to append the component to the endpublic void add(java.awt.Component comp, java.lang.Object constraints)
add
in class java.awt.Container
comp
- the component to be addedconstraints
- an object expressing layout contraints for this componentpublic void add(java.awt.Component comp, java.lang.Object constraints, int index)
add
in class java.awt.Container
comp
- the component to be addedconstraints
- an object expressing layout contraints for thisindex
- the position in the container's list at which to insert the
component; -1
means insert at the endpublic java.awt.Component add(java.lang.String name, java.awt.Component comp)
add
in class java.awt.Container
name
- the name of the Component
to be added.comp
- the Component
to add.public boolean isDockingAllowed(java.awt.Component comp, java.lang.String region)
true
if docking is allowed for the specified
Component
within the supplied region
, false
otherwise. It is important to note that success of a docking operation
relies on many factors and a return value of true
from this
method does not necessarily guarantee that a call to dock()
will
succeed. This method merely indicates that the current
DockingPort
does not have any outstanding reason to block a
docking operation with respect to the specified Component
and
region
.
If comp
is null
or region
is invalid according to
DockingManager.isValidDockingRegion(String region)
, then this
method returns false
.
If this DockingPort
is not already the parent DockingPort
for the specified Component
, then this method returns
true
.
If this DockingPort
is already the parent DockingPort
for
the specified Component
, then a check is performed to see if
there is a tabbed layout. Tabbed layouts may contain multiple
Dockables
, and thus the tab ordering may be rearranged, or
shifted into a split layout. If comp
is the only docked
Component
within this DockingPort
, then this method
returns false
since the layout cannot be rearranged. Otherwise,
this method returns true
.
isDockingAllowed
in interface DockingPort
comp
- the Component
whose docking availability is to be
checkedregion
- the region to be checked for docking availability for the
specified Component
.true
if docking is allowed for the specified
Component
within the supplied region
,
false
otherwise.DockingPort.isDockingAllowed(Component, String)
,
DockingManager.isValidDockingRegion(String)
,
isParentDockingPort(Component)
public java.lang.String getRegion(java.awt.Point location)
DockingPort
that contains
the specified Point
. Valid return values are those regions
defined in DockingConstants
and include NORTH_REGION
,
SOUTH_REGION
, EAST_REGION
, WEST_REGION
,
CENTER_REGION
, and UNKNOWN_REGION
.
If location
is null
, then UNKNOWN_REGION
is
returned.
This method gets the RegionChecker
for this DockingPort
by calling getRegionChecker()
. It then attempts to locate the
Dockable
at the specified location
by calling
getDockableAt(Point location)
.
This method defers processing to getRegion(Component c, Point p)
for the current RegionChecker
. If a Dockable
was found
at the specified Point
, then the location of the Point
is translated to the coordinate system of the Component
for the
embedded Dockable
and that Component
and modified
Point
are passed into getRegion(Component c, Point p)
}
for the current RegionChecker
. If no Dockable
was found,
then the specified Point
is left unmodified and this
DockingPort
and the supplied Point
are passed to
getRegion(Component c, Point p)
} for the current
RegionChecker
.
getRegion
in interface DockingPort
location
- the location within this DockingPort
to examine for a
docking region.DockingPort
that contains
the specified Point
getRegionChecker()
,
getDockableAt(Point)
,
Dockable.getComponent()
,
RegionChecker.getRegion(Component, Point)
public RegionChecker getRegionChecker()
RegionChecker
currently used by this
DockingPort
. This method retrieves the
DockingPortPropertySet
instance for this DockingPort
by
calling getDockingProperties()
. It then returns by invoking
getRegionChecker()
on the resolved DockingPortPropertySet
.RegionChecker
currently used by this
DockingPort
.getDockingProperties()
,
DockingPortPropertySet.getRegionChecker()
public Dockable getDockableAt(java.awt.Point location)
Dockable
located at the specified
Point
. If location
is null
, or this
DockingPort
is empty, then a null
reference is returned.
If this DockingPort
contains a split layout, then any nested
Dockables
will be within a sub-DockingPort
and not a
direct child of this DockingPort
. Therefore, if
getDockedComponent()
returns a JSplitPane
, then this
method will return a null
reference.
If this DockingPort
contains a tabbed layout, then the
JTabbedPane
returned by getDockedComponent()
will be
checked for a Dockable
at the specified Point
.
location
- the location within the DockingPort
to test for a
Dockable
.Dockable
located at the specified
Point
.getDockedComponent()
,
DockingManager.getDockable(Component)
,
Container.getComponentAt(int x, int y)
public java.awt.Component getComponent(java.lang.String region)
Component
currently docked within the specified
region
.
If this DockingPort
has either a single child Dockable
or
a tabbed layout, then the supplied region must be CENTER_REGION
or this method will return a null
reference. If there is a single
child Dockable
, then this method will return the same
Component
as returned by getDockedComponent()
. If there
is a tabbed layout, then this method will return the Component
in
the currently selected tab.
If this DockingPort
has a split layout, then a check for
CENTER_REGION
will return a null
reference. For outer
regions (NORTH_REGION
, SOUTH_REGION
,
EAST_REGION
, or WEST_REGION
), the supplied region
parameter must match the orientation of the embedded JSplitPane
.
Thus for a vertically oriented split pane, checks for EAST_REGION
and WEST_REGION
will return a null
reference. Likewise,
for a horizontally oriented split pane, checks for NORTH_REGION
and SOUTH_REGION
will return a null
reference.
Outer regions are mapped to corresponding split pane regions.
NORTH_REGION
maps to the split pane's top component,
SOUTH_REGION
maps to the bottom, EAST_REGION
maps to the
right, and WEST_REGION
maps to the left. The sub-DockingPort
for the split pane region that corresponds to the specified
region
parameter will be resolved and this method will return
that Component
retrieved by calling its
getDockedComponent()
method. Note that the
getDockedComponent()
call to a sub- DockingPort
implies
that the JTabbedPane
or JSplitPane
for the sub-port may
be returned if the sub-port contains multiple Dockables
.
If this DockingPort
is empty, then this method returns a
null
reference.
getComponent
in interface DockingPort
region
- the region to be checked for a docked Component
Component
docked within the specified region.DockingPort.getComponent(String)
,
getDockedComponent()
public Dockable getDockable(java.lang.String region)
Dockable
currently docked within the specified
region
. This method dispatches to
getComponent(String region)
to retrieve the Component
docked within the specified region and returns its associated
Dockable
via DockingManager.getDockable(Component comp)
.
There are somewhat strict semantics associated with retrieving the
Component
in a particular docking region. API documentation for
getComponent(String region)
should be referenced for a listing of
the rule set. If region
is invalid according to
DockingManager.isValidDockingRegion(String region)
, then this
method returns a null
reference.
getDockable
in interface DockingPort
region
- the region to be checked for a docked Dockable
Dockable
docked within the specified region.DockingPort.getDockable(String)
,
getComponent(String)
,
getDockedComponent()
,
DockingManager.getDockable(Component)
,
DockingManager.isValidDockingRegion(String)
protected javax.swing.JTabbedPane createTabbedPane()
null
, implementations may throw
NullPointerExceptions. Do not expect NPE checking.protected void updateTab(Dockable dockable)
public DockingStrategy getDockingStrategy()
DockingStrategy
used by this DockingPort
.
This method dispatches to getDockingStrategy(Object obj)
,
passing this
as an argument. By default,
DefaultDockingStrategy
is used unless a different
DockingStrategy
has been assigned by the end user for
DefaultDockingPort
.getDockingStrategy
in interface DockingPort
DockingStrategy
used by this DockingPort
.DockingPort.getDockingStrategy()
,
DockingManager.getDockingStrategy(Object)
public void clear()
Dockables
from this DockingPort
. Internally,
this method dispatches to removeAll()
. This ensures that not
only docked Components
are removed, that that all wrapper
containers such as JTabbedPanes
, JSplitPanes
, and sub-DockingPorts
are removed as well.clear
in interface DockingPort
DockingPort.clear()
,
removeAll()
public boolean dock(java.awt.Component comp, java.lang.String region)
Dockable
associated with the specified
Component
by invoking
DockingManager.getDockable(Component comp)
. Processing is then
dispatched to dock(Dockable dockable, String region)
.
If no Dockable
is resolved for the specified Component
,
then this method attempts to register the Component
as a
Dockable
automatically by calling
DockingManager.registerDockable(Component comp)
.
If either comp
or region
region are null
, then
this method returns false
. Otherwise, this method returns a
boolean indicating the success of the docking operation based upon
dock(Dockable dockable, String region)
.
dock
in interface DockingPort
comp
- the Component
to be docked within this
DockingPort
region
- the region within this DockingPort
to dock the
specified Component
true
if the docking operation was successful,
false
otherwise.DockingPort.dock(Component, String)
,
dock(Dockable, String)
,
DockingManager.getDockable(Component)
,
DockingManager.registerDockable(Component)
public boolean dock(Dockable dockable, java.lang.String region)
Dockable
within the specified region. The
Component
used for docking is returned by calling
getComponent()
on the specified Dockable
. This method
returns false
immediately if the specified Dockable
is
null
or if
isDockingAllowed(Component comp, String region)
returns
false
.
If this DockingPort
is currently empty, then the Dockable
is docked into the CENTER_REGION
, regardless of the supplied
region
parameter's value.
If isSingleTabAllowed()
returns false
and the
DockingPort
is emtpy, then the Dockable
will be added
directly to the DockingPort
and will take up all available space
within the DockingPort
. In this case, subsequent calls to
getDockedComponent()
will return the dockable Component
.
If isSingleTabAllowed()
returns true
and the
DockingPort
is emtpy, then a JTabbedPane
will be added
directly to the DockingPort
and will take up all available space
within the DockingPort
. The dockable Component
will be
added as a tab within the tabbed pane. In this case, subsequent calls to
getDockedComponent()
will return the JTabbedPane
.
If the DockingPort
is not empty, and the specified region
is CENTER_REGION
, then the dockable Component
will be
added to the JTabbedPane
returned by getDockedComponent()
.
If this DockingPort
only contained a single dockable
Component
without a tabbed pane, then the currently docked
Component
is removed, a JTabbedPane
is created and added,
and both the old Component
and the new one are added to the
JTabbedPane
. In this case, subsequent calls to
getDockedComponent()
will return the JTabbedPane
.
If the DockingPort
is not empty, and the specified region
is NORTH_REGION
, SOUTH_REGION
, EAST_REGION
, or
WEST_REGION
, then the currently docked Component
is
removed and replaced with a JSplitPane
. Two new
DefaultDockingPorts
are created as sub-ports and are added to
each side of the JSplitPane
. The previously docked
Component
is docked to the CENTER_REGION of one of the sub-ports
and the new Component
is added to the other. In this case,
subsequent calls to getDockedComponent()
will return the
JSplitPane
. In this fasion, the sub-ports will now be capable of
handling further sub-docking within the layout.
JSplitPane
and sub-DockingPort
creation are delegated to
the DockingStrategy
returned by getDockingStrategy()
.
Initial splitpane divider location is also controlled by this
DockingStrategy
.
dock
in interface DockingPort
dockable
- the Dockable
to be docked within this
DockingPort
region
- the region within this DockingPort
to dock the
specified Dockable
true
if the docking operation was successful,
false
otherwise.DockingPort.dock(Dockable, String)
,
isDockingAllowed(Component, String)
,
getDockedComponent()
,
getDockingStrategy()
,
DockingStrategy.createDockingPort(DockingPort)
,
DockingStrategy.createSplitPane(DockingPort, String)
,
DockingStrategy.getInitialDividerLocation(DockingPort, JSplitPane)
,
DockingStrategy.getDividerProportion(DockingPort, JSplitPane)
public java.awt.Component getDockedComponent()
Component
currently embedded within with
DockingPort
. If the DockingPort
is empty, then this
method returns a null
reference. If there is a single
Dockable
docked within it with no tabbed layout, then the
Component
for that Dockable
is returned per its
getComponent()
method. If there is a tabbed layout present, then
a JTabbedPane
is returned. If there is a split layout present,
then a JSplitPane
is returned.getDockedComponent
in interface DockingPort
DockingPort.getDockedComponent()
public java.lang.String getPersistentId()
String
identifier that is unique to
DockingPorts
within a JVM instance, but persistent across JVM
instances. This is used for configuration mangement, allowing the JVM to
recognize a DockingPort
instance within an application instance,
persist the ID, and recall it in later application instances. The ID
should be unique within an appliation instance so that there are no
collisions with other DockingPort
instances, but it should also
be consistent from JVM to JVM so that the association between a
DockingPort
instance and its ID can be remembered from session to
session.
The value returned by this method will come from the most recent call to
setPersistentId(String id)
. If
setPersistentId(String id)
was invoked with a null
argument, then the String
verion of this DockingPort's
hash code is used. Therefore, this method will never return a
null
reference.
getPersistentId
in interface DockingPort
DockingPort
DockingPort.getPersistentId()
,
setPersistentId(String)
,
DockingManager.getDockingPort(String)
public void setPersistentId(java.lang.String id)
DockingPort
. If
id
is null
, then the String
value of this
DockingPort's
hash code is used.
DockingPorts
are tracked by persistent ID within
DockingManager
. Whenever this method is called, the
DockingManager's
tracking mechanism is automatically upated for
this DockingPort
.
setPersistentId
in interface DockingPort
id
- the persistent ID to be used for this DockingPort
getPersistentId()
,
DockingManager.getDockingPort(String)
,
DockingPortTracker.updateIndex(DockingPort)
public boolean isSingleTabAllowed()
true
if single tabs are allowed within this
DockingPort
, false
otherwise.
Generally the tabbed interface does not appear until two or more
Dockables
are docked to the CENTER_REGION
of the
DockingPort
and tabs are required to switch between them. When
there is only a single Dockable
within the DockingPort
,
the default behavior for the dockable Component
to take up all of
the space within the DockingPort
.
If this method returns true
, then a single Dockable
within this DockingPort
will reside within a tabbed layout that
contains only one tab.
The value returned by this method is a scoped property. This means there
may be many different "scopes" at which the single-tab property may be
set. For instance, a "global" setting may override the individual setting
for this DockingPort
, and this DockingPort's
particular
setting may override the global default setting.
org.flexdock.docking.props.PropertyManager
should be referenced
for further information on scoped properties.
true
if single tabs are allowed within this
DockingPort
, false
otherwise.setSingleTabAllowed(boolean)
,
DockingManager.isSingleTabsAllowed()
,
DockingManager.setSingleTabsAllowed(boolean)
,
PropertyManager
,
DockingPortPropertySet.isSingleTabsAllowed()
,
DockingPortPropertySet.setSingleTabsAllowed(boolean)
public void setSingleTabAllowed(boolean allowed)
DockingPort
, allowing or
disallowing a single Dockable
within the DockingPort
to
appear within a tabbed layout.
Generally the tabbed interface does not appear until two or more
Dockables
are docked to the CENTER_REGION
of the
DockingPort
and tabs are required to switch between them. When
there is only a single Dockable
within the DockingPort
,
the default behavior for the dockable Component
to take up all of
the space within the DockingPort
.
If the single tab property is set to true
, then a single
Dockable
within this DockingPort
will reside within a
tabbed layout that contains only one tab.
The single tab property is a scoped property. This means there may be
many different "scopes" at which the single-tab property may be set. For
instance, a "global" setting may override the individual setting for this
DockingPort
, and this DockingPort's
particular setting
may override the global default setting. This method applied a value
only to the local scope for this particular DockingPort
.
org.flexdock.docking.props.PropertyManager
should be referenced
for further information on scoped properties.
allowed
- true
if a single-tabbed layout should be allowed,
false
otherwiseisSingleTabAllowed()
,
DockingManager.setSingleTabsAllowed(boolean)
,
DockingManager.isSingleTabsAllowed()
,
PropertyManager
,
DockingPortPropertySet.setSingleTabsAllowed(boolean)
,
DockingPortPropertySet.isSingleTabsAllowed()
public boolean isParentDockingPort(java.awt.Component comp)
DefaultDockingPort
. This method returns true
if the specified Component
is a direct child of the
DefaultDockingPort
or is a direct child of a JTabbedPane
or JSplitPane
that is currently the DefaultDockingPort's
docked
component. Otherwise, this method returns false
. If comp
is null
, then then this method return false
isParentDockingPort
in interface DockingPort
comp
- the Component to be tested.DefaultDockingPort
.DockingPort.isParentDockingPort(java.awt.Component)
,
Component.getParent()
,
getDockedComponent()
protected boolean isValidDockingRegion(java.lang.String region)
protected Dockable getCenterDockable()
public void remove(int index)
remove
in class java.awt.Container
index
- the index of the component to be removed.Container.remove(int)
public void removeAll()
removeAll
in class java.awt.Container
Container.removeAll()
public void setBorderManager(BorderManager mgr)
BorderManager
. This method provides
a means of customizing border managment following any successful call to
dock(Dockable dockable, String region)
or
undock(Component comp)
, allowing cleanup of borders for nested
Components
within the docking layout. null
values are
allowed.mgr
- the BorderManager
assigned to to manage docked
component borders.getBorderManager()
,
BorderManager
public BorderManager getBorderManager()
BorderManager
. The
BorderManager
is used any time a successful call to
dock(Dockable dockable, String region)
or
undock(Component comp)
has been issued to clean up borders for
nested Components
within the docking layout. This method will
return a null
reference if there is no BorderManager
installed.BorderManager
.setBorderManager(BorderManager)
,
BorderManager
public boolean undock(java.awt.Component comp)
Component
and returns a boolean indicating
the success of the operation.
Since DefaultDockingPort
may only contain one child component,
there i s a container hierarchy to manage tabbed interfaces, split
layouts, and sub-docking. As components are removed from this hierarchy,
the hierarchy itself must be reevaluated. Removing a component from a
child code>DefaultDockingPort} within a JSplitPane
renders the
child DefaultDockingPort
unnecessary, which, in turn, renders the
notion of splitting the layout with a JSplitPane
unnecessary
(since there are no longer two components to split the layout between).
Likewise, removing a child component from a JTabbedPane
such that
there is only one child left within the JTabbedPane
removes the
need for a tabbed interface to begin with.
This method automatically handles the reevaluation of the container
hierarchy to keep wrapper-container usage at a minimum. Since
DockingManager
makes this callback automatic, developers normally
will not need to call this method explicitly. However, when removing a
component from a DefaultDockingPort
using application code,
developers should keep in mind to use this method instead of
remove()
.
undock
in interface DockingPort
comp
- the Component
to be undocked.DockingPort.undock(Component comp)
,
DockingManager.undock(Dockable)
public java.util.Set getDockables()
Dockables
docked within this DockingPort
and
all sub-DockingPorts
. The returned Set
will contain
Dockable
instances. If there are no Dockables
present, an
empty Set
will be returned. This method will never return a
null
reference.getDockables
in interface DockingPort
Dockables
docked within this DockingPort
and
all sub-DockingPorts
.DockingPort.getDockables()
protected java.util.Set getDockableSet(int depth, int level, java.lang.Class desiredClass)
protected boolean isValidDockableChild(java.awt.Component c, java.lang.Class desiredClass)
public void addDockingListener(DockingListener listener)
DockingListener
to observe docking events for this
DockingPort
. null
arguments are ignored.addDockingListener
in interface DockingMonitor
listener
- the DockingListener
to add to this DockingPort
.DockingMonitor.addDockingListener(DockingListener)
,
getDockingListeners()
,
removeDockingListener(DockingListener)
public DockingListener[] getDockingListeners()
DockingListeners
added to this
DockingPort
. If there are no listeners present for this
DockingPort
, then a zero-length array is returned.getDockingListeners
in interface DockingMonitor
DockingListeners
added to this
DockingPort
.DockingMonitor.getDockingListeners()
,
addDockingListener(DockingListener)
,
removeDockingListener(DockingListener)
public void removeDockingListener(DockingListener listener)
DockingListener
from this
DockingPort
. If the specified DockingListener
is
null
, or the listener has not previously been added to this
DockingPort
, then no Exception
is thrown and no action
is taken.removeDockingListener
in interface DockingMonitor
listener
- the DockingListener
to remove from this
DockingPort
DockingMonitor.removeDockingListener(DockingListener)
,
addDockingListener(DockingListener)
,
getDockingListeners()
public void dockingCanceled(DockingEvent evt)
DockingListener
interface contract.dockingCanceled
in interface DockingListener
evt
- the DockingEvent
to respond to.DockingListener.dockingCanceled(DockingEvent)
public void dockingComplete(DockingEvent evt)
dockingComplete
in interface DockingListener
evt
- the DockingEvent
to respond to.DockingListener.dockingComplete(DockingEvent)
public void dragStarted(DockingEvent evt)
DockingListener
interface contract.dragStarted
in interface DockingListener
evt
- the DockingEvent
to respond to.DockingListener.dragStarted(DockingEvent)
public void dropStarted(DockingEvent evt)
DockingListener
interface contract.dropStarted
in interface DockingListener
evt
- the DockingEvent
to respond to.DockingListener.dropStarted(DockingEvent)
public void undockingComplete(DockingEvent evt)
DockingListener
interface contract.undockingComplete
in interface DockingListener
evt
- the DockingEvent
to respond to.DockingListener.undockingComplete(DockingEvent)
public void undockingStarted(DockingEvent evt)
DockingListener
interface contract.undockingStarted
in interface DockingListener
evt
- the DockingEvent
to respond to.DockingListener.undockingStarted(DockingEvent)
public DockingPortPropertySet getDockingProperties()
DockingPortPropertySet
instance associated with this
DockingPort
. This method returns the default implementation
supplied by the framework by invoking
getDockingPortPropertySet(DockingPort port)
on
org.flexdock.docking.props.PropertyManager
and supplying an
argument of this
.getDockingProperties
in interface DockingPort
DockingPortPropertySet
associated with this
DockingPort
. This method will not return a null
reference.DockingPortPropertySet
,
DockingPort.getDockingProperties()
,
PropertyManager.getDockingPortPropertySet(DockingPort)
public void setTabsAsDragSource(boolean enabled)
Dockable
within an embedded tabbed
layout will respond to drag events as if the tab were a component
included within the List
returned by calling
getDragSources()
on the Dockable
. This allows dragging a
tab to initiate drag-to-dock operations.enabled
- true
if drag-to-dock support should be enabled for
tabs and their associated Dockables
, false
otherwise.isTabsAsDragSource()
,
Dockable.getDragSources()
public boolean isTabsAsDragSource()
true
if drag-to-dock support is enabled for tabs and
their associated Dockables
, false
otherwise. If
tab-drag-source is enabled, then the tab that corresponds to a
Dockable
within an embedded tabbed layout will respond to drag
events as if the tab were a component included within the List
returned by calling getDragSources()
on the Dockable
.
This allows dragging a tab to initiate drag-to-dock operations.true
if drag-to-dock support is enabled for tabs and
their associated Dockables
, false
otherwise.setTabsAsDragSource(boolean)
,
Dockable.getDragSources()
protected int getInitTabPlacement()
public boolean isRoot()
DockingPort
is
nested within another DockingPort
. If there are no other
DockingPorts
within this DockingPort's
container ancestor
hierarchy, then this method will return true
. Otherwise, this
method will return false
. If the this DockingPort
is not
validated and/or is not part of a container hierarchy, this method should
return true
.isRoot
in interface DockingPort
false
if this DockingPort
is nested within
another DockingPort
, true
otherwise.DockingPort.isRoot()
public void setRoot(boolean root)
DefaultDockingPorts
whether they are "root" DockingPorts
according to the rules specified by isRoot()
on the
DockingPort
interface. This method should not be called by
application-level developers. It will most likely be removed in
future versions and the logic contained herein will be managed by some
type of change listener.root
- true
if this is a "root" DockingPort
,
false
otherwise.isRoot()
,
DockingPort.isRoot()
public void setDragInProgress(boolean inProgress)
DefaultDockingPorts
whether a drag operation is or is not
currently in progress and should not be called by application-level
developers. It will most likely be removed in future versions and the
logic contained herein will be managed by some type of change listener.inProgress
- true
if a drag operation involving this
DockingPort
is currently in progress, false
otherwise.public void paint(java.awt.Graphics g)
DragPreview
implementations may by able to supply a
BufferedImage
for this DockingPort
to use for painting
operations. This may be useful for cases in which the dimensions of
docked Components
are altered in realtime during the drag
operation to provide a "ghost" image for the DragPreview
. In
this case, visual feedback for altered subcomponents within this
DockingPort
may be blocked in favor of a temporary
BufferedImage
for the life of the drag operation.paint
in class javax.swing.JComponent
g
- the Graphics
context in which to paintJComponent.paint(java.awt.Graphics)
public LayoutNode exportLayout()
LayoutNode
containing metadata that describes the
current layout contained within this DefaultDockingPort
. The
LayoutNode
returned by this method will be a
DockingPortNode
that constitutes the root of a tree structure
containing various DockingNode
implementations; specifically
SplitNode
, DockableNode
, and DockingPortNode
.
Each of these nodes is Serializable
, implying the
LayoutNode
itself may be written to external storage and later
reloaded into this DockingPort
via
importLayout(LayoutNode node)
.exportLayout
in interface DockingPort
LayoutNode
representing the current layout state within
this DockingPort
DockingPort.importLayout(LayoutNode)
,
importLayout(LayoutNode)
,
LayoutManager.createLayout(DockingPort)
,
LayoutNode
,
DockingNode
,
DockingPortNode
,
SplitNode
,
DockableNode
public void importLayout(LayoutNode node)
DockingPort
and
reconstructs a new layout based upon the specified LayoutNode
.
At present, this method can only handle LayoutNodes
that have
been generated by DefaultDockingPort's
exportLayout()
method. If the specified LayoutNode
is null
or is
otherwise not an instance of DockingPortNode
, then this
method returns immediately with no action taken.
Otherwise, the necessary Dockables
are docked within this
DockingPort
and all subsequently generated sub-DockingPorts
in a visual configuration mandated by the tree structure modeled by the
specified LayoutNode
.
importLayout
in interface DockingPort
node
- the LayoutNode
whose layout is to be instantiated
within this DockingPort
DockingPort.importLayout(LayoutNode)
,
exportLayout()
,
LayoutNode
,
DockingNode
,
DockingPortNode
,
SplitNode
,
DockableNode
public void installMaximizedDockable(Dockable dockable)
DockingPort
DockingPort
to temporarily install the specified
Dockable
and maximize its component. This method is called by
DockingManager
in the course of maximizing a Dockable
.
Client code should not call this method directly.
This DockingPort
is expected to display the specified dockable's
component such that it occupies all (or the majority) of its screen
resources. Also, this DockingPort
is expected to internally store
enough information to restore its current state after a subsequent call
to DockingPort.uninstallMaximizedDockable()
.
installMaximizedDockable
in interface DockingPort
dockable
- the Dockable
that is requested to be maximizedDockingManager.toggleMaximized(Component)
,
DockingManager.toggleMaximized(Dockable)
public void uninstallMaximizedDockable()
DockingPort
DockingPort
that the Dockable
previously
installed for maximization via a call to
DockingPort.installMaximizedDockable(Dockable)
should now be returned to its
original DockingPort
and that this DockingPort
should
return to its original state from before the call to
DockingPort.installMaximizedDockable(Dockable)
. This method is called by
DockingManager
in the course of restoring a maximized
Dockable
. Client code should not call this method directly.
This DockingPort
is expected to remove the maximized dockable's
component from its swing container hierarchy.
uninstallMaximizedDockable
in interface DockingPort
DockingManager.toggleMaximized(Component)
,
DockingManager.toggleMaximized(Dockable)
public void releaseForMaximization(Dockable dockable)
DockingPort
DockingPort
to temporarily release its child
Dockable
for use by another DockingPort
to achieve
maximization. This method is called by DockingManager
in the
course of maximizing a Dockable
. Client code should not call
this method directly.
This DockingPort
is expected to remove the specified dockable's
component from its swing container hierarchy. Also, this
DockingPort
is expected to internally store enough information to
restore its current state after a subsequent call to
DockingPort.returnFromMaximization()
.
releaseForMaximization
in interface DockingPort
dockable
- the Dockable
that is requested to be maximizedDockingManager.toggleMaximized(Component)
,
DockingManager.toggleMaximized(Dockable)
public void returnFromMaximization()
DockingPort
DockingPort
that the Dockable
previously
released for maximization via a call to
DockingPort.releaseForMaximization(Dockable)
is now ready to be returned to
its original state inside this DockingPort
. This method is
called by DockingManager
in the course of restoring a maximized
Dockable
. Client code should not call this method directly.returnFromMaximization
in interface DockingPort
DockingManager.toggleMaximized(Component)
,
DockingManager.toggleMaximized(Dockable)