## 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
`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`.