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
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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.