Class DockingUtility
- java.lang.Object
-
- org.flexdock.util.DockingUtility
-
- All Implemented Interfaces:
DockingConstants
public class DockingUtility extends java.lang.Object implements DockingConstants
- Author:
- Christopher Butler
-
-
Field Summary
-
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
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static boolean
dockRelative(Dockable dockable, Dockable parent, java.lang.String relativeRegion)
Docks the specifiedDockable
relative to another already-dockedDockable
in the specified region.static boolean
dockRelative(Dockable dockable, Dockable parent, java.lang.String relativeRegion, float ratio)
Docks the specifiedDockable
relative to another already-dockedDockable
in the specified region with the specified split proportion.static DockingPort
findDockingPort(java.awt.Container container, java.awt.Point location)
Returns the deepestDockingPort
within the specifiedContainer
at the specifiedlocation
.static java.lang.String
flipRegion(java.lang.String region)
Returns the opposite docking region of the specifiedregion
.static Dockable
getAncestorDockable(java.awt.Component comp)
static int
getMinimizedConstraint(Dockable dockable)
Returns anint
value representing the current minimization constraint for the specifiedDockable
.static DockingPort
getParentDockingPort(java.awt.Component comp)
Returns theDockingPort
that contains the specifiedComponent
.static DockingPort
getParentDockingPort(Dockable d)
Returns theDockingPort
that contains the specifiedDockable
.static java.lang.String
getRegion(int regionType)
Returns theString
docking region for the specified orientation constant.static java.lang.String
getTabText(Dockable dockable)
Returns the text to be used by aDockable
as a tab label within a tabbed layout.static boolean
isActive(Dockable dockable)
static boolean
isAxisEquivalent(java.lang.String region, java.lang.String otherRegion)
Tests for region equivalency between the specified region parameters across horizontal and vertical axes.static boolean
isDockable(java.lang.Object obj)
Returnstrue
if the specificObject
is aDockable
.static boolean
isEmbedded(Dockable dockable)
Returnstrue
if the specifiedDockable
is currently docked within aDockingPort
.static boolean
isFloating(Dockable dockable)
Returnstrue
if the specifiedDockable
is currently docked within a floating dialog.static boolean
isMinimized(Dockable dockable)
Returnstrue
if the specifiedDockable
is currently minimized;false
otherwise.static boolean
isRegionTopLeft(java.lang.String region)
Returnstrue
if the specifiedregion
is equal to eitherNORTH_REGION
orWEST_REGION
.static boolean
isSubport(DockingPort dockingPort)
Returnstrue
if the specifiedDockingPort
has an ancestorDockingPort
;false
otherwise.static void
setSplitProportion(Dockable dockable, float proportion)
Sets the divider location of the split layout containing the specified dockableComponent
.static void
setSplitProportion(DockingPort port, float proportion)
Sets the divider location of the split layout embedded within the specifiedDockingPort
.static java.lang.String
translateRegionAxis(javax.swing.JSplitPane splitPane, java.lang.String region)
Returns the specifiedregion's
cross-axis equivalent region in accordance with the orientation used by the specifiedJSplitPane
.
-
-
-
Method Detail
-
getParentDockingPort
public static DockingPort getParentDockingPort(Dockable d)
Returns theDockingPort
that contains the specifiedDockable
. If theDockable
isnull
, then anull
reference is returned.This method will only return the immediate parent
DockingPort
of the specifiedDockable
This means that a check is performed for theComponent
returned by theDockable's
getComponent()
method. TheDockingPort
returned by this method will not only be an ancestorContainer
of thisComponent
, but invoking theDockingPort's
isParentDockingPort(Component comp)
with the thisComponent
will also returntrue
. If both of these conditions cannot be satisfied, then this method returns anull
reference.- Parameters:
d
- theDockable
whose parentDockingPort
is to be returned.- Returns:
- the imediate parent
DockingPort
that contains the specifiedDockable
. - See Also:
getParentDockingPort(Component)
-
getParentDockingPort
public static DockingPort getParentDockingPort(java.awt.Component comp)
Returns theDockingPort
that contains the specifiedComponent
. If theComponent
isnull
, then anull
reference is returned.This method will only return the immediate parent
DockingPort
of the specifiedComponent
This means that theDockingPort
returned by this method will not only be an ancestorContainer
of the specifiedComponent
, but invoking itsisParentDockingPort(Component comp)
with the specifiedComponent
will also returntrue
. If both of these conditions cannot be satisfied, then this method returns anull
reference.- Parameters:
comp
- theComponent
whose parentDockingPort
is to be returned.- Returns:
- the immediate parent
DockingPort
that contains the specifiedComponent
.
-
isSubport
public static boolean isSubport(DockingPort dockingPort)
Returnstrue
if the specifiedDockingPort
has an ancestorDockingPort
;false
otherwise. If the specifiedDockingPort
isnull
, then this method returnsfalse
.- Parameters:
dockingPort
- theDockingPort
to check for an ancestor port- Returns:
true
if the specifiedDockingPort
has an ancestorDockingPort
;false
otherwise.- See Also:
SwingUtilities.getAncestorOfClass(java.lang.Class, java.awt.Component)
-
findDockingPort
public static DockingPort findDockingPort(java.awt.Container container, java.awt.Point location)
Returns the deepestDockingPort
within the specifiedContainer
at the specifiedlocation
. If eithercontainer
orlocation
arenull
, then this method returnsnull
.This method will find the deepest
Component
within the specified container that the specifiedPoint
viaSwingUtilities.getDeepestComponentAt(Component parent, int x, int y)
. If noComponent
is resovled, then this method returnsnull
. If the resolvedComponent
is aDockingPort
, then it is returned. Otherwise, theComponent's
DockingPort
ancestor is resovled and returned fromSwingUtilities.getAncestorOfClass(Class c, Component comp)
, passingDockingPort.class
for the ancestor class parameter.- Parameters:
container
- theContainer
within which to find aDockingPort
.location
- the point within the specifiedContainer
at which to search for aDockingPort
.- Returns:
- the deepest
DockingPort
within the specifiedContainer
at the specifiedlocation
. - See Also:
SwingUtilities.getDeepestComponentAt(java.awt.Component, int, int)
,SwingUtilities.getAncestorOfClass(java.lang.Class, java.awt.Component)
-
translateRegionAxis
public static java.lang.String translateRegionAxis(javax.swing.JSplitPane splitPane, java.lang.String region)
Returns the specifiedregion's
cross-axis equivalent region in accordance with the orientation used by the specifiedJSplitPane
. If theJSplitPane
isnull
, or the specifiedregion
is invalid according toDockingManager.isValidDockingRegion(String region)
, then this method returnsnull
.NORTH_REGION
andSOUTH_REGION
are considered "vertical" regions, whileWEST_REGION
andEAST_REGION
are considered horizontal regions. If theJSplitPane
orientation matches the specifiedregion
orientation, then the originalregion
value is returned. For instance, if the specifiedregion
isEAST_REGION
, and theJSplitPane
is of a horizontal orientation, then there is no need to translate theregion
parameter across axes since its current axis is already horizontal. In this case,EAST_REGION
would be returned by this method.If the axis of the specified
region
does not match the orientation of theJSplitPane
, then the region is translated to its cross-axis equivalent and returns. In this case,NORTH_REGION
will be translated toWEST_REGION
,SOUTH_REGION
toEAST_REGION
,WEST_REGION
toNORTH_REGION
, andEAST_REGION
toSOUTH_REGION
.CENTER_REGION
is never altered.- Parameters:
splitPane
- theJSplitPane
whose orientation is to be used as a target axisregion
- the docking region to translate to the target axis- Returns:
- the specified
region's
cross-axis equivalent region in accordance with the orientation used by the specifiedJSplitPane
. - See Also:
DockingManager.isValidDockingRegion(String)
,JSplitPane.getOrientation()
,isAxisEquivalent(String, String)
-
flipRegion
public static java.lang.String flipRegion(java.lang.String region)
Returns the opposite docking region of the specifiedregion
. ForNORTH_REGION
, this method returnsSOUTH_REGION
. ForSOUTH_REGION
, this method returnsNORTH_REGION
. ForEAST_REGION
, this method returnsWEST_REGION
. ForWEST_REGION
, this method returnsEAST_REGION
. ForCENTER_REGION
or an invalid region, as specified byDockingManager.isValidDockingRegion(String region)
, this method returnCENTER_REGION
.- Parameters:
region
- the region whose opposite is to be returned.- Returns:
- the opposite docking region of the specified
region
. - See Also:
DockingManager.isValidDockingRegion(String)
-
isAxisEquivalent
public static boolean isAxisEquivalent(java.lang.String region, java.lang.String otherRegion)
Tests for region equivalency between the specified region parameters across horizontal and vertical axes. If eitherregion
orotherRegion
arenull
or invalid according toDockingManager.isValidDockingRegion(String region)
, then this method returnsfalse
.Equivalency within the same axis means that the two specified regions are the same value, as each region is unique within its axis. Thus, this method returns
true
ifregion.equals(otherRegion)
returnstrue
. This includesCENTER_REGION
, which is axis independent.CENTER_REGION
is not an axis equivalent to any region other than itself since it is the only docking region that does not correspond to a horizontal or vertical axis. If either the specifiedregion
orotherRegion
isCENTER_REGION
and the other is not, then this method returnsfalse
.Equivalancy across axes follows a top-to-left and bottom-to-right mapping. In this fashion,
NORTH_REGION
andWEST_REGION
are equivalent andSOUTH_REGION
andEAST_REGION
are equivalent. These combination will returntrue
for this method. All other region combinatinos will cause this method to returnfalse
.- Parameters:
region
- the first region to check for equivalencyotherRegion
- the second region to check for equivalency- Returns:
true
if the two specified regions are equal or cross-axis equivalents,false
otherwise.- See Also:
DockingManager.isValidDockingRegion(String)
-
isRegionTopLeft
public static boolean isRegionTopLeft(java.lang.String region)
Returnstrue
if the specifiedregion
is equal to eitherNORTH_REGION
orWEST_REGION
. Returnsfalse
otherwise.- Parameters:
region
- theregion
to check for top or left equivalency- Returns:
true
if the specifiedregion
is equal to eitherNORTH_REGION
orWEST_REGION
;false
otherwise.- See Also:
DockingConstants.NORTH_REGION
,DockingConstants.WEST_REGION
-
getRegion
public static java.lang.String getRegion(int regionType)
Returns theString
docking region for the specified orientation constant.LEFT
maps toWEST_REGION
,RIGHT
maps toEAST_REGION
,TOP
maps toNORTH_REGION
,BOTTOM
maps toSOUTH_REGION
, andCENTER
maps toCENTER_REGION
. All other integer values will cause this method to returnUNKNOWN_REGION
.All constants, both integer an
String
values, can be found on theDockingConstants
interface.- Parameters:
regionType
- the orientation constant to translate into a docking region- Returns:
- the
String
docking region for the specified orientation constant. - See Also:
DockingConstants.LEFT
,DockingConstants.RIGHT
,DockingConstants.TOP
,DockingConstants.BOTTOM
,DockingConstants.CENTER
,DockingConstants.WEST_REGION
,DockingConstants.EAST_REGION
,DockingConstants.NORTH_REGION
,DockingConstants.SOUTH_REGION
,DockingConstants.CENTER_REGION
,DockingConstants.UNKNOWN_REGION
-
isMinimized
public static boolean isMinimized(Dockable dockable)
Returnstrue
if the specifiedDockable
is currently minimized;false
otherwise. If theDockable
isnull
, then this method returnsfalse
.This method retrieves the current
DockingState
instance associated with theDockable
and calls it'sisMinimized()
method to return.DockingState
for the specifiedDockable
is queried by callinggetDockingState(Dockable dockable)
on theDockingManager's
currently installedLayoutManager
.- Parameters:
dockable
- theDockable
whose minimized state is to be returned- Returns:
true
if the specifiedDockable
is currently minimized;false
otherwise.- See Also:
DockingState.isMinimized()
,DockingManager.getLayoutManager()
,LayoutManager.getDockingState(Dockable)
-
getMinimizedConstraint
public static int getMinimizedConstraint(Dockable dockable)
Returns anint
value representing the current minimization constraint for the specifiedDockable
. If theDockable
isnull
, then this method returnsMinimizationManager.UNSPECIFIED_LAYOUT_CONSTRAINT
.This method retrieves the current
DockingState
instance associated with theDockable
and calls it'sgetMinimizedConstraint()
method to return.DockingState
for the specifiedDockable
is queried by callinggetDockingState(Dockable dockable)
on theDockingManager's
currently installedLayoutManager
.- Parameters:
dockable
- theDockable
whose minimized constraint is to be returned- Returns:
- an
int
value representing the current minimization constraint for the specifiedDockable
- See Also:
MinimizationManager.UNSPECIFIED_LAYOUT_CONSTRAINT
,DockingManager.getLayoutManager()
,LayoutManager.getDockingState(Dockable)
-
dockRelative
public static boolean dockRelative(Dockable dockable, Dockable parent, java.lang.String relativeRegion)
Docks the specifiedDockable
relative to another already-dockedDockable
in the specified region. The "parent"Dockable
must currently be docked. If not, this method will returnfalse
. Otherwise, its parentDockingPort
will be resolved and the newDockable
will be docked into theDockingPort
relative to the "parent"Dockable
. This method defers processing todockRelative(Dockable dockable, Dockable parent, String relativeRegion, float ratio)
passingUNSPECIFIED_SIBLING_PREF
for theratio
parameter.This method returns
false
if any of the input parameters arenull
or if the specifiedregion
is invalid according toDockingManager.isValidDockingRegion(String region)
. If the specified region is other than CENTER, then a split layout should result.- Parameters:
dockable
- theDockable
to be dockedparent
- theDockable
used as a reference point for dockingrelativeRegion
- the docking region into whichdockable
will be docked- Returns:
true
if the docking operation was successful;false
otherwise.- See Also:
dockRelative(Dockable, Dockable, String, float)
,DockingManager.isValidDockingRegion(String)
,Dockable.getDockingPort()
,DockingManager.dock(Dockable, DockingPort, String)
-
dockRelative
public static boolean dockRelative(Dockable dockable, Dockable parent, java.lang.String relativeRegion, float ratio)
Docks the specifiedDockable
relative to another already-dockedDockable
in the specified region with the specified split proportion. The "parent"Dockable
must currently be docked. If not, this method will returnfalse
. Otherwise, its parentDockingPort
will be resolved and the newDockable
will be docked into theDockingPort
relative to the "parent"Dockable
. If the specified region is CENTER, then theproportion
parameter is ignored. Otherwise, a split layout should result with the proportional space specified in theproportion
parameter allotted to thedockable
argument.This method returns
false
if any of the input parameters arenull
or if the specifiedregion
is invalid according toDockingManager.isValidDockingRegion(String region)
.- Parameters:
dockable
- theDockable
to be dockedparent
- theDockable
used as a reference point for dockingrelativeRegion
- the docking region into whichdockable
will be dockedratio
- the proportional space to allot thedockable
argument if the docking operation results in a split layout.- Returns:
true
if the docking operation was successful;false
otherwise.- See Also:
DockingManager.isValidDockingRegion(String)
,Dockable.getDockingPort()
,DockingManager.dock(Dockable, DockingPort, String)
-
isFloating
public static boolean isFloating(Dockable dockable)
Returnstrue
if the specifiedDockable
is currently docked within a floating dialog. This method returnsfalse
if theDockable
is presently, minimized, hidden, docked within the main application layout, or if theDockable
parameter isnull
.This method retrieves the current
DockingState
instance associated with theDockable
and calls it'sisFloating()
method to return.DockingState
for the specifiedDockable
is queried by callinggetDockingState(Dockable dockable)
on theDockingManager's
currently installedLayoutManager
.- Parameters:
dockable
- theDockable
whose floating state is to be returned- Returns:
true
if the specifiedDockable
is currently floating;false
otherwise.- See Also:
DockingState.isFloating()
,DockingManager.getLayoutManager()
,LayoutManager.getDockingState(Dockable)
-
isEmbedded
public static boolean isEmbedded(Dockable dockable)
Returnstrue
if the specifiedDockable
is currently docked within aDockingPort
. This method returnsfalse
if theDockable
is presently floating, minimized, hidden, or if theDockable
parameter isnull
.- Parameters:
dockable
- theDockable
whose embedded state is to be returned- Returns:
true
if the specifiedDockable
is currently docked within aDockingPort
;false
otherwise.- See Also:
DockingManager.isDocked(Dockable)
,isFloating(Dockable)
-
setSplitProportion
public static void setSplitProportion(DockingPort port, float proportion)
Sets the divider location of the split layout embedded within the specifiedDockingPort
. This method differs from bothsetSplitProportion(Dockable dockable, float proportion)
in that this method resolves the split layout embedded within the specifiedDockingPort
, whereas the other method modifies the split layout containing its respectiveDockable
parameter.The resulting divider location will be a percentage of the split layout size based upon the
proportion
parameter. Valid values forproportion
range from0.0F{@code to {@code 1.0F}. For example, a {@code proportion} of {@code 0.3F} will move the divider to 30% of the "size" (<i>width</i> for horizontal split, <i>height</i> for vertical split) of the split container embedded within the specified {@code DockingPort}. If a {@code proportion} of less than {@code 0.0F} is supplied, the value }0.0F
is used. If aproportion
greater than1.0F
is supplied, the value }1.0F} is used.This method should be effective regardless of whether the split layout in question has been fully realized and is currently visible on the screen. This should alleviate common problems associated with setting percentages of unrealized
Component
dimensions, which are initially0x0
before theComponent
has been rendered to the screen.If the specified
DockingPort
isnull
, then noException
is thrown and no action is taken. Identical behavior occurs if theDockingPort
does not contain split layout.- Parameters:
port
- theDockingPort
containing the split layout is to be resized.proportion
- the percentage of split layout size to which the split divider should be set.- See Also:
SwingUtility.setSplitDivider(JSplitPane, float)
-
setSplitProportion
public static void setSplitProportion(Dockable dockable, float proportion)
Sets the divider location of the split layout containing the specified dockableComponent
.The resulting divider location will be a percentage of the split layout size based upon the
proportion
parameter. Valid values forproportion
range from0.0F{@code to {@code 1.0F}. For example, a {@code proportion} of {@code 0.3F} will move the divider to 30% of the "size" (<i>width</i> for horizontal split, <i>height</i> for vertical split) of the split container that contains the specified {@code Dockable}. If a {@code proportion} of less than {@code 0.0F} is supplied, the value }0.0F
is used. If aproportion
greater than1.0F
is supplied, the value }1.0F} is used.It is important to note that the split divider location is only a percentage of the container size from left to right or top to bottom. A
proportion
of0.3F
does not imply thatdockable
itself will be allotted 30% of the available space. The split divider will be moved to the 30% position of the split container regardless of the region in which the specifiedDockable
resides (which may possibly result indockable
being allotted 70% of the available space).This method should be effective regardless of whether the split layout in question has been fully realized and is currently visible on the screen. This should alleviate common problems associated with setting percentages of unrealized
Component
dimensions, which are initially0x0
before theComponent
has been rendered to the screen.If the specified
Dockable
isnull
, then noException
is thrown and no action is taken. Identical behavior occurs if theDockable
does not reside within a split layout.If the
Dockable
resides within a tabbed layout, a check is done to see if the tabbed layout resides within a parent split layout. If so, the resolved split layout is resized. Otherwise no action is taken.- Parameters:
dockable
- theDockable
whose containing split layout is to be resized.proportion
- the percentage of containing split layout size to which the split divider should be set.- See Also:
SwingUtility.setSplitDivider(JSplitPane, float)
-
getTabText
public static java.lang.String getTabText(Dockable dockable)
Returns the text to be used by aDockable
as a tab label within a tabbed layout. This method retrieves the associatedDockablePropertySet
by callinggetDockingProperties()
on the specifiedDockable
. It then returns the value retrieved from callinggetDockableDesc()
on theDockablePropertySet
instance. If the specifiedDockable
isnull
, then this method returnsnull
.- Parameters:
dockable
- theDockable
whose tab-text is to be returned- Returns:
- the text to be used by a
Dockable
as a tab label within a tabbed layout. - See Also:
Dockable.getDockingProperties()
,DockablePropertySet.getDockableDesc()
-
isDockable
public static boolean isDockable(java.lang.Object obj)
Returnstrue
if the specificObject
is aDockable
. Ifobj instanceof Dockable
istrue
, then this method returnstrue
. Anull
parameter will cause this method to returnfalse
.Registered
Dockable
components, if they areJComponents
, will also have aBoolean
client property present with the keyDockable.DOCKABLE_INDICATOR
, used by dockableJComponents
that don't implement theDockable
interface directly, but acquire docking capabilities through a separate wrapperDockable
implementation. For these components, theinstanceof
check is insufficient since the validDockable
is implemented by a separate class. Therefore, if theinstanceof
check fails, and the suppliedObject
parameter is aJComponent
, a client property with the keyDockable.DOCKABLE_INDICATOR
is checked for a value ofBoolean.TRUE
. If the client property is present, then this method returnstrue
.- Parameters:
obj
- theObject
to be checked to see if it represents a validDockable
- Returns:
true
if the specificObject
is aDockable
- See Also:
Dockable.DOCKABLE_INDICATOR
,Boolean.TRUE
,JComponent.getClientProperty(java.lang.Object)
-
getAncestorDockable
public static Dockable getAncestorDockable(java.awt.Component comp)
-
isActive
public static boolean isActive(Dockable dockable)
-
-