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