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

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

### Method Summary

Methods
`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)`