org.flexdock.docking.defaults

## Class DefaultRegionChecker

- java.lang.Object
- - org.flexdock.docking.defaults.DefaultRegionChecker

All Implemented Interfaces:
  DockingConstants, RegionChecker

    public class DefaultRegionChecker
    extends java.lang.Object
    implements RegionChecker, DockingConstants

Author:
  Christopher Butler

### Field Summary

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

`DEFAULT_REGION_SIZE, DEFAULT_SIBLING_SIZE, DEFAULT_SIBLING_SIZE_KEY, MAX_REGION_SIZE, MAX_SIBILNG_SIZE, MIN_REGION_SIZE, MIN_SIBILNG_SIZE`

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

### Constructor Summary

Constructors
Constructor and Description
`DefaultRegionChecker()`

### Method Summary

Methods
`protected java.awt.Rectangle` `calculateRegionalBounds(java.awt.Component c, java.lang.String region, float size)`
`protected static float` `checkBounds(float val, float max, float min)`
`protected static float` `getDockingInset(java.lang.Float value, float defaultVal, float max, float min)`
`java.awt.Rectangle` `getEastRegion(java.awt.Component c)` Returns the rectangular bounds within the specified component that represent it's `DockingConstants.EAST_REGION`.
`java.awt.Rectangle` `getNorthRegion(java.awt.Component c)` Returns the rectangular bounds within the specified component that represent it's `DockingConstants.NORTH_REGION`.
`java.lang.String` `getRegion(java.awt.Component comp, java.awt.Point point)` Returns the docking region of the supplied `Component` that contains the coordinates of the specified `Point`.
`java.awt.Rectangle` `getRegionBounds(java.awt.Component c, java.lang.String region)` Returns the bounding `Rectangle` within the specified component that represents the specified region.
`static float` `getRegionPreference(Dockable d, java.lang.String region)` Returns a percentage (0.0F through 1.0F) representing the amount of space allotted for the specified region within the specified `Dockable`.
`float` `getRegionSize(java.awt.Component c, java.lang.String region)` Returns a percentage (0.0F through 1.0F) representing the amount of space allotted for the specified region within the specified `Component`.
`java.awt.Rectangle` `getSiblingBounds(java.awt.Component c, java.lang.String region)` Returns the bounding `Rectangle` within the specified component that represents the desired area to be allotted for sibling `Components` in the specified region.
`static float` `getSiblingPreference(Dockable d, java.lang.String region)` Returns a percentage (0.0F through 1.0F) representing the amount of space allotted for sibling `Components` docked to the specified region within the specified `Dockable`.
`float` `getSiblingSize(java.awt.Component c, java.lang.String region)` Returns a percentage (0.0F through 1.0F) representing the amount of space allotted for sibling `Component` docked to the specified region within the specified `Component`.
`java.awt.Rectangle` `getSouthRegion(java.awt.Component c)` Returns the rectangular bounds within the specified component that represent it's `DockingConstants.SOUTH_REGION`.
`java.awt.Rectangle` `getWestRegion(java.awt.Component c)` Returns the rectangular bounds within the specified component that represent it's `DockingConstants.WEST_REGION`.
`static float` `validateRegionSize(float size)` Returns `size` if it is between the values `RegionChecker.MIN_REGION_SIZE` and `RegionChecker.MAX_REGION_SIZE`.
`static float` `validateSiblingSize(float size)` Returns `size` if it is between the values `RegionChecker.MIN_SIBILNG_SIZE` and `RegionChecker.MAX_SIBILNG_SIZE`.

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

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

### Constructor Detail

#### DefaultRegionChecker

    public DefaultRegionChecker()

### Method Detail

#### getRegion

    public java.lang.String getRegion(java.awt.Component comp,
                             java.awt.Point point)

Returns the docking region of the supplied `Component` that contains the coordinates of the specified `Point`. If either `comp` or `point` is `null`, then `UNKNOWN_REGION` is returned. If the specified `Component` bounds do not contain the supplied `Point`, then `UNKNOWN_REGION` is returned.

This implementation assumes that `comp` is a `Component` embedded within a `DockingPort`. If `comp` is itself a `DockingPort`, then `CENTER_REGION` is returned. Otherwise, the returned region is based upon a section of the bounds of the specified `Component` relative to the containing `DockingPort`.

This method divides the specified `Component's` bounds into four `Rectangles` determined by `getNorthRegion(Component c)`, `getSouthRegion(Component c)`, `getEastRegion(Component c)`, and `getWestRegion(Component c)`, respectively. Each `Rectangle` is then checked to see if it contains the specified `Point`. The order of precedence is NORTH, SOUTH, EAST, and then WEST. If the specified `Point` is contained by the `Component` bounds but none of the sub-`Rectangles`, then `CENTER_REGION` is returned.

For NORTH and SOUTH `Rectangles`, the distance is checked between the top/bottom and left or right edge of the regional bounds. If the horizontal distance to the regional edge is smaller than the vertical distance, then EAST or WEST takes precendence of NORTH or SOUTH. This allows for proper determination between "northeast", "northwest", "southeast", and "southwest" cases.

Specified by:
  `getRegion` in interface `RegionChecker`
Parameters:
  `comp` - the `Component` whose region is to be examined.
  `point` - the coordinates whose region is to be determined.
Returns:
  the docking region containing the specified `Point`.
See Also:
  `RegionChecker.getRegion(Component, Point)`, `getNorthRegion(Component)`, `getSouthRegion(Component)`, `getEastRegion(Component)`, `getWestRegion(Component)`

#### getNorthRegion

    public java.awt.Rectangle getNorthRegion(java.awt.Component c)

Returns the rectangular bounds within the specified component that represent it's `DockingConstants.NORTH_REGION`. This method dispatches to `getRegionBounds(Component c, String region)`, passing an argument of `DockingConstants.NORTH_REGION` for the region parameter. If the specified `Component` is `null`, then a `null` reference is returned.

Specified by:
  `getNorthRegion` in interface `RegionChecker`
Parameters:
  `c` - the `Component` whose north region is to be returned.
Returns:
  the bounds containing the north region of the specified `Component`.
See Also:
  `RegionChecker.getNorthRegion(Component)`, `getRegionBounds(Component, String)`

#### getSouthRegion

    public java.awt.Rectangle getSouthRegion(java.awt.Component c)

Returns the rectangular bounds within the specified component that represent it's `DockingConstants.SOUTH_REGION`. This method dispatches to `getRegionBounds(Component c, String region)`, passing an argument of `DockingConstants.SOUTH_REGION` for the region parameter. If the specified `Component` is `null`, then a `null` reference is returned.

Specified by:
  `getSouthRegion` in interface `RegionChecker`
Parameters:
  `c` - the `Component` whose south region is to be returned.
Returns:
  the bounds containing the north region of the specified `Component`.
See Also:
  `RegionChecker.getSouthRegion(Component)`, `getRegionBounds(Component, String)`

#### getEastRegion

    public java.awt.Rectangle getEastRegion(java.awt.Component c)

Returns the rectangular bounds within the specified component that represent it's `DockingConstants.EAST_REGION`. This method dispatches to `getRegionBounds(Component c, String region)`, passing an argument of `DockingConstants.EAST_REGION` for the region parameter. If the specified `Component` is `null`, then a `null` reference is returned.

Specified by:
  `getEastRegion` in interface `RegionChecker`
Parameters:
  `c` - the `Component` whose east region is to be returned.
Returns:
  the bounds containing the north region of the specified `Component`.
See Also:
  `RegionChecker.getEastRegion(Component)`, `getRegionBounds(Component, String)`

#### getWestRegion

    public java.awt.Rectangle getWestRegion(java.awt.Component c)

Returns the rectangular bounds within the specified component that represent it's `DockingConstants.WEST_REGION`. This method dispatches to `getRegionBounds(Component c, String region)`, passing an argument of `DockingConstants.WEST_REGION` for the region parameter. If the specified `Component` is `null`, then a `null` reference is returned.

Specified by:
  `getWestRegion` in interface `RegionChecker`
Parameters:
  `c` - the `Component` whose west region is to be returned.
Returns:
  the bounds containing the north region of the specified `Component`.
See Also:
  `RegionChecker.getWestRegion(Component)`, `getRegionBounds(Component, String)`

#### getRegionBounds

    public java.awt.Rectangle getRegionBounds(java.awt.Component c,
                                     java.lang.String region)

Returns the bounding `Rectangle` within the specified component that represents the specified region. If `c` or `region` are null, then this method returns a `null` reference.

This method dispatches to `getRegionSize(Component c, String region)` to determine the proportional size of the specified `Component` dedicated to the specified region. It then multiplies this value by the relevant `Component` dimension (`width` for east/west, `height` for north/south) and returns a `Rectangle` with the resulting dimension, spanning the `Component` edge for the specified region.

Specified by:
  `getRegionBounds` in interface `RegionChecker`
Parameters:
  `c` - the `Component` whose region bounds are to be returned.
  `region` - the specified region that is to be examined.
Returns:
  the bounds containing the supplied region of the specified `Component`.
See Also:
  `RegionChecker.getRegionBounds(Component, String)`, `getRegionSize(Component, String)`

#### getSiblingBounds

    public java.awt.Rectangle getSiblingBounds(java.awt.Component c,
                                      java.lang.String region)

Returns the bounding `Rectangle` within the specified component that represents the desired area to be allotted for sibling `Components` in the specified region. If `c` or `region` are null, then this method returns a `null` reference.

This method dispatches to `getSiblingSize(Component c, String region)` to determine the proportional size of the specified `Component` dedicated to siblings in the specified region. It then multiplies this value by the relevant `Component` dimension (`width` for east/west, `height` for north/south) and returns a `Rectangle` with the resulting dimension, spanning the `Component` edge for the specified region.

Specified by:
  `getSiblingBounds` in interface `RegionChecker`
Parameters:
  `c` - the `Component` whose sibling bounds are to be returned.
  `region` - the specified region that is to be examined.
Returns:
  the bounds representing the allotted sibling area for the supplied region of the specified `Component`.
See Also:
  `RegionChecker.getSiblingBounds(Component, String)`, `getSiblingSize(Component, String)`

#### calculateRegionalBounds

    protected java.awt.Rectangle calculateRegionalBounds(java.awt.Component c,
                                             java.lang.String region,
                                             float size)

#### getRegionSize

    public float getRegionSize(java.awt.Component c,
                      java.lang.String region)

Returns a percentage (0.0F through 1.0F) representing the amount of space allotted for the specified region within the specified `Component`.

This method resolves the `Dockable` associated with the specified `Component` and dispatches to `getRegionPreference(Dockable d, String region)`. `getRegionPreference(Dockable d, String region)` attempts to invoke `getDockingProperties()` on the `Dockable` to resolve a `DockablePropertySet` instance and return from its `getRegionInset(String region)` method.

If the specified `Component` is `null`, no `Dockable` can be resolved, or no value is specified in the `Dockable's` associated `DockingProps` instance, then the default value of `RegionChecker.DEFAULT_REGION_SIZE` is returned.

Specified by:
  `getRegionSize` in interface `RegionChecker`
Parameters:
  `c` - the `Component` whose region is to be examined.
  `region` - the specified region that is to be examined.
Returns:
  the percentage of the specified `Component` allotted for the specified region.
See Also:
  `RegionChecker.getRegionSize(Component, String)`, `DockingManager.getDockable(Component)`, `getRegionPreference(Dockable, String)`, `Dockable.getDockingProperties()`

#### getSiblingSize

    public float getSiblingSize(java.awt.Component c,
                       java.lang.String region)

Returns a percentage (0.0F through 1.0F) representing the amount of space allotted for sibling `Component` docked to the specified region within the specified `Component`.

This method resolves the `Dockable` associated with the specified `Component` and dispatches to `getSiblingPreference(Dockable d, String region)`. `getSiblingPreference(Dockable d, String region)` attempts to invoke `getDockingProperties()` on the `Dockable` to resolve a `DockablePropertySet` instance and return from its `getSiblingSize(String region)` method.

If the specified `Component` is `null`, no `Dockable` can be resolved, or no value is specified in the `Dockable's` associated `DockingProps` instance, then the default value of `RegionChecker.DEFAULT_SIBLING_SIZE` is returned.

Specified by:
  `getSiblingSize` in interface `RegionChecker`
Parameters:
  `c` - the `Component` whose sibling size is to be examined.
  `region` - the specified region that is to be examined.
Returns:
  the percentage of the specified `Component` allotted for the siblings within the specified region.
See Also:
  `DockingManager.getDockable(Component)`, `getSiblingPreference(Dockable, String)`, `Dockable.getDockingProperties()`

#### getDockingInset

    protected static float getDockingInset(java.lang.Float value,
                        float defaultVal,
                        float max,
                        float min)

#### checkBounds

    protected static float checkBounds(float val,
                    float max,
                    float min)

#### validateRegionSize

    public static float validateRegionSize(float size)

Returns `size` if it is between the values `RegionChecker.MIN_REGION_SIZE` and `RegionChecker.MAX_REGION_SIZE`. If `size` is less than `RegionChecker.MIN_REGION_SIZE`, then `RegionChecker.MIN_REGION_SIZE` is returned. If `size` is greater than `RegionChecker.MAX_REGION_SIZE`, then `RegionChecker.MAX_REGION_SIZE` is returned.

Returns:
  a valid `size` value between `RegionChecker.MIN_REGION_SIZE` and `RegionChecker.MAX_REGION_SIZE`, inclusive.

#### validateSiblingSize

    public static float validateSiblingSize(float size)

Returns `size` if it is between the values `RegionChecker.MIN_SIBILNG_SIZE` and `RegionChecker.MAX_SIBILNG_SIZE`. If `size` is less than `RegionChecker.MIN_SIBILNG_SIZE`, then `RegionChecker.MIN_SIBILNG_SIZE` is returned. If `size` is greater than `RegionChecker.MAX_SIBILNG_SIZE`, then `RegionChecker.MAX_SIBILNG_SIZE` is returned.

Returns:
  a valid `size` value between `RegionChecker.MIN_SIBILNG_SIZE` and `RegionChecker.MAX_SIBILNG_SIZE`, inclusive.

#### getRegionPreference

    public static float getRegionPreference(Dockable d,
                            java.lang.String region)

Returns a percentage (0.0F through 1.0F) representing the amount of space allotted for the specified region within the specified `Dockable`.

This method calls `getDockingProperties()` on the `Dockable` to resolve a `DockablePropertySet` instance. It then invokes `getRegionInset(String region)` on the `DockablePropertySet` to retrieve the preferred region size. If the `Dockable` is `null` or no region preference can be found, then the default value of `RegionChecker.DEFAULT_REGION_SIZE` is returned. Otherwise, the retrieved region preference is passed through `validateRegionSize(float size)` and returned.

Parameters:
  `d` - the `Dockable` whose region is to be checked
  `region` - the region of the specified `Dockable` to be checked
Returns:
  a percentage (0.0F through 1.0F) representing the amount of space allotted for the specified region within the specified `Dockable`.
See Also:
  `Dockable.getDockingProperties()`, `RegionChecker.DEFAULT_REGION_SIZE`, `validateRegionSize(float)`

#### getSiblingPreference

    public static float getSiblingPreference(Dockable d,
                             java.lang.String region)

Returns a percentage (0.0F through 1.0F) representing the amount of space allotted for sibling `Components` docked to the specified region within the specified `Dockable`.

This method calls `getDockingProperties()` on the `Dockable` to resolve a `DockablePropertySet` instance. It then invokes `getSiblingSize(String region)` on the `DockablePropertySet` to retrieve the preferred sibling size. If the `Dockable` is `null` or no sibling preference can be found, then the default value of `RegionChecker.DEFAULT_SIBLING_SIZE` is returned. Otherwise, the retrieved region preference is passed through `validateSiblingSize(float size)` and returned.

Parameters:
  `d` - the `Dockable` whose sibling size is to be checked
  `region` - the region of the specified `Dockable` to be checked
Returns:
  a percentage (0.0F through 1.0F) representing the amount of space allotted for sibling `Components` docked to the specified region within the specified `Dockable`.
See Also:
  `Dockable.getDockingProperties()`, `RegionChecker.DEFAULT_SIBLING_SIZE`, `validateSiblingSize(float)`