org.flexdock.docking
Interface DockingPort

All Superinterfaces:
DockingListener, DockingMonitor, java.util.EventListener
All Known Implementing Classes:
DefaultDockingPort, FloatingDockingPort, Viewport

public interface DockingPort
extends DockingListener, DockingMonitor

This interface is designed to specify the API's required by DockingManager for placing Dockable instances within a container. A DockingPort is the parent container inside of which Dockable instances may be placed.

Author:
Chris Butler

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.flexdock.docking.event.DockingListener
DockingListener.Stub
 
Field Summary
static java.lang.String INITIAL_TAB_POSITION
           
 
Method Summary
 void clear()
          Removes all docked components from the DockingPort.
 boolean dock(java.awt.Component comp, java.lang.String region)
          Docks the specified Component in the specified region.
 boolean dock(Dockable dockable, java.lang.String region)
          Docks the specified Dockable in the specified region.
 LayoutNode exportLayout()
          Returns a LayoutNode containing metadata that describes the current layout contained within this DockingPort.
 java.lang.Object getClientProperty(java.lang.Object key)
          Returns the value of the property with the specified key.
 java.awt.Component getComponent(java.lang.String region)
          Returns a reference to Component currently docked in the target region.
 Dockable getDockable(java.lang.String region)
          Returns a reference to Dockable currently docked in the target region.
 java.util.Set getDockables()
          Returns a Set of all Dockables presently contained by this DockingPort.
 java.awt.Component getDockedComponent()
          Returns a reference to the currently docked component.
 DockingPortPropertySet getDockingProperties()
          Returns a DockingPortPropertySet instance associated with this DockingPort.
 DockingStrategy getDockingStrategy()
          Returns the DockingStrategy instance used by this DockingPort for docking operations.
 java.lang.String getPersistentId()
          Returns a String identifier that is unique within a JVM instance, but persistent across JVM instances.
 java.lang.String getRegion(java.awt.Point p)
          Returns the region of this DockingPort containing the coordinates within the specified Point.
 void importLayout(LayoutNode node)
          Examines a LayoutNode and constructs a corresponding component hierarchy to match the specified layout.
 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 a boolean indicating whether or not docking is allowed within the specified region.
 boolean isParentDockingPort(java.awt.Component comp)
          Indicates whether or not the specified component is a child component docked within the DockingPort.
 boolean isRoot()
          Returns a boolean indicating whether or not this DockingPort is nested within another DockingPort.
 void putClientProperty(java.lang.Object key, java.lang.Object value)
          Adds an arbitrary key/value "client property" to this DockingPort.
 void releaseForMaximization(Dockable dockable)
          Asks this DockingPort to temporarily release its child Dockable for use by another DockingPort to achieve maximization.
 void returnFromMaximization()
          Notifies this DockingPort that the Dockable previously released for maximization via a call to releaseForMaximization(Dockable) is now ready to be returned to its original state inside this DockingPort.
 void setPersistentId(java.lang.String id)
          Sets the persistent ID String to be returned by getPersistentId().
 boolean undock(java.awt.Component comp)
          Removes the specified Component in from the DockingPort.
 void uninstallMaximizedDockable()
          Notifies this DockingPort that the Dockable previously installed for maximization via a call to 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 installMaximizedDockable(Dockable).
 
Methods inherited from interface org.flexdock.docking.event.DockingListener
dockingCanceled, dockingComplete, dragStarted, dropStarted, undockingComplete, undockingStarted
 
Methods inherited from interface org.flexdock.docking.event.DockingMonitor
addDockingListener, getDockingListeners, removeDockingListener
 

Field Detail

INITIAL_TAB_POSITION

static final java.lang.String INITIAL_TAB_POSITION
See Also:
Constant Field Values
Method Detail

isDockingAllowed

boolean isDockingAllowed(java.awt.Component comp,
                         java.lang.String region)
Returns a boolean indicating whether or not docking is allowed within the specified region. Used by DockingManager during drag operations.


clear

void clear()
Removes all docked components from the DockingPort.


dock

boolean dock(Dockable dockable,
             java.lang.String region)
Docks the specified Dockable in the specified region. The Dockable's getDockable() component is used as the docking component.


dock

boolean dock(java.awt.Component comp,
             java.lang.String region)
Docks the specified Component in the specified region. Returns true for success and false for failure.


getDockedComponent

java.awt.Component getDockedComponent()
Returns a reference to the currently docked component.


getDockable

Dockable getDockable(java.lang.String region)
Returns a reference to Dockable currently docked in the target region. Returns null if there is no Dockable there. If a tabbed layout is present, this method will return the Dockable in the currently selected tab.


getComponent

java.awt.Component getComponent(java.lang.String region)
Returns a reference to Component currently docked in the target region. Returns null if there is no Component there. If a tabbed layout is present, this method will return the Component in the currently selected tab.


getPersistentId

java.lang.String getPersistentId()
Returns a String identifier that is unique 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.


setPersistentId

void setPersistentId(java.lang.String id)
Sets the persistent ID String to be returned by getPersistentId().

Parameters:
id - the persistent ID to be applied.
See Also:
getPersistentId()

isParentDockingPort

boolean isParentDockingPort(java.awt.Component comp)
Indicates whether or not the specified component is a child component docked within the DockingPort.


undock

boolean undock(java.awt.Component comp)
Removes the specified Component in from the DockingPort. Returns true for success and false for failure.


getRegion

java.lang.String getRegion(java.awt.Point p)
Returns the region of this DockingPort containing the coordinates within the specified Point. The return value will be one of the regions specified in org.flexdock.util.DockingConstants, including CENTER_REGION, NORTH_REGION, SOUTH_REGION, EAST_REGION, WEST_REGION, or UNKNOWN_REGION.

Returns:
the region containing the specified Point.

getClientProperty

java.lang.Object getClientProperty(java.lang.Object key)
Returns the value of the property with the specified key. Only properties added with putClientProperty will return a non-null value.

Parameters:
key - the being queried
Returns:
the value of this property or null
See Also:
JComponent.getClientProperty(java.lang.Object)

putClientProperty

void putClientProperty(java.lang.Object key,
                       java.lang.Object value)
Adds an arbitrary key/value "client property" to this DockingPort. null values are allowed.

See Also:
JComponent.putClientProperty(java.lang.Object, java.lang.Object)

getDockingProperties

DockingPortPropertySet getDockingProperties()
Returns a DockingPortPropertySet instance associated with this DockingPort. Developers implementing the DockingPort interface may or may not choose to provide their own DockingPortPropertySet implementation for use with this method. A default implementation is supplied by the framework and most DockingPort implementations, including all implementations provided by the framework, will return the default DockingPortPropertySet via a call to org.flexdock.docking.props.PropertyManager. Developers are encouraged to take advantage of this by calling PropertyManager.getDockingPortPropertySet(this).

Returns:
the DockingPortPropertySet associated with this DockingPort This method may not return a null reference.
See Also:
DockingPortPropertySet, PropertyManager.getDockingPortPropertySet(DockingPort)

getDockingStrategy

DockingStrategy getDockingStrategy()
Returns the DockingStrategy instance used by this DockingPort for docking operations.

See Also:
DockingStrategy

getDockables

java.util.Set getDockables()
Returns a Set of all Dockables presently contained by this DockingPort.

Returns:
a Set of Dockables contained by this DockingPort. If the DockingPort contians no Dockables, and empty Set is returned. This method may not return a null reference.

isRoot

boolean isRoot()
Returns a boolean indicating whether or not this 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.


importLayout

void importLayout(LayoutNode node)
Examines a LayoutNode and constructs a corresponding component hierarchy to match the specified layout. The supplied LayoutNode will contain metadata describing a layout of Dockables, including relative sizes, split proportions, tabbing sequences, etc. This DockingPort is reponsible for constructing a valid Dockable component layout based upon the metadata contained within the supplied LayoutNode

Parameters:
node - the LayoutNode describing the layout to construct
See Also:
LayoutNode, exportLayout()

exportLayout

LayoutNode exportLayout()
Returns a LayoutNode containing metadata that describes the current layout contained within this DockingPort. The returned LayoutNode should be structured such that a subsequent call to importLayout() on the same DockingPort should construct a visual component layout identical to that which currently exists in this DockingPort

Returns:
a LayoutNode representing the current layout state within this DockingPort
See Also:
LayoutNode, importLayout(LayoutNode)

releaseForMaximization

void releaseForMaximization(Dockable dockable)
Asks this 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 returnFromMaximization().

Parameters:
dockable - the Dockable that is requested to be maximized
See Also:
DockingManager.toggleMaximized(Component), DockingManager.toggleMaximized(Dockable)

returnFromMaximization

void returnFromMaximization()
Notifies this DockingPort that the Dockable previously released for maximization via a call to 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.

See Also:
DockingManager.toggleMaximized(Component), DockingManager.toggleMaximized(Dockable)

installMaximizedDockable

void installMaximizedDockable(Dockable dockable)
Asks this 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 uninstallMaximizedDockable().

Parameters:
dockable - the Dockable that is requested to be maximized
See Also:
DockingManager.toggleMaximized(Component), DockingManager.toggleMaximized(Dockable)

uninstallMaximizedDockable

void uninstallMaximizedDockable()
Notifies this DockingPort that the Dockable previously installed for maximization via a call to 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 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.

See Also:
DockingManager.toggleMaximized(Component), DockingManager.toggleMaximized(Dockable)