org.flexdock.docking

## Interface DockingStrategy

All Known Implementing Classes:
  DefaultDockingStrategy

    public interface DockingStrategy

This interface defines an API used by `DockingManager` and `DockingPort` to support customizable behaviors during docking operations. `DockingManager` will associate a `DockingStrategy` with a particular `DockingPort` or `Dockable` class type. Calls to `DockingManager.dock()` and `DockingManager.undock()` will be deferred to the `DockingStrategy` associated with the parameters supplied in the respective method calls. `DockingStrategies` are also responsible for creating sub-DockingPorts and split panes for nested `DockingPorts` Implementations of `DockingStrategy` are responsible for managing component relationships between `Dockables` and parent containers. This includes making determinations as to whether a particular docking operation will be allowed for the specified parameters and the specifics of how a particular `Dockable` may be removed from one parent `Container` or `DockingPort` and added to another. `DockingStrategy` may determine whether a call to `dock()` implies an attempt to float a `Dockable` in a separate window. Because of the potentially large scope of responsibilities associated with a `DockingStrategy`, implementations may range from being very simple to highly complex. Although custom implementations of `DockingStrategy` are not discouraged, the recommeded path is to subclass `DefaultDockingStrategy` for consistency of behavior. `DockingStrategies` are associated with a particular type of `Dockable` or `DockingPort` by calling `DockingManager.setDockingStrategy(Class c, DockingStrategy strategy)`. `DefaultDockingStrategy` is the default implementation used for all classes that do not have a custom `DockingStrategy` registered.

Author:
  Christopher Butler

### Method Summary

Methods
`DockingPort` `createDockingPort(DockingPort base)` Creates and returns a new `DockingPort` instance based upon the supplied `DockingPort` parameter.
`javax.swing.JSplitPane` `createSplitPane(DockingPort base, java.lang.String region)` Creates and returns a new `JSplitPane` instance based upon the supplied parameters.
`boolean` `dock(Dockable dockable, DockingPort dockingPort, java.lang.String dockingRegion)` Attempts to dock the specified `Dockable` into the supplied `DockingPort` in the specified region.
`boolean` `dock(Dockable dockable, DockingPort dockingPort, java.lang.String dockingRegion, DragOperation operation)` Attempts to dock the specified `Dockable` into the supplied `DockingPort` in the specified region based upon the semantics of the specified `DragOperation`.
`double` `getDividerProportion(DockingPort dockingPort, javax.swing.JSplitPane splitPane)` Returns the desired divider proportion of the specified `JSplitPane` after rendering.
`int` `getInitialDividerLocation(DockingPort dockingPort, javax.swing.JSplitPane splitPane)` Returns the initial divider location to be used by the specified `JSplitPane`.
`boolean` `undock(Dockable dockable)` Undocks the specified `Dockable` instance from its containing `DockingPort`.

### Method Detail

#### dock

    boolean dock(Dockable dockable,
               DockingPort dockingPort,
               java.lang.String dockingRegion)

Attempts to dock the specified `Dockable` into the supplied `DockingPort` in the specified region. If docking is not possible for the specified parameters, then the method returns `false` and no action is taken. Since there is no `DragOperation` parameter present, this method implies programmatic docking as opposed to docking as a result of drag-events.

Parameters:
  `dockable` - the `Dockable` we wish to dock
  `dockingPort` - the `DockingPort` into which we wish to dock
  `dockingRegion` - the region of the specified `DockingPort` into which we wish to dock.
Returns:
  whether or not the docking operation was successful.

#### dock

    boolean dock(Dockable dockable,
               DockingPort dockingPort,
               java.lang.String dockingRegion,
               DragOperation operation)

Attempts to dock the specified `Dockable` into the supplied `DockingPort` in the specified region based upon the semantics of the specified `DragOperation`. If docking is not possible for the specified parameters, then the method returns `false` and no action is taken.

Parameters:
  `dockable` - the `Dockable` we wish to dock
  `dockingPort` - the `DockingPort` into which we wish to dock
  `dockingRegion` - the region of the specified `DockingPort` into which we wish to dock.
  `operation` - the `DragOperation` describing the state of the application/mouse at the point in time in which we're attempting to dock.
Returns:
  whether or not the docking operation was successful.

#### undock

    boolean undock(Dockable dockable)

Undocks the specified `Dockable` instance from its containing `DockingPort`.

Parameters:
  `dockable` - the `Dockable` we wish to undock
Returns:
  `true` if the `Dockable` was successfully undocked. Otherwise, returns `false`.

#### createDockingPort

    DockingPort createDockingPort(DockingPort base)

Creates and returns a new `DockingPort` instance based upon the supplied `DockingPort` parameter. For layouts that support nested `DockingPorts`, this method is useful for creating child `DockingPorts` suitable for embedding within the base `DockingPort`

Parameters:
  `base` - the `DockingPort` off of which the returned instance will be based.
Returns:
  a new `DockingPort` instance based upon the supplied parameter.

#### createSplitPane

    javax.swing.JSplitPane createSplitPane(DockingPort base,
                                         java.lang.String region)

Creates and returns a new `JSplitPane` instance based upon the supplied parameters. The returned `JSplitPane` should be suitable for embedding within the base `DockingPort` and its orientation should reflect the supplied `region` parameter.

Parameters:
  `base` - the `DockingPort` off of which the returned `JSplitPane` will be based.
  `region` - the region within the base `DockingPort` used to determine the orientation of the returned `JSplitPane`.
Returns:
  a new `JSplitPane` suitable for embedding within the base `DockingPort` parameter.

#### getInitialDividerLocation

    int getInitialDividerLocation(DockingPort dockingPort,
                                javax.swing.JSplitPane splitPane)

Returns the initial divider location to be used by the specified `JSplitPane`. This method assumes that the `JSplitPane` parameter is embedded within the specified `DockingPort` and that is has been validated and its current dimensions are non-zero.

Parameters:
  `dockingPort` - the `DockingPort` that contains, or will contain the specified `JSplitPane`.
  `splitPane` - the `JSplitPane` whose initial divider location is to be determined.
Returns:
  the desired divider location of the supplied `JSplitPane`.

#### getDividerProportion

    double getDividerProportion(DockingPort dockingPort,
                              javax.swing.JSplitPane splitPane)

Returns the desired divider proportion of the specified `JSplitPane` after rendering. This method assumes that the `JSplitPane` parameter is, or will be embedded within the specified `DockingPort`. This method does not assume that the `JSplitPane` has been validated and that it's current dimensions are non-zero.

Parameters:
  `dockingPort` - the `DockingPort` that contains, or will contain the specified `JSplitPane`.
  `splitPane` - the `JSplitPane` whose initial divider location is to be determined.
Returns:
  the desired divider proportion of the supplied `JSplitPane`.