org.flexdock.docking
Interface Dockable

All Superinterfaces:
DockingListener, DockingMonitor, java.util.EventListener
All Known Implementing Classes:
AbstractDockable, DockableComponentWrapper, View

public interface Dockable
extends DockingListener, DockingMonitor

This interface is designed to specify the API's required by DockingManager and DockingPort for dealing with dockable components in a drag-n-drop fashion. A Dockable is the child component that is docked into a DockingPort.

Author:
Christopher Butler

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.flexdock.docking.event.DockingListener
DockingListener.Stub
 
Field Summary
static java.lang.String DOCKABLE_INDICATOR
          A constant property key to signify that a component is dockable.
 
Method Summary
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener to the listener list.
 boolean dock(Dockable dockable)
          Implements the semantics for docking an external Dockable to this Dockable and returns a boolean indicating whether or not the docking operation was successful.
 boolean dock(Dockable dockable, java.lang.String relativeRegion)
          Implements the semantics for docking an external Dockable to the specified region of this Dockable and returns a boolean indicating whether or not the docking operation was successful.
 boolean dock(Dockable dockable, java.lang.String relativeRegion, float ratio)
          Implements the semantics for docking an external Dockable to the specified region of this Dockable with the specified layout ratio, returning a boolean indicating whether or not the docking operation was successful.
 java.lang.Object getClientProperty(java.lang.Object key)
          Returns the value of the property with the specified key.
 java.awt.Component getComponent()
          Returns the Component that is to be dragged and docked.
 DockingPort getDockingPort()
          Returns the DockingPort within which this Dockable is currently docked.
 DockablePropertySet getDockingProperties()
          Returns a DockablePropertySet instance associated with this Dockable.
 java.util.List getDragSources()
          Returns a List of the Components that are event sources for drag operations.
 java.util.Set getFrameDragSources()
          Returns a Set of the Components that are used as frame drag sources.
 java.lang.String getPersistentId()
          Returns a String identifier that is unique within a JVM instance, but persistent across JVM instances.
 void putClientProperty(java.lang.Object key, java.lang.Object value)
          Adds an arbitrary key/value "client property" to this Dockable.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes a PropertyChangeListener from the listener list.
 
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

DOCKABLE_INDICATOR

static final java.lang.String DOCKABLE_INDICATOR
A constant property key to signify that a component is dockable.

See Also:
Constant Field Values
Method Detail

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 key that is being queried
Returns:
the value of this property or null
See Also:
JComponent.getClientProperty(java.lang.Object)

getComponent

java.awt.Component getComponent()
Returns the Component that is to be dragged and docked. This may or may not be included in the list returned by getDragSources().

The framework performs indexing on the underlying Component. Consequently, this method may not return a null reference.

Returns:
the component wrapped by this dockable.

getDockingPort

DockingPort getDockingPort()
Returns the DockingPort within which this Dockable is currently docked. If not currently docked, this method will return null.

Returns:
the docking port this dockable resides in, or null if the dockable is not currently docked (i.e. in the middle of a drag operation).

getDragSources

java.util.List getDragSources()
Returns a List of the Components that are event sources for drag operations. The list may or may not include the Component returned by getComponent().

Returns:
a list containing the components that may be used to drag this dockable.

getFrameDragSources

java.util.Set getFrameDragSources()
Returns a Set of the Components that are used as frame drag sources. When a Dockable is floated into an external frame, that frame may or may not have a titlebar for repositioning. The Components returned by this method will be setup with appropriate event listeners such that dragging them will serve to reposition the containing frame as if they were the frame titlebar. If a Component exists in both the Set returned by this method and the List returned by getDragSources(), the "frame reposition" behavior will supercede any "drag-to-dock" behavior while the Dockable is in a floating state.

Returns:
a set containing the components that may be used to drag the frame this dockable resides in, if the dockable is floating.

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 Dockable 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 Dockable instances, but it should also be consistent from JVM to JVM so that the association between a Dockable instance and its ID can be remembered from session to session.

The framework performs indexing on the persistent ID. Consequently, this method may not return a null reference.

Returns:
the persistence id for this dockable. This id ensures that only one copy of a given dockable will exist.

putClientProperty

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

Parameters:
key - the new client property key.
value - the new client property value; if null this method will remove the property.
See Also:
JComponent.putClientProperty(java.lang.Object, java.lang.Object)

getDockingProperties

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

Returns:
the DockablePropertySet associated with this Dockable This method may not return a null reference.
See Also:
DockablePropertySet, PropertyManager.getDockablePropertySet(Dockable)

dock

boolean dock(Dockable dockable)
Implements the semantics for docking an external Dockable to this Dockable and returns a boolean indicating whether or not the docking operation was successful.

The framework already provides a default implementation for this method through DockingManager.dock(Dockable dockable, Dockable parent). While users are free to provide their own implementation for this method, the recommended approach is to use the default implementation with the following line:

return DockingManager.dock(dockable, this);

Parameters:
dockable - the Dockable to dock relative to this Dockable
Returns:
true if the docking operation was successful; false otherwise.
See Also:
dock(Dockable, String), dock(Dockable, String, float), DockingManager.dock(Dockable, Dockable)

dock

boolean dock(Dockable dockable,
             java.lang.String relativeRegion)
Implements the semantics for docking an external Dockable to the specified region of this Dockable and returns a boolean indicating whether or not the docking operation was successful. If the docking operation results in a split layout, this method should determine an appropriate ratio of available space to allot to the new sibling Dockable.

The framework already provides a default implementation for this method through DockingManager.dock(Dockable dockable, Dockable parent, String region). While users are free to provide their own implementation for this method, the recommended approach is to use the default implementation with the following line:

return DockingManager.dock(dockable, this, relativeRegion);

Parameters:
dockable - the Dockable to dock relative to this Dockable
relativeRegion - the docking region into which to dock the specified Dockable
Returns:
true if the docking operation was successful; false otherwise.
See Also:
dock(Dockable, String, float), DockingManager.dock(Dockable, Dockable, String)

dock

boolean dock(Dockable dockable,
             java.lang.String relativeRegion,
             float ratio)
Implements the semantics for docking an external Dockable to the specified region of this Dockable with the specified layout ratio, returning a boolean indicating whether or not the docking operation was successful. If the docking operation results in a split layout, this method should use the specified ratio to determine the amount of available space to allot to the new sibling Dockable.

The framework already provides a default implementation for this method through DockingManager.dock(Dockable dockable, Dockable parent, String region, float proportion). While users are free to provide their own implementation for this method, the recommended approach is to use the default implementation with the following line:

return DockingManager.dock(dockable, this, relativeRegion, ratio);

Parameters:
dockable - the Dockable to dock relative to this Dockable
relativeRegion - the docking region into which to dock the specified Dockable
ratio - the proportion of available space in the resulting layout to allot to the new sibling Dockable.
Returns:
true if the docking operation was successful; false otherwise.
See Also:
DockingManager.dock(Dockable, Dockable, String, float)

addPropertyChangeListener

void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all bound properties of this class. Note that if this Dockable is inheriting a bound property, then no event will be fired in response to a change in the inherited property.

If listener is null, no exception is thrown and no action is performed.

Parameters:
listener - the PropertyChangeListener to be added
See Also:
removePropertyChangeListener(PropertyChangeListener)

removePropertyChangeListener

void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This method should be used to remove PropertyChangeListeners that were registered for all bound properties of this class.

If listener is null, no exception is thrown and no action is performed.

Parameters:
listener - the PropertyChangeListener to be removed
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener)