org.flexdock.docking

## Interface RegionChecker

- All Known Implementing Classes:
    DefaultRegionChecker

      public interface RegionChecker

  This interface provides an API for determining the desired regional bounds for a `Dockable` component. Implementing classes are responsible for determining the bounds and proportional sizes for both docking regions and sibling components. As a `Dockable` is dragged across a `DockingPort` containing another embedded `Dockable`, a determination must be made as to where the dragged `Dockable` will be docked within the target `DockingPort` based upon the current mouse position relative to the embedded `Dockable` underneath the mouse. Classes that implement this interface are responsible for making such determinations. For example, if a `Dockable` is dragged over another `Dockable` embedded within a `DockingPort`, and the current mouse position is near the top edge of the embedded `Dockable`, the current `RegionChecker` is responsible for determining whether the user is attempting to dock in the `north`, `east`, `west`, or `center` of the embedded `Dockable`. The visual `DragPreview` displayed to the end user should reflect this determination. Once the docking operation is complete and the layout has been split between both `Dockables`, the actual percentage of space allotted to the new `Dockable` in the layout, referred to as the "sibling", is also determined by the current `RegionChecker` implementation.
  Author:
    Christopher Butler, Mateusz Szczap

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static float` | `DEFAULT_REGION_SIZE` Default region size.
    `static float` | `DEFAULT_SIBLING_SIZE` Default sibling size.
    `static java.lang.String` | `DEFAULT_SIBLING_SIZE_KEY` A key to find a system property that will override the default sibling size in this interface.
    `static float` | `MAX_REGION_SIZE` Default maximum region size.
    `static float` | `MAX_SIBILNG_SIZE` Default maximum sibling size.
    `static float` | `MIN_REGION_SIZE` Default minimum region size.
    `static float` | `MIN_SIBILNG_SIZE` Default minimum sibling size.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.awt.Rectangle` | `getEastRegion(java.awt.Component component)` Returns the rectangular bounds within the specified component that represent it's `DockingConstants.EAST_REGION`.
    `java.awt.Rectangle` | `getNorthRegion(java.awt.Component component)` Returns the rectangular bounds within the specified component that represent it's `DockingConstants.NORTH_REGION`.
    `java.lang.String` | `getRegion(java.awt.Component component, 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 component, java.lang.String region)` Returns the rectangular bounds within the specified component that represent the specified region.
    `float` | `getRegionSize(java.awt.Component component, java.lang.String region)` Returns a percentage representing the amount of space allotted for the specified region within the specified `Component`.
    `java.awt.Rectangle` | `getSiblingBounds(java.awt.Component component, java.lang.String region)` A `Rectangle` representing the actual amount of space to allot for sibling `Components` should they be docked into the specified region.
    `float` | `getSiblingSize(java.awt.Component component, java.lang.String region)` Returns a percentage representing the amount of space allotted for sibling `Components` to be docked within the specified region of the supplied `Component`.
    `java.awt.Rectangle` | `getSouthRegion(java.awt.Component component)` Returns the rectangular bounds within the specified component that represent it's `DockingConstants.SOUTH_REGION`.
    `java.awt.Rectangle` | `getWestRegion(java.awt.Component component)` Returns the rectangular bounds within the specified component that represent it's `DockingConstants.WEST_REGION`.

- - ### Field Detail

    - #### MAX_REGION_SIZE

          static final float MAX_REGION_SIZE

      Default maximum region size.
      See Also:
        Constant Field Values

    - #### MIN_REGION_SIZE

          static final float MIN_REGION_SIZE

      Default minimum region size.
      See Also:
        Constant Field Values

    - #### MAX_SIBILNG_SIZE

          static final float MAX_SIBILNG_SIZE

      Default maximum sibling size.
      See Also:
        Constant Field Values

    - #### MIN_SIBILNG_SIZE

          static final float MIN_SIBILNG_SIZE

      Default minimum sibling size.
      See Also:
        Constant Field Values

    - #### DEFAULT_REGION_SIZE

          static final float DEFAULT_REGION_SIZE

      Default region size.
      See Also:
        Constant Field Values

    - #### DEFAULT_SIBLING_SIZE

          static final float DEFAULT_SIBLING_SIZE

      Default sibling size.
      See Also:
        Constant Field Values

    - #### DEFAULT_SIBLING_SIZE_KEY

          static final java.lang.String DEFAULT_SIBLING_SIZE_KEY

      A key to find a system property that will override the default sibling size in this interface.
      See Also:
        `DEFAULT_SIBLING_SIZE`, Constant Field Values

  - ### Method Detail

    - #### getRegion

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

      Returns the docking region of the supplied `Component` that contains the coordinates of the specified `Point`. Valid return values are those regions defined in `DockingConstants` and include `CENTER_REGION`, `NORTH_REGION`, `SOUTH_REGION`, `EAST_REGION`, `WEST_REGION`, or `UNKNOWN_REGION`.
      Parameters:
        `component` - 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`.

    - #### getNorthRegion

          java.awt.Rectangle getNorthRegion(java.awt.Component component)

      Returns the rectangular bounds within the specified component that represent it's `DockingConstants.NORTH_REGION`.
      Parameters:
        `component` - the `Component` whose north region is to be returned.
      Returns:
        the bounds containing the north region of the specified `Component`.

    - #### getSouthRegion

          java.awt.Rectangle getSouthRegion(java.awt.Component component)

      Returns the rectangular bounds within the specified component that represent it's `DockingConstants.SOUTH_REGION`.
      Parameters:
        `component` - the `Component` whose south region is to be returned.
      Returns:
        the bounds containing the south region of the specified `Component`.

    - #### getEastRegion

          java.awt.Rectangle getEastRegion(java.awt.Component component)

      Returns the rectangular bounds within the specified component that represent it's `DockingConstants.EAST_REGION`.
      Parameters:
        `component` - the `Component` whose east region is to be returned.
      Returns:
        the bounds containing the east region of the specified `Component`.

    - #### getWestRegion

          java.awt.Rectangle getWestRegion(java.awt.Component component)

      Returns the rectangular bounds within the specified component that represent it's `DockingConstants.WEST_REGION`.
      Parameters:
        `component` - the `Component` whose west region is to be returned.
      Returns:
        the bounds containing the west region of the specified `Component`.

    - #### getRegionBounds

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

      Returns the rectangular bounds within the specified component that represent the specified region. Valid values for the `region` parameter are those regions defined in `DockingConstants` and include `NORTH_REGION`, `SOUTH_REGION`, `EAST_REGION`, and `WEST_REGION`. All other region values should result in this method returning a `null` reference.
      Parameters:
        `component` - 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`.

    - #### getRegionSize

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

      Returns a percentage representing the amount of space allotted for the specified region within the specified `Component`. For example, a return value of 0.25F for NORTH_REGION implies that the top 25% of the supplied `Component's` bounds rectangle is to be interpreted as the `Component's` northern region. Valid values for the `region` parameter are those regions defined in `DockingConstants` and include `NORTH_REGION`, `SOUTH_REGION`, `EAST_REGION`, and `WEST_REGION`. All other region values should result in this method returning the constant `DEFAULT_SIBLING_SIZE`.
      Parameters:
        `component` - 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.

    - #### getSiblingBounds

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

      A `Rectangle` representing the actual amount of space to allot for sibling `Components` should they be docked into the specified region. This method differs from `getRegionBounds(Component c, String region)` in that `getRegionBounds()` determines the amount to space used to check whether a `Component's` docking will intersect with a particular region, whereas this method returns the actual amount of space said `Component` will take up after docking has been completed. Valid values for the `region` parameter are those regions defined in `DockingConstants` and include `NORTH_REGION`, `SOUTH_REGION`, `EAST_REGION`, and `WEST_REGION`. All other region values should result in this method returning the constant `DEFAULT_SIBLING_SIZE`.
      Parameters:
        `component` - the `Component` whose sibling bounds are to be returned.
        `region` - the specified region that is to be examined.
      Returns:
        the bounds containing the sibling bounds desired for `Components` docked into the specified region of the of the specified `Component`.

    - #### getSiblingSize

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

      Returns a percentage representing the amount of space allotted for sibling `Components` to be docked within the specified region of the supplied `Component`. This method differs from `getRegionSize(Component c, String region)` in that `getRegionSize()` determines the proportional space used to check whether a `Component's` docking will intersect with a particular region, whereas this method returns the proportional space said `Component` will take up after docking has been completed. Valid values for the `region` parameter are those regions defined in `DockingConstants` and include `NORTH_REGION`, `SOUTH_REGION`, `EAST_REGION`, and `WEST_REGION`. All other region values should result in this method returning the constant `DEFAULT_SIBLING_SIZE`.
      Parameters:
        `component` - the `Component` whose sibling proportions are to be returned.
        `region` - the specified region that is to be examined.
      Returns:
        the percentage of the specified `Component` allotted for sibling `Components` that are to be docked into the specified region.