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

Fields
`static java.lang.String` `INITIAL_TAB_POSITION`

### Method Summary

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