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