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
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `INITIAL_TAB_POSITION`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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)`