org.flexdock.docking.RegionChecker Maven / Gradle / Ivy
The newest version!
/*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package org.flexdock.docking;
import java.awt.Component;
import java.awt.Point;
import java.awt.Rectangle;
/**
* This interface provides an API for determining the desired regional bounds
* for a {@code Dockable} component. Implementing classes are responsible for
* determining the bounds and proportional sizes for both docking regions and
* sibling components.
*
* As a {@code Dockable} is dragged across a {@code DockingPort} containing
* another embedded {@code Dockable}, a determination must be made as to where
* the dragged {@code Dockable} will be docked within the target
* {@code DockingPort} based upon the current mouse position relative to
* the embedded {@code Dockable} underneath the mouse. Classes that implement
* this interface are responsible for making such determinations.
*
* For example, if a {@code Dockable} is dragged over another {@code Dockable}
* embedded within a {@code DockingPort}, and the current mouse position is
* near the top edge of the embedded {@code Dockable}, the current
* {@code RegionChecker} is responsible for determining whether the user is
* attempting to dock in the {@code north}, {@code east}, {@code west}, or
* {@code center} of the embedded {@code Dockable}. The visual
* {@code DragPreview} displayed to the end user should reflect this
* determination.
*
* Once the docking operation is complete and the layout has been split between
* both {@code Dockables}, the actual percentage of space allotted to the new
* {@code Dockable} in the layout, referred to as the "sibling", is also
* determined by the current {@code RegionChecker} implementation.
*
* @author Christopher Butler
* @author Mateusz Szczap
*/
public interface RegionChecker {
/**
* Default maximum region size.
*/
float MAX_REGION_SIZE = .5F;
/**
* Default minimum region size.
*/
float MIN_REGION_SIZE = .0F;
/**
* Default maximum sibling size.
*/
float MAX_SIBILNG_SIZE = 1F;
/**
* Default minimum sibling size.
*/
float MIN_SIBILNG_SIZE = .0F;
/**
* Default region size.
*/
float DEFAULT_REGION_SIZE = .25F;
/**
* Default sibling size.
*/
float DEFAULT_SIBLING_SIZE = .5F;
/**
* A key to find a system property that will override the default sibling
* size in this interface.
*
* @see #DEFAULT_SIBLING_SIZE
*/
String DEFAULT_SIBLING_SIZE_KEY = "default.sibling.size";
/**
* Returns the docking region of the supplied {@code Component} that
* contains the coordinates of the specified {@code Point}. Valid return
* values are those regions defined in {@code DockingConstants} and include
* {@code CENTER_REGION}, {@code NORTH_REGION}, {@code SOUTH_REGION},
* {@code EAST_REGION}, {@code WEST_REGION}, or {@code UNKNOWN_REGION}.
*
* @param component
* the {@code Component} whose region is to be examined.
* @param point
* the coordinates whose region is to be determined.
* @return the docking region containing the specified {@code Point}.
*/
String getRegion(Component component, Point point);
/**
* Returns the rectangular bounds within the specified component that
* represent it's {@code DockingConstants.NORTH_REGION}.
*
* @param component
* the {@code Component} whose north region is to be returned.
* @return the bounds containing the north region of the specified
* {@code Component}.
*/
Rectangle getNorthRegion(Component component);
/**
* Returns the rectangular bounds within the specified component that
* represent it's {@code DockingConstants.SOUTH_REGION}.
*
* @param component
* the {@code Component} whose south region is to be returned.
* @return the bounds containing the south region of the specified
* {@code Component}.
*/
Rectangle getSouthRegion(Component component);
/**
* Returns the rectangular bounds within the specified component that
* represent it's {@code DockingConstants.EAST_REGION}.
*
* @param component
* the {@code Component} whose east region is to be returned.
* @return the bounds containing the east region of the specified
* {@code Component}.
*/
Rectangle getEastRegion(Component component);
/**
* Returns the rectangular bounds within the specified component that
* represent it's {@code DockingConstants.WEST_REGION}.
*
* @param component
* the {@code Component} whose west region is to be returned.
* @return the bounds containing the west region of the specified
* {@code Component}.
*/
Rectangle getWestRegion(Component component);
/**
* Returns the rectangular bounds within the specified component that
* represent the specified region. Valid values for the {@code region}
* parameter are those regions defined in {@code DockingConstants} and
* include {@code NORTH_REGION}, {@code SOUTH_REGION}, {@code EAST_REGION},
* and {@code WEST_REGION}. All other region values should result in this
* method returning a {@code null} reference.
*
* @param component
* the {@code Component} whose region bounds are to be returned.
* @param region
* the specified region that is to be examined.
* @return the bounds containing the supplied region of the specified
* {@code Component}.
*/
Rectangle getRegionBounds(Component component, String region);
/**
* Returns a percentage representing the amount of space allotted for the
* specified region within the specified {@code Component}. For example, a
* return value of 0.25F for NORTH_REGION implies that the top 25% of the
* supplied {@code Component's} bounds rectangle is to be interpreted as the
* {@code Component's} northern region. Valid values for the {@code region}
* parameter are those regions defined in {@code DockingConstants} and
* include {@code NORTH_REGION}, {@code SOUTH_REGION}, {@code EAST_REGION},
* and {@code WEST_REGION}. All other region values should result in this
* method returning the constant {@code DEFAULT_SIBLING_SIZE}.
*
* @param component
* the {@code Component} whose region is to be examined.
* @param region
* the specified region that is to be examined.
* @return the percentage of the specified {@code Component} allotted for
* the specified region.
*/
float getRegionSize(Component component, String region);
/**
* A {@code Rectangle} representing the actual amount of space to allot for
* sibling {@code Components} should they be docked into the specified
* region. This method differs from
* {@code getRegionBounds(Component c, String region)} in that
* {@code getRegionBounds()} determines the amount to space used to check
* whether a {@code Component's} docking will intersect with a particular
* region, whereas this method returns the actual amount of space said
* {@code Component} will take up after docking has been completed. Valid
* values for the {@code region} parameter are those regions defined in
* {@code DockingConstants} and include {@code NORTH_REGION},
* {@code SOUTH_REGION}, {@code EAST_REGION}, and {@code WEST_REGION}.
* All other region values should result in this method returning the
* constant {@code DEFAULT_SIBLING_SIZE}.
*
* @param component
* the {@code Component} whose sibling bounds are to be returned.
* @param region
* the specified region that is to be examined.
* @return the bounds containing the sibling bounds desired for
* {@code Components} docked into the specified region of the of the
* specified {@code Component}.
*/
Rectangle getSiblingBounds(Component component, String region);
/**
* Returns a percentage representing the amount of space allotted for
* sibling {@code Components} to be docked within the specified region of
* the supplied {@code Component}. This method differs from
* {@code getRegionSize(Component c, String region)} in that
* {@code getRegionSize()} determines the proportional space used to check
* whether a {@code Component's} docking will intersect with a particular
* region, whereas this method returns the proportional space said
* {@code Component} will take up after docking has been completed. Valid
* values for the {@code region} parameter are those regions defined in
* {@code DockingConstants} and include {@code NORTH_REGION},
* {@code SOUTH_REGION}, {@code EAST_REGION}, and {@code WEST_REGION}.
* All other region values should result in this method returning the
* constant {@code DEFAULT_SIBLING_SIZE}.
*
* @param component
* the {@code Component} whose sibling proportions are to be
* returned.
* @param region
* the specified region that is to be examined.
* @return the percentage of the specified {@code Component} allotted for
* sibling {@code Components} that are to be docked into the
* specified region.
*/
float getSiblingSize(Component component, String region);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy