org.flexdock.docking.defaults

## Class DockableComponentWrapper

- java.lang.Object
- - org.flexdock.docking.defaults.DockableComponentWrapper

- All Implemented Interfaces:
    java.util.EventListener, Dockable, DockingListener, DockingMonitor

      public class DockableComponentWrapper
      extends java.lang.Object
      implements Dockable

  This class models a `Dockable` implementation for wrapping a `Component`. It is essentially the simplest means to turning a generic `Component` into a `Dockable` instance. Compound `Dockables` may have separate child components that are responsible for drag initiation, whereas another component is the actual drag source. This is shown in the manner that a `JInternalFrame` would be a draggable component, while the frame's title pane is the actual drag initiator.

  The class, conversely, deals with the simple case, where a `Component` itself must be docking-enabled. `DockableComponentWrapper` wraps a `Component` and implements the `Dockable` interface. Since the `Component` itself is being docking-enabled, it serves as both the drag source and drag initiator. Thus, `getComponent()` will return a reference to `'this'` and `getDragSources()` return a `List` containing the same self-reference `Component`.

  This class may be used by application code to enable docking capabilities on a given `Component`. However, it is recommended that `DockingManager.registerDockable(Component evtSrc, String desc)` be used as a more automated, less invasive means of enabling docking on a component. `DockingManager.registerDockable(Component evtSrc, String desc)` will automatically create a `DockableComponentWrapper` instance and register the required drag listeners.

  Author:
    Chris Butler

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.flexdock.docking.event.DockingListener

      `DockingListener.Stub`

  - ### Field Summary

    - ### Fields inherited from interface org.flexdock.docking.Dockable

      `DOCKABLE_INDICATOR`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDockingListener(DockingListener listener)` Adds a `DockingListener` to observe docking events for this `Dockable`.
    `void` | `addPropertyChangeListener(java.beans.PropertyChangeListener listener)` Adds a PropertyChangeListener to the listener list.
    `static DockableComponentWrapper` | `create(java.awt.Component src, java.lang.String id, java.lang.String desc)` Creates a `DockableComponentWrapper` instance using the specified source component, persistent ID, and docking description.
    `static DockableComponentWrapper` | `create(DockingAdapter adapter)`
    `static DockableComponentWrapper` | `create(DockingStub stub)`
    `boolean` | `dock(Dockable dockable)` Provides the default `Dockable` implementation of `dock(Dockable dockable)` by calling and returning `DockingManager.dock(Dockable dockable, Dockable parent)`.
    `boolean` | `dock(Dockable dockable, java.lang.String relativeRegion)` Provides the default `Dockable` implementation of `dock(Dockable dockable, String relativeRegion)` by calling and returning `DockingManager.dock(Dockable dockable, Dockable parent, String region)`.
    `boolean` | `dock(Dockable dockable, java.lang.String relativeRegion, float ratio)` Provides the default `Dockable` implementation of `dock(Dockable dockable, String relativeRegion, float ratio)` by calling and returning `DockingManager.dock(Dockable dockable, Dockable parent, String region, float proportion)`.
    `void` | `dockingCanceled(DockingEvent evt)` No operation.
    `void` | `dockingComplete(DockingEvent evt)` No operation.
    `void` | `dragStarted(DockingEvent evt)` No operation.
    `void` | `dropStarted(DockingEvent evt)` No operation.
    `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` used to create this `DockableComponentWrapper` instance.
    `DockingListener[]` | `getDockingListeners()` Returns an array of all `DockingListeners` added to this `Dockable`.
    `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 `Components` used to initiate drag-to-dock operation.
    `java.util.Set` | `getFrameDragSources()` Returns a `HashSet` of `Components` used as frame drag sources when this `Dockable` is floating in a non-decorated external dialog.
    `java.lang.String` | `getPersistentId()` Returns the persistent ID of this `DockableComponentWrapper` instance provided when this object was instantiated.
    `void` | `putClientProperty(java.lang.Object key, java.lang.Object value)` Adds an arbitrary key/value "client property" to this `Dockable`.
    `void` | `removeDockingListener(DockingListener listener)` Removes the specified `DockingListener` from this `Dockable`.
    `void` | `removePropertyChangeListener(java.beans.PropertyChangeListener listener)` Removes a PropertyChangeListener from the listener list.
    `void` | `undockingComplete(DockingEvent evt)` No operation.
    `void` | `undockingStarted(DockingEvent evt)` No operation.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### create

          public static DockableComponentWrapper create(java.awt.Component src,
                                        java.lang.String id,
                                        java.lang.String desc)

      Creates a `DockableComponentWrapper` instance using the specified source component, persistent ID, and docking description. This method is used to create `Dockable` instances for simple `Components` where the drag source and drag initiator are the same `Component`.

      If `src` or `id` are `null`, then this method returns a `null` reference.

      `src` will be the `Component` returned by invoking `getComponent()` on the resulting `Dockable` and will be included in the `List` returned by `getDragSources()`. `id` will be the value returned by invoking `getPersistentId()` on the resulting `Dockable`. `desc` may be used by the `Dockable` for descriptive purposes (such as tab-text in a tabbed layout). It is not recommended to supply a `null` value for `desc`, but doing so is not illegal.

      Parameters:
        `src` - the source component
        `id` - the persistent ID for the Dockable instance
        `desc` - the docking description
      Returns:
        a new `DockableComponentWrapper` instance
      See Also:
        `Dockable.getComponent()`, `Dockable.getDragSources()`, `Dockable.getPersistentId()`, `DockingManager.registerDockable(Component, String)`

    - #### create

          public static DockableComponentWrapper create(DockingStub stub)

    - #### create

          public static DockableComponentWrapper create(DockingAdapter adapter)

    - #### getComponent

          public java.awt.Component getComponent()

      Returns the `Component` used to create this `DockableComponentWrapper` instance.
      Specified by:
        `getComponent` in interface `Dockable`
      Returns:
        the `Component` used to create this `DockableComponentWrapper` instance.
      See Also:
        `Dockable.getComponent()`, `create(Component, String, String)`

    - #### getDragSources

          public java.util.List getDragSources()

      Returns a `List` of `Components` used to initiate drag-to-dock operation. By default, the returned `List` contains the `Component` returned by `getComponent()`.
      Specified by:
        `getDragSources` in interface `Dockable`
      Returns:
        a `List` of `Components` used to initiate drag-to-dock operation.
      See Also:
        `Dockable.getDragSources()`, `getComponent()`, `create(Component, String, String)`

    - #### getPersistentId

          public java.lang.String getPersistentId()

      Returns the persistent ID of this `DockableComponentWrapper` instance provided when this object was instantiated.
      Specified by:
        `getPersistentId` in interface `Dockable`
      Returns:
        the persistent ID of this `DockableComponentWrapper`
      See Also:
        `Dockable.getPersistentId()`, `create(Component, String, String)`

    - #### getFrameDragSources

          public java.util.Set getFrameDragSources()

      Returns a `HashSet` of `Components` used as frame drag sources when this `Dockable` is floating in a non-decorated external dialog. The `HashSet` returned by this method is initially empty. Because it is mutable, however, new `Components` may be added to it.
      Specified by:
        `getFrameDragSources` in interface `Dockable`
      Returns:
        a `HashSet` of `Components` used as frame drag sources when this `Dockable` is floating in a non-decorated external dialog.
      See Also:
        `Dockable.getFrameDragSources()`

    - #### addDockingListener

          public void addDockingListener(DockingListener listener)

      Adds a `DockingListener` to observe docking events for this `Dockable`. `null` arguments are ignored.
      Specified by:
        `addDockingListener` in interface `DockingMonitor`
      Parameters:
        `listener` - the `DockingListener` to add to this `Dockable`.
      See Also:
        `getDockingListeners()`, `removeDockingListener(DockingListener)`

    - #### getDockingListeners

          public DockingListener[] getDockingListeners()

      Returns an array of all `DockingListeners` added to this `Dockable`. If there are no listeners present for this `Dockable`, then a zero-length array is returned.
      Specified by:
        `getDockingListeners` in interface `DockingMonitor`
      Returns:
        an array of all `DockingListeners` added to this `Dockable`.
      See Also:
        `addDockingListener(DockingListener)`, `removeDockingListener(DockingListener)`

    - #### removeDockingListener

          public void removeDockingListener(DockingListener listener)

      Removes the specified `DockingListener` from this `Dockable`. If the specified `DockingListener` is `null`, or the listener has not previously been added to this `Dockable`, then no `Exception` is thrown and no action is taken.
      Specified by:
        `removeDockingListener` in interface `DockingMonitor`
      Parameters:
        `listener` - the `DockingListener` to remove from this `Dockable`
      See Also:
        `addDockingListener(DockingListener)`, `getDockingListeners()`

    - #### dockingCanceled

          public void dockingCanceled(DockingEvent evt)

      No operation. Provided as a method stub to fulfull the `DockingListener` interface contract.
      Specified by:
        `dockingCanceled` in interface `DockingListener`
      Parameters:
        `evt` - the `DockingEvent` to respond to.
      See Also:
        `DockingListener.dockingCanceled(DockingEvent)`

    - #### dockingComplete

          public void dockingComplete(DockingEvent evt)

      No operation. Provided as a method stub to fulfull the `DockingListener` interface contract.
      Specified by:
        `dockingComplete` in interface `DockingListener`
      Parameters:
        `evt` - the `DockingEvent` to respond to.
      See Also:
        `DockingListener.dockingComplete(DockingEvent)`

    - #### undockingComplete

          public void undockingComplete(DockingEvent evt)

      No operation. Provided as a method stub to fulfull the `DockingListener` interface contract.
      Specified by:
        `undockingComplete` in interface `DockingListener`
      Parameters:
        `evt` - the `DockingEvent` to respond to.
      See Also:
        `DockingListener.undockingComplete(DockingEvent)`

    - #### undockingStarted

          public void undockingStarted(DockingEvent evt)

      No operation. Provided as a method stub to fulfull the `DockingListener` interface contract.
      Specified by:
        `undockingStarted` in interface `DockingListener`
      Parameters:
        `evt` - the `DockingEvent` to respond to.
      See Also:
        `DockingListener.undockingStarted(DockingEvent)`

    - #### dragStarted

          public void dragStarted(DockingEvent evt)

      No operation. Provided as a method stub to fulfull the `DockingListener` interface contract.
      Specified by:
        `dragStarted` in interface `DockingListener`
      Parameters:
        `evt` - the `DockingEvent` to respond to.
      See Also:
        `DockingListener.dragStarted(DockingEvent)`

    - #### dropStarted

          public void dropStarted(DockingEvent evt)

      No operation. Provided as a method stub to fulfull the `DockingListener` interface contract.
      Specified by:
        `dropStarted` in interface `DockingListener`
      Parameters:
        `evt` - the `DockingEvent` to respond to.
      See Also:
        `DockingListener.dropStarted(DockingEvent)`

    - #### getClientProperty

          public 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. If `key` is `null`, a `null` reference is returned.

      If the `Component` returned by `getComponent()` is an instance of `JComponent`, then this method will dispatch to that `JComponent's` `getClientProperty(Object, Object)` method. Otherwise, this `DockableComponentWrapper` will provide its own internal mapping of client properties.

      Specified by:
        `getClientProperty` in interface `Dockable`
      Parameters:
        `key` - the key that is being queried
      Returns:
        the value of this property or `null`
      See Also:
        `Dockable.getClientProperty(Object)`, `JComponent.getClientProperty(java.lang.Object)`

    - #### putClientProperty

          public void putClientProperty(java.lang.Object key,
                               java.lang.Object value)

      Adds an arbitrary key/value "client property" to this `Dockable`. `null` values are allowed. If `key` is `null`, then no action is taken.

      If the `Component` returned by `getComponent()` is an instance of `JComponent`, then this method will dispatch to that `JComponent's` `putClientProperty(Object, Object)` method. Otherwise, this `DockableComponentWrapper` will provide its own internal mapping of client properties.

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

    - #### getDockingProperties

          public DockablePropertySet getDockingProperties()

      Returns a `DockablePropertySet` instance associated with this `Dockable`. This method returns the default implementation supplied by the framework by invoking `getDockablePropertySet(Dockable dockable)` on `org.flexdock.docking.props.PropertyManager` and supplying an argument of `this`.
      Specified by:
        `getDockingProperties` in interface `Dockable`
      Returns:
        the `DockablePropertySet` associated with this `Dockable`. This method will not return a `null` reference.
      See Also:
        `Dockable.getDockingProperties()`, `PropertyManager.getDockablePropertySet(Dockable)`

    - #### getDockingPort

          public DockingPort getDockingPort()

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

      This method defers processing to `getDockingPort(Dockable dockable)`, passing an argument of `this`.

      Specified by:
        `getDockingPort` in interface `Dockable`
      Returns:
        the `DockingPort` within which this `Dockable` is currently docked.
      See Also:
        `Dockable.getDockingPort()`, `DockingManager.getDockingPort(Dockable)`

    - #### dock

          public boolean dock(Dockable dockable)

      Provides the default `Dockable` implementation of `dock(Dockable dockable)` by calling and returning `DockingManager.dock(Dockable dockable, Dockable parent)`. `'this'` is passed as the `parent` parameter.
      Specified by:
        `dock` in interface `Dockable`
      Parameters:
        `dockable` - the `Dockable` to dock relative to this `Dockable`
      Returns:
        `true` if the docking operation was successful; `false` otherwise.
      See Also:
        `Dockable.dock(Dockable)`, `DockingManager.dock(Dockable, Dockable)`

    - #### dock

          public boolean dock(Dockable dockable,
                     java.lang.String relativeRegion)

      Provides the default `Dockable` implementation of `dock(Dockable dockable, String relativeRegion)` by calling and returning `DockingManager.dock(Dockable dockable, Dockable parent, String region)`. `'this'` is passed as the `parent` parameter.
      Specified by:
        `dock` in interface `Dockable`
      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:
        `Dockable.dock(Dockable, String)`, `DockingManager.dock(Dockable, Dockable, String)`

    - #### dock

          public boolean dock(Dockable dockable,
                     java.lang.String relativeRegion,
                     float ratio)

      Provides the default `Dockable` implementation of `dock(Dockable dockable, String relativeRegion, float ratio)` by calling and returning `DockingManager.dock(Dockable dockable, Dockable parent, String region, float proportion)`. `'this'` is passed as the `parent` parameter.
      Specified by:
        `dock` in interface `Dockable`
      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

          public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

      Description copied from interface: `Dockable`
      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.

      Specified by:
        `addPropertyChangeListener` in interface `Dockable`
      Parameters:
        `listener` - the PropertyChangeListener to be added
      See Also:
        `Dockable.removePropertyChangeListener(PropertyChangeListener)`

    - #### removePropertyChangeListener

          public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

      Description copied from interface: `Dockable`
      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.

      Specified by:
        `removePropertyChangeListener` in interface `Dockable`
      Parameters:
        `listener` - the PropertyChangeListener to be removed
      See Also:
        `Dockable.addPropertyChangeListener(java.beans.PropertyChangeListener)`