org.flexdock.util

## Class DockingUtility

- java.lang.Object
- - org.flexdock.util.DockingUtility

All Implemented Interfaces:
  DockingConstants

    public class DockingUtility
    extends java.lang.Object
    implements DockingConstants

Author:
  Christopher Butler

### Field Summary

### Fields inherited from interface org.flexdock.docking.DockingConstants

`ACTIVE_WINDOW, BOTTOM, CENTER, CENTER_REGION, CLOSE_ACTION, DEFAULT_PERSISTENCE_KEY, DOCKING_ID, EAST_REGION, HEAVYWEIGHT_DOCKABLES, HORIZONTAL, LEFT, MOUSE_PRESSED, NORTH_REGION, PERMANENT_FOCUS_OWNER, PIN_ACTION, REGION, RIGHT, SOUTH_REGION, TOP, UNINITIALIZED, UNINITIALIZED_RATIO, UNKNOWN_REGION, UNSPECIFIED_SIBLING_PREF, VERTICAL, WEST_REGION`

### Method Summary

Methods
`static boolean` `dockRelative(Dockable dockable, Dockable parent, java.lang.String relativeRegion)` Docks the specified `Dockable` relative to another already-docked `Dockable` in the specified region.
`static boolean` `dockRelative(Dockable dockable, Dockable parent, java.lang.String relativeRegion, float ratio)` Docks the specified `Dockable` relative to another already-docked `Dockable` in the specified region with the specified split proportion.
`static DockingPort` `findDockingPort(java.awt.Container container, java.awt.Point location)` Returns the deepest `DockingPort` within the specified `Container` at the specified `location`.
`static java.lang.String` `flipRegion(java.lang.String region)` Returns the opposite docking region of the specified `region`.
`static Dockable` `getAncestorDockable(java.awt.Component comp)`
`static int` `getMinimizedConstraint(Dockable dockable)` Returns an `int` value representing the current minimization constraint for the specified `Dockable`.
`static DockingPort` `getParentDockingPort(java.awt.Component comp)` Returns the `DockingPort` that contains the specified `Component`.
`static DockingPort` `getParentDockingPort(Dockable d)` Returns the `DockingPort` that contains the specified `Dockable`.
`static java.lang.String` `getRegion(int regionType)` Returns the `String` docking region for the specified orientation constant.
`static java.lang.String` `getTabText(Dockable dockable)` Returns the text to be used by a `Dockable` as a tab label within a tabbed layout.
`static boolean` `isActive(Dockable dockable)`
`static boolean` `isAxisEquivalent(java.lang.String region, java.lang.String otherRegion)` Tests for region equivalency between the specified region parameters across horizontal and vertical axes.
`static boolean` `isDockable(java.lang.Object obj)` Returns `true` if the specific `Object` is a `Dockable`.
`static boolean` `isEmbedded(Dockable dockable)` Returns `true` if the specified `Dockable` is currently docked within a `DockingPort`.
`static boolean` `isFloating(Dockable dockable)` Returns `true` if the specified `Dockable` is currently docked within a floating dialog.
`static boolean` `isMinimized(Dockable dockable)` Returns `true` if the specified `Dockable` is currently minimized; `false` otherwise.
`static boolean` `isRegionTopLeft(java.lang.String region)` Returns `true` if the specified `region` is equal to either `NORTH_REGION` or `WEST_REGION`.
`static boolean` `isSubport(DockingPort dockingPort)` Returns `true` if the specified `DockingPort` has an ancestor `DockingPort`; `false` otherwise.
`static void` `setSplitProportion(Dockable dockable, float proportion)` Sets the divider location of the split layout containing the specified dockable `Component`.
`static void` `setSplitProportion(DockingPort port, float proportion)` Sets the divider location of the split layout embedded within the specified `DockingPort`.
`static java.lang.String` `translateRegionAxis(javax.swing.JSplitPane splitPane, java.lang.String region)` Returns the specified `region's` cross-axis equivalent region in accordance with the orientation used by the specified `JSplitPane`.

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

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

### Method Detail

#### getParentDockingPort

    public static DockingPort getParentDockingPort(Dockable d)

Returns the `DockingPort` that contains the specified `Dockable`. If the `Dockable` is `null`, then a `null` reference is returned.

This method will only return the immediate parent `DockingPort` of the specified `Dockable` This means that a check is performed for the `Component` returned by the `Dockable's` `getComponent()` method. The `DockingPort` returned by this method will not only be an ancestor `Container` of this `Component`, but invoking the `DockingPort's` `isParentDockingPort(Component comp)` with the this `Component` will also return `true`. If both of these conditions cannot be satisfied, then this method returns a `null` reference.

Parameters:
  `d` - the `Dockable` whose parent `DockingPort` is to be returned.
Returns:
  the imediate parent `DockingPort` that contains the specified `Dockable`.
See Also:
  `getParentDockingPort(Component)`

#### getParentDockingPort

    public static DockingPort getParentDockingPort(java.awt.Component comp)

Returns the `DockingPort` that contains the specified `Component`. If the `Component` is `null`, then a `null` reference is returned.

This method will only return the immediate parent `DockingPort` of the specified `Component` This means that the `DockingPort` returned by this method will not only be an ancestor `Container` of the specified `Component`, but invoking its `isParentDockingPort(Component comp)` with the specified `Component` will also return `true`. If both of these conditions cannot be satisfied, then this method returns a `null` reference.

Parameters:
  `comp` - the `Component` whose parent `DockingPort` is to be returned.
Returns:
  the immediate parent `DockingPort` that contains the specified `Component`.

#### isSubport

    public static boolean isSubport(DockingPort dockingPort)

Returns `true` if the specified `DockingPort` has an ancestor `DockingPort`; `false` otherwise. If the specified `DockingPort` is `null`, then this method returns `false`.

Parameters:
  `dockingPort` - the `DockingPort` to check for an ancestor port
Returns:
  `true` if the specified `DockingPort` has an ancestor `DockingPort`; `false` otherwise.
See Also:
  `SwingUtilities.getAncestorOfClass(java.lang.Class, java.awt.Component)`

#### findDockingPort

    public static DockingPort findDockingPort(java.awt.Container container,
                              java.awt.Point location)

Returns the deepest `DockingPort` within the specified `Container` at the specified `location`. If either `container` or `location` are `null`, then this method returns `null`.

This method will find the deepest `Component` within the specified container that the specified `Point` via `SwingUtilities.getDeepestComponentAt(Component parent, int x, int y)`. If no `Component` is resovled, then this method returns `null`. If the resolved `Component` is a `DockingPort`, then it is returned. Otherwise, the `Component's` `DockingPort` ancestor is resovled and returned from `SwingUtilities.getAncestorOfClass(Class c, Component comp)`, passing `DockingPort.class` for the ancestor class parameter.

Parameters:
  `container` - the `Container` within which to find a `DockingPort`.
  `location` - the point within the specified `Container` at which to search for a `DockingPort`.
Returns:
  the deepest `DockingPort` within the specified `Container` at the specified `location`.
See Also:
  `SwingUtilities.getDeepestComponentAt(java.awt.Component, int, int)`, `SwingUtilities.getAncestorOfClass(java.lang.Class, java.awt.Component)`

#### translateRegionAxis

    public static java.lang.String translateRegionAxis(javax.swing.JSplitPane splitPane,
                                       java.lang.String region)

Returns the specified `region's` cross-axis equivalent region in accordance with the orientation used by the specified `JSplitPane`. If the `JSplitPane` is `null`, or the specified `region` is invalid according to `DockingManager.isValidDockingRegion(String region)`, then this method returns `null`. `NORTH_REGION` and `SOUTH_REGION` are considered "vertical" regions, while `WEST_REGION` and `EAST_REGION` are considered horizontal regions. If the `JSplitPane` orientation matches the specified `region` orientation, then the original `region` value is returned. For instance, if the specified `region` is `EAST_REGION`, and the `JSplitPane` is of a horizontal orientation, then there is no need to translate the `region` parameter across axes since its current axis is already horizontal. In this case, `EAST_REGION` would be returned by this method.

If the axis of the specified `region` does not match the orientation of the `JSplitPane`, then the region is translated to its cross-axis equivalent and returns. In this case, `NORTH_REGION` will be translated to `WEST_REGION`, `SOUTH_REGION` to `EAST_REGION`, `WEST_REGION` to `NORTH_REGION`, and `EAST_REGION` to `SOUTH_REGION`. `CENTER_REGION` is never altered.

Parameters:
  `splitPane` - the `JSplitPane` whose orientation is to be used as a target axis
  `region` - the docking region to translate to the target axis
Returns:
  the specified `region's` cross-axis equivalent region in accordance with the orientation used by the specified `JSplitPane`.
See Also:
  `DockingManager.isValidDockingRegion(String)`, `JSplitPane.getOrientation()`, `isAxisEquivalent(String, String)`

#### flipRegion

    public static java.lang.String flipRegion(java.lang.String region)

Returns the opposite docking region of the specified `region`. For `NORTH_REGION`, this method returns `SOUTH_REGION`. For `SOUTH_REGION`, this method returns `NORTH_REGION`. For `EAST_REGION`, this method returns `WEST_REGION`. For `WEST_REGION`, this method returns `EAST_REGION`. For `CENTER_REGION` or an invalid region, as specified by `DockingManager.isValidDockingRegion(String region)`, this method return `CENTER_REGION`.

Parameters:
  `region` - the region whose opposite is to be returned.
Returns:
  the opposite docking region of the specified `region`.
See Also:
  `DockingManager.isValidDockingRegion(String)`

#### isAxisEquivalent

    public static boolean isAxisEquivalent(java.lang.String region,
                           java.lang.String otherRegion)

Tests for region equivalency between the specified region parameters across horizontal and vertical axes. If either `region` or `otherRegion` are `null` or invalid according to `DockingManager.isValidDockingRegion(String region)`, then this method returns `false`.

Equivalency within the same axis means that the two specified regions are the same value, as each region is unique within its axis. Thus, this method returns `true` if `region.equals(otherRegion)` returns `true`. This includes `CENTER_REGION`, which is axis independent.

`CENTER_REGION` is not an axis equivalent to any region other than itself since it is the only docking region that does not correspond to a horizontal or vertical axis. If either the specified `region` or `otherRegion` is `CENTER_REGION` and the other is not, then this method returns `false`.

Equivalancy across axes follows a top-to-left and bottom-to-right mapping. In this fashion, `NORTH_REGION` and `WEST_REGION` are equivalent and `SOUTH_REGION` and `EAST_REGION` are equivalent. These combination will return `true` for this method. All other region combinatinos will cause this method to return `false`.

Parameters:
  `region` - the first region to check for equivalency
  `otherRegion` - the second region to check for equivalency
Returns:
  `true` if the two specified regions are equal or cross-axis equivalents, `false` otherwise.
See Also:
  `DockingManager.isValidDockingRegion(String)`

#### isRegionTopLeft

    public static boolean isRegionTopLeft(java.lang.String region)

Returns `true` if the specified `region` is equal to either `NORTH_REGION` or `WEST_REGION`. Returns `false` otherwise.

Parameters:
  `region` - the `region` to check for top or left equivalency
Returns:
  `true` if the specified `region` is equal to either `NORTH_REGION` or `WEST_REGION`; `false` otherwise.
See Also:
  `DockingConstants.NORTH_REGION`, `DockingConstants.WEST_REGION`

#### getRegion

    public static java.lang.String getRegion(int regionType)

Returns the `String` docking region for the specified orientation constant. `LEFT` maps to `WEST_REGION`, `RIGHT` maps to `EAST_REGION`, `TOP` maps to `NORTH_REGION`, `BOTTOM` maps to `SOUTH_REGION`, and `CENTER` maps to `CENTER_REGION`. All other integer values will cause this method to return `UNKNOWN_REGION`.

All constants, both integer an `String` values, can be found on the `DockingConstants` interface.

Parameters:
  `regionType` - the orientation constant to translate into a docking region
Returns:
  the `String` docking region for the specified orientation constant.
See Also:
  `DockingConstants.LEFT`, `DockingConstants.RIGHT`, `DockingConstants.TOP`, `DockingConstants.BOTTOM`, `DockingConstants.CENTER`, `DockingConstants.WEST_REGION`, `DockingConstants.EAST_REGION`, `DockingConstants.NORTH_REGION`, `DockingConstants.SOUTH_REGION`, `DockingConstants.CENTER_REGION`, `DockingConstants.UNKNOWN_REGION`

#### isMinimized

    public static boolean isMinimized(Dockable dockable)

Returns `true` if the specified `Dockable` is currently minimized; `false` otherwise. If the `Dockable` is `null`, then this method returns `false`.

This method retrieves the current `DockingState` instance associated with the `Dockable` and calls it's `isMinimized()` method to return. `DockingState` for the specified `Dockable` is queried by calling `getDockingState(Dockable dockable)` on the `DockingManager's` currently installed `LayoutManager`.

Parameters:
  `dockable` - the `Dockable` whose minimized state is to be returned
Returns:
  `true` if the specified `Dockable` is currently minimized; `false` otherwise.
See Also:
  `DockingState.isMinimized()`, `DockingManager.getLayoutManager()`, `LayoutManager.getDockingState(Dockable)`

#### getMinimizedConstraint

    public static int getMinimizedConstraint(Dockable dockable)

Returns an `int` value representing the current minimization constraint for the specified `Dockable`. If the `Dockable` is `null`, then this method returns `MinimizationManager.UNSPECIFIED_LAYOUT_CONSTRAINT`.

This method retrieves the current `DockingState` instance associated with the `Dockable` and calls it's `getMinimizedConstraint()` method to return. `DockingState` for the specified `Dockable` is queried by calling `getDockingState(Dockable dockable)` on the `DockingManager's` currently installed `LayoutManager`.

Parameters:
  `dockable` - the `Dockable` whose minimized constraint is to be returned
Returns:
  an `int` value representing the current minimization constraint for the specified `Dockable`
See Also:
  `MinimizationManager.UNSPECIFIED_LAYOUT_CONSTRAINT`, `DockingState.getMinimizedConstraint()()`, `DockingManager.getLayoutManager()`, `LayoutManager.getDockingState(Dockable)`

#### dockRelative

    public static boolean dockRelative(Dockable dockable,
                       Dockable parent,
                       java.lang.String relativeRegion)

Docks the specified `Dockable` relative to another already-docked `Dockable` in the specified region. The "parent" `Dockable` must currently be docked. If not, this method will return `false`. Otherwise, its parent `DockingPort` will be resolved and the new `Dockable` will be docked into the `DockingPort` relative to the "parent" `Dockable`. This method defers processing to `dockRelative(Dockable dockable, Dockable parent, String relativeRegion, float ratio)` passing `UNSPECIFIED_SIBLING_PREF` for the `ratio` parameter.

This method returns `false` if any of the input parameters are `null` or if the specified `region` is invalid according to `DockingManager.isValidDockingRegion(String region)`. If the specified region is other than CENTER, then a split layout should result.

Parameters:
  `dockable` - the `Dockable` to be docked
  `parent` - the `Dockable` used as a reference point for docking
  `relativeRegion` - the docking region into which `dockable` will be docked
Returns:
  `true` if the docking operation was successful; `false` otherwise.
See Also:
  `dockRelative(Dockable, Dockable, String, float)`, `DockingManager.isValidDockingRegion(String)`, `Dockable.getDockingPort()`, `DockingManager.dock(Dockable, DockingPort, String)`

#### dockRelative

    public static boolean dockRelative(Dockable dockable,
                       Dockable parent,
                       java.lang.String relativeRegion,
                       float ratio)

Docks the specified `Dockable` relative to another already-docked `Dockable` in the specified region with the specified split proportion. The "parent" `Dockable` must currently be docked. If not, this method will return `false`. Otherwise, its parent `DockingPort` will be resolved and the new `Dockable` will be docked into the `DockingPort` relative to the "parent" `Dockable`. If the specified region is CENTER, then the `proportion` parameter is ignored. Otherwise, a split layout should result with the proportional space specified in the `proportion` parameter allotted to the `dockable` argument.

This method returns `false` if any of the input parameters are `null` or if the specified `region` is invalid according to `DockingManager.isValidDockingRegion(String region)`.

Parameters:
  `dockable` - the `Dockable` to be docked
  `parent` - the `Dockable` used as a reference point for docking
  `relativeRegion` - the docking region into which `dockable` will be docked
  `ratio` - the proportional space to allot the `dockable` argument if the docking operation results in a split layout.
Returns:
  `true` if the docking operation was successful; `false` otherwise.
See Also:
  `DockingManager.isValidDockingRegion(String)`, `Dockable.getDockingPort()`, `DockingManager.dock(Dockable, DockingPort, String)`

#### isFloating

    public static boolean isFloating(Dockable dockable)

Returns `true` if the specified `Dockable` is currently docked within a floating dialog. This method returns `false` if the `Dockable` is presently, minimized, hidden, docked within the main application layout, or if the `Dockable` parameter is `null`.

This method retrieves the current `DockingState` instance associated with the `Dockable` and calls it's `isFloating()` method to return. `DockingState` for the specified `Dockable` is queried by calling `getDockingState(Dockable dockable)` on the `DockingManager's` currently installed `LayoutManager`.

Parameters:
  `dockable` - the `Dockable` whose floating state is to be returned
Returns:
  `true` if the specified `Dockable` is currently floating; `false` otherwise.
See Also:
  `DockingState.isFloating()`, `DockingManager.getLayoutManager()`, `LayoutManager.getDockingState(Dockable)`

#### isEmbedded

    public static boolean isEmbedded(Dockable dockable)

Returns `true` if the specified `Dockable` is currently docked within a `DockingPort`. This method returns `false` if the `Dockable` is presently floating, minimized, hidden, or if the `Dockable` parameter is `null`.

Parameters:
  `dockable` - the `Dockable` whose embedded state is to be returned
Returns:
  `true` if the specified `Dockable` is currently docked within a `DockingPort`; `false` otherwise.
See Also:
  `DockingManager.isDocked(Dockable)`, `isFloating(Dockable)`

#### setSplitProportion

    public static void setSplitProportion(DockingPort port,
                          float proportion)

Sets the divider location of the split layout embedded within the specified `DockingPort`. This method differs from both `setSplitProportion(Dockable dockable, float proportion)` in that this method resolves the split layout embedded within the specified `DockingPort`, whereas the other method modifies the split layout containing its respective `Dockable` parameter.

The resulting divider location will be a percentage of the split layout size based upon the `proportion` parameter. Valid values for `proportion` range from `0.0F{@code to {@code 1.0F}. For example, a {@code proportion} of {@code 0.3F} will move the divider to 30% of the "size" (<i>width</i> for horizontal split, <i>height</i> for vertical split) of the split container embedded within the specified {@code DockingPort}. If a {@code proportion} of less than {@code 0.0F} is supplied, the value }0.0F` is used. If a `proportion` greater than `1.0F` is supplied, the value }1.0F} is used.

This method should be effective regardless of whether the split layout in question has been fully realized and is currently visible on the screen. This should alleviate common problems associated with setting percentages of unrealized `Component` dimensions, which are initially `0x0` before the `Component` has been rendered to the screen.

If the specified `DockingPort` is `null`, then no `Exception` is thrown and no action is taken. Identical behavior occurs if the `DockingPort` does not contain split layout.

Parameters:
  `port` - the `DockingPort` containing the split layout is to be resized.
  `proportion` - the percentage of split layout size to which the split divider should be set.
See Also:
  `SwingUtility.setSplitDivider(JSplitPane, float)`

#### setSplitProportion

    public static void setSplitProportion(Dockable dockable,
                          float proportion)

Sets the divider location of the split layout containing the specified dockable `Component`.

The resulting divider location will be a percentage of the split layout size based upon the `proportion` parameter. Valid values for `proportion` range from `0.0F{@code to {@code 1.0F}. For example, a {@code proportion} of {@code 0.3F} will move the divider to 30% of the "size" (<i>width</i> for horizontal split, <i>height</i> for vertical split) of the split container that contains the specified {@code Dockable}. If a {@code proportion} of less than {@code 0.0F} is supplied, the value }0.0F` is used. If a `proportion` greater than `1.0F` is supplied, the value }1.0F} is used.

It is important to note that the split divider location is only a percentage of the container size from left to right or top to bottom. A `proportion` of `0.3F` does not imply that `dockable` itself will be allotted 30% of the available space. The split divider will be moved to the 30% position of the split container regardless of the region in which the specified `Dockable` resides (which may possibly result in `dockable` being allotted 70% of the available space).

This method should be effective regardless of whether the split layout in question has been fully realized and is currently visible on the screen. This should alleviate common problems associated with setting percentages of unrealized `Component` dimensions, which are initially `0x0` before the `Component` has been rendered to the screen.

If the specified `Dockable` is `null`, then no `Exception` is thrown and no action is taken. Identical behavior occurs if the `Dockable` does not reside within a split layout.

If the `Dockable` resides within a tabbed layout, a check is done to see if the tabbed layout resides within a parent split layout. If so, the resolved split layout is resized. Otherwise no action is taken.

Parameters:
  `dockable` - the `Dockable` whose containing split layout is to be resized.
  `proportion` - the percentage of containing split layout size to which the split divider should be set.
See Also:
  `SwingUtility.setSplitDivider(JSplitPane, float)`

#### getTabText

    public static java.lang.String getTabText(Dockable dockable)

Returns the text to be used by a `Dockable` as a tab label within a tabbed layout. This method retrieves the associated `DockablePropertySet` by calling `getDockingProperties()` on the specified `Dockable`. It then returns the value retrieved from calling `getDockableDesc()` on the `DockablePropertySet` instance. If the specified `Dockable` is `null`, then this method returns `null`.

Parameters:
  `dockable` - the `Dockable` whose tab-text is to be returned
Returns:
  the text to be used by a `Dockable` as a tab label within a tabbed layout.
See Also:
  `Dockable.getDockingProperties()`, `DockablePropertySet.getDockableDesc()`

#### isDockable

    public static boolean isDockable(java.lang.Object obj)

Returns `true` if the specific `Object` is a `Dockable`. If `obj instanceof Dockable` is `true`, then this method returns `true`. A `null` parameter will cause this method to return `false`.

Registered `Dockable` components, if they are `JComponents`, will also have a `Boolean` client property present with the key `Dockable.DOCKABLE_INDICATOR`, used by dockable `JComponents` that don't implement the `Dockable` interface directly, but acquire docking capabilities through a separate wrapper `Dockable` implementation. For these components, the `instanceof` check is insufficient since the valid `Dockable` is implemented by a separate class. Therefore, if the `instanceof` check fails, and the supplied `Object` parameter is a `JComponent`, a client property with the key `Dockable.DOCKABLE_INDICATOR` is checked for a value of `Boolean.TRUE`. If the client property is present, then this method returns `true`.

Parameters:
  `obj` - the `Object` to be checked to see if it represents a valid `Dockable`
Returns:
  `true` if the specific `Object` is a `Dockable`
See Also:
  `Dockable.DOCKABLE_INDICATOR`, `Boolean.TRUE`, `JComponent.getClientProperty(java.lang.Object)`

#### getAncestorDockable

    public static Dockable getAncestorDockable(java.awt.Component comp)

#### isActive

    public static boolean isActive(Dockable dockable)