public class DockingUtility extends Object implements 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
Modifier and Type | Method and Description |
---|---|
static boolean |
dockRelative(Dockable dockable,
Dockable parent,
String relativeRegion)
Docks the specified
Dockable relative to another already-docked
Dockable in the specified region. |
static boolean |
dockRelative(Dockable dockable,
Dockable parent,
String relativeRegion,
float ratio)
Docks the specified
Dockable relative to another already-docked
Dockable in the specified region with the specified split
proportion. |
static DockingPort |
findDockingPort(Container container,
Point location)
Returns the deepest
DockingPort within the specified
Container at the specified location . |
static String |
flipRegion(String region)
Returns the opposite docking region of the specified
region . |
static Dockable |
getAncestorDockable(Component comp) |
static int |
getMinimizedConstraint(Dockable dockable)
Returns an
int value representing the current minimization
constraint for the specified Dockable . |
static DockingPort |
getParentDockingPort(Component comp)
Returns the
DockingPort that contains the specified
Component . |
static DockingPort |
getParentDockingPort(Dockable d)
Returns the
DockingPort that contains the specified
Dockable . |
static String |
getRegion(int regionType)
Returns the
String docking region for the specified orientation
constant. |
static String |
getTabText(Dockable dockable)
Returns the text to be used by a
Dockable as a tab label within a
tabbed layout. |
static boolean |
isActive(Dockable dockable) |
static boolean |
isAxisEquivalent(String region,
String otherRegion)
Tests for region equivalency between the specified region parameters
across horizontal and vertical axes.
|
static boolean |
isDockable(Object obj)
Returns
true if the specific Object is a Dockable . |
static boolean |
isEmbedded(Dockable dockable)
Returns
true if the specified Dockable is currently
docked within a DockingPort . |
static boolean |
isFloating(Dockable dockable)
Returns
true if the specified Dockable is currently
docked within a floating dialog. |
static boolean |
isMinimized(Dockable dockable)
Returns
true if the specified Dockable is currently
minimized; false otherwise. |
static boolean |
isRegionTopLeft(String region)
Returns
true if the specified region is equal to either
NORTH_REGION or WEST_REGION . |
static boolean |
isSubport(DockingPort dockingPort)
Returns
true if the specified DockingPort has an ancestor
DockingPort ; false otherwise. |
static void |
setSplitProportion(Dockable dockable,
float proportion)
Sets the divider location of the split layout containing the specified
dockable
Component . |
static void |
setSplitProportion(DockingPort port,
float proportion)
Sets the divider location of the split layout embedded within the
specified
DockingPort . |
static String |
translateRegionAxis(JSplitPane splitPane,
String region)
Returns the specified
region's cross-axis equivalent region in
accordance with the orientation used by the specified JSplitPane . |
public static DockingPort getParentDockingPort(Dockable d)
DockingPort
that contains the specified
Dockable
. If the Dockable
is null
, then a
null
reference is returned.
This method will only return the immediate parent DockingPort
of
the specified Dockable
This means that a check is performed for
the Component
returned by the Dockable's
getComponent()
method. The DockingPort
returned by this
method will not only be an ancestor Container
of this
Component
, but invoking the DockingPort's
isParentDockingPort(Component comp)
with the this
Component
will also return true
. If both of these
conditions cannot be satisfied, then this method returns a null
reference.
d
- the Dockable
whose parent DockingPort
is to be
returned.DockingPort
that contains the
specified Dockable
.getParentDockingPort(Component)
public static DockingPort getParentDockingPort(Component comp)
DockingPort
that contains the specified
Component
. If the Component
is null
, then a
null
reference is returned.
This method will only return the immediate parent DockingPort
of
the specified Component
This means that the DockingPort
returned by this method will not only be an ancestor Container
of
the specified Component
, but invoking its
isParentDockingPort(Component comp)
with the specified
Component
will also return true
. If both of these
conditions cannot be satisfied, then this method returns a null
reference.
comp
- the Component
whose parent DockingPort
is to
be returned.DockingPort
that contains the
specified Component
.public static boolean isSubport(DockingPort dockingPort)
true
if the specified DockingPort
has an ancestor
DockingPort
; false
otherwise. If the specified
DockingPort
is null
, then this method returns
false
.dockingPort
- the DockingPort
to check for an ancestor porttrue
if the specified DockingPort
has an ancestor
DockingPort
; false
otherwise.SwingUtilities.getAncestorOfClass(java.lang.Class,
java.awt.Component)
public static DockingPort findDockingPort(Container container, Point location)
DockingPort
within the specified
Container
at the specified location
. If either
container
or location
are null
, then this method
returns null
.
This method will find the deepest Component
within the specified
container that the specified Point
via
SwingUtilities.getDeepestComponentAt(Component parent, int x, int y)
.
If no Component
is resovled, then this method returns
null
. If the resolved Component
is a DockingPort
,
then it is returned. Otherwise, the Component's
DockingPort
ancestor is resovled and returned from
SwingUtilities.getAncestorOfClass(Class c, Component comp)
,
passing DockingPort.class
for the ancestor class parameter.
container
- the Container
within which to find a
DockingPort
.location
- the point within the specified Container
at which to
search for a DockingPort
.DockingPort
within the specified
Container
at the specified location
.SwingUtilities.getDeepestComponentAt(java.awt.Component, int, int)
,
SwingUtilities.getAncestorOfClass(java.lang.Class,
java.awt.Component)
public static String translateRegionAxis(JSplitPane splitPane, String region)
region's
cross-axis equivalent region in
accordance with the orientation used by the specified JSplitPane
.
If the JSplitPane
is null
, or the specified
region
is invalid according to
DockingManager.isValidDockingRegion(String region)
, then this
method returns null
.
NORTH_REGION
and SOUTH_REGION
are considered "vertical"
regions, while WEST_REGION
and EAST_REGION
are considered
horizontal regions. If the JSplitPane
orientation matches the
specified region
orientation, then the original region
value is returned. For instance, if the specified region
is
EAST_REGION
, and the JSplitPane
is of a horizontal
orientation, then there is no need to translate the region
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 the JSplitPane
, then the region is translated to
its cross-axis equivalent and returns. In this case, NORTH_REGION
will be translated to WEST_REGION
, SOUTH_REGION
to
EAST_REGION
, WEST_REGION
to NORTH_REGION
, and
EAST_REGION
to SOUTH_REGION
. CENTER_REGION
is
never altered.
splitPane
- the JSplitPane
whose orientation is to be used as a
target axisregion
- the docking region to translate to the target axisregion's
cross-axis equivalent region in
accordance with the orientation used by the specified
JSplitPane
.DockingManager.isValidDockingRegion(String)
,
JSplitPane.getOrientation()
,
isAxisEquivalent(String, String)
public static String flipRegion(String region)
region
. For
NORTH_REGION
, this method returns SOUTH_REGION
. For
SOUTH_REGION
, this method returns NORTH_REGION
. For
EAST_REGION
, this method returns WEST_REGION
. For
WEST_REGION
, this method returns EAST_REGION
. For
CENTER_REGION
or an invalid region, as specified by
DockingManager.isValidDockingRegion(String region)
, this method
return CENTER_REGION
.region
- the region whose opposite is to be returned.region
.DockingManager.isValidDockingRegion(String)
public static boolean isAxisEquivalent(String region, String otherRegion)
region
or
otherRegion
are null
or invalid according to
DockingManager.isValidDockingRegion(String region)
, then this
method returns false
.
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
if region.equals(otherRegion)
returns
true
. This includes CENTER_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 specified region
or
otherRegion
is CENTER_REGION
and the other is not, then
this method returns false
.
Equivalancy across axes follows a top-to-left and bottom-to-right
mapping. In this fashion, NORTH_REGION
and WEST_REGION
are equivalent and SOUTH_REGION
and EAST_REGION
are
equivalent. These combination will return true
for this method.
All other region combinatinos will cause this method to return
false
.
region
- the first region to check for equivalencyotherRegion
- the second region to check for equivalencytrue
if the two specified regions are equal or cross-axis
equivalents, false
otherwise.DockingManager.isValidDockingRegion(String)
public static boolean isRegionTopLeft(String region)
true
if the specified region
is equal to either
NORTH_REGION
or WEST_REGION
. Returns false
otherwise.region
- the region
to check for top or left equivalencytrue
if the specified region
is equal to either
NORTH_REGION
or WEST_REGION
; false
otherwise.DockingConstants.NORTH_REGION
,
DockingConstants.WEST_REGION
public static String getRegion(int regionType)
String
docking region for the specified orientation
constant. LEFT
maps to WEST_REGION
, RIGHT
maps
to EAST_REGION
, TOP
maps to NORTH_REGION
,
BOTTOM
maps to SOUTH_REGION
, and CENTER
maps to
CENTER_REGION
. All other integer values will cause this method
to return UNKNOWN_REGION
.
All constants, both integer an String
values, can be found on the
DockingConstants
interface.
regionType
- the orientation constant to translate into a docking regionString
docking region for the specified orientation
constant.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
public static boolean isMinimized(Dockable dockable)
true
if the specified Dockable
is currently
minimized; false
otherwise. If the Dockable
is
null
, then this method returns false
.
This method retrieves the current DockingState
instance
associated with the Dockable
and calls it's isMinimized()
method to return. DockingState
for the specified Dockable
is queried by calling getDockingState(Dockable dockable)
on the
DockingManager's
currently installed LayoutManager
.
dockable
- the Dockable
whose minimized state is to be returnedtrue
if the specified Dockable
is currently
minimized; false
otherwise.DockingState.isMinimized()
,
DockingManager.getLayoutManager()
,
LayoutManager.getDockingState(Dockable)
public static int getMinimizedConstraint(Dockable dockable)
int
value representing the current minimization
constraint for the specified Dockable
. If the Dockable
is null
, then this method returns
MinimizationManager.UNSPECIFIED_LAYOUT_CONSTRAINT
.
This method retrieves the current DockingState
instance
associated with the Dockable
and calls it's
getMinimizedConstraint()
method to return. DockingState
for the specified Dockable
is queried by calling
getDockingState(Dockable dockable)
on the
DockingManager's
currently installed LayoutManager
.
dockable
- the Dockable
whose minimized constraint is to be
returnedint
value representing the current minimization
constraint for the specified Dockable
MinimizationManager.UNSPECIFIED_LAYOUT_CONSTRAINT
,
DockingState.getMinimizedConstraint()()
,
DockingManager.getLayoutManager()
,
LayoutManager.getDockingState(Dockable)
public static boolean dockRelative(Dockable dockable, Dockable parent, String relativeRegion)
Dockable
relative to another already-docked
Dockable
in the specified region. The "parent" Dockable
must currently be docked. If not, this method will return false
.
Otherwise, its parent DockingPort
will be resolved and the new
Dockable
will be docked into the DockingPort
relative to
the "parent" Dockable
. This method defers processing to
dockRelative(Dockable dockable, Dockable parent, String relativeRegion, float ratio)
passing UNSPECIFIED_SIBLING_PREF
for the ratio
parameter.
This method returns false
if any of the input parameters are
null
or if the specified region
is invalid according to
DockingManager.isValidDockingRegion(String region)
. If the
specified region is other than CENTER, then a split layout should result.
dockable
- the Dockable
to be dockedparent
- the Dockable
used as a reference point for dockingrelativeRegion
- the docking region into which dockable
will be dockedtrue
if the docking operation was successful;
false
otherwise.dockRelative(Dockable, Dockable, String, float)
,
DockingManager.isValidDockingRegion(String)
,
Dockable.getDockingPort()
,
DockingManager.dock(Dockable, DockingPort, String)
public static boolean dockRelative(Dockable dockable, Dockable parent, String relativeRegion, float ratio)
Dockable
relative to another already-docked
Dockable
in the specified region with the specified split
proportion. The "parent" Dockable
must currently be docked. If
not, this method will return false
. Otherwise, its parent
DockingPort
will be resolved and the new Dockable
will be
docked into the DockingPort
relative to the "parent"
Dockable
. If the specified region is CENTER, then the
proportion
parameter is ignored. Otherwise, a split layout should
result with the proportional space specified in the proportion
parameter allotted to the dockable
argument.
This method returns false
if any of the input parameters are
null
or if the specified region
is invalid according to
DockingManager.isValidDockingRegion(String region)
.
dockable
- the Dockable
to be dockedparent
- the Dockable
used as a reference point for dockingrelativeRegion
- the docking region into which dockable
will be dockedratio
- the proportional space to allot the dockable
argument
if the docking operation results in a split layout.true
if the docking operation was successful;
false
otherwise.DockingManager.isValidDockingRegion(String)
,
Dockable.getDockingPort()
,
DockingManager.dock(Dockable, DockingPort, String)
public static boolean isFloating(Dockable dockable)
true
if the specified Dockable
is currently
docked within a floating dialog. This method returns false
if the
Dockable
is presently, minimized, hidden, docked within the main
application layout, or if the Dockable
parameter is null
.
This method retrieves the current DockingState
instance
associated with the Dockable
and calls it's isFloating()
method to return. DockingState
for the specified Dockable
is queried by calling getDockingState(Dockable dockable)
on the
DockingManager's
currently installed LayoutManager
.
dockable
- the Dockable
whose floating state is to be returnedtrue
if the specified Dockable
is currently
floating; false
otherwise.DockingState.isFloating()
,
DockingManager.getLayoutManager()
,
LayoutManager.getDockingState(Dockable)
public static boolean isEmbedded(Dockable dockable)
true
if the specified Dockable
is currently
docked within a DockingPort
. This method returns false
if the Dockable
is presently floating, minimized, hidden, or if
the Dockable
parameter is null
.dockable
- the Dockable
whose embedded state is to be returnedtrue
if the specified Dockable
is currently
docked within a DockingPort
; false
otherwise.DockingManager.isDocked(Dockable)
,
isFloating(Dockable)
public static void setSplitProportion(DockingPort port, float proportion)
DockingPort
. This method differs from both
setSplitProportion(Dockable dockable, float proportion)
in that
this method resolves the split layout embedded within the
specified DockingPort
, whereas the other method modifies the
split layout containing its respective Dockable
parameter.
The resulting divider location will be a percentage of the split layout
size based upon the proportion
parameter. Valid values for
proportion
range from 0.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 a proportion
greater
than 1.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 initially
0x0
before the Component
has been rendered to the screen.
If the specified DockingPort
is null
, then no
Exception
is thrown and no action is taken. Identical behavior
occurs if the DockingPort
does not contain split layout.
port
- the DockingPort
containing the split layout is to be
resized.proportion
- the percentage of split layout size to which the split divider
should be set.SwingUtility.setSplitDivider(JSplitPane, float)
public static void setSplitProportion(Dockable dockable, float proportion)
Component
.
The resulting divider location will be a percentage of the split layout
size based upon the proportion
parameter. Valid values for
proportion
range from 0.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 a proportion
greater than
1.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
of 0.3F
does not imply that dockable
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 specified Dockable
resides (which may
possibly result in dockable
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 initially
0x0
before the Component
has been rendered to the screen.
If the specified Dockable
is null
, then no
Exception
is thrown and no action is taken. Identical behavior
occurs if the Dockable
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.
dockable
- the Dockable
whose containing split layout is to be
resized.proportion
- the percentage of containing split layout size to which the
split divider should be set.SwingUtility.setSplitDivider(JSplitPane, float)
public static String getTabText(Dockable dockable)
Dockable
as a tab label within a
tabbed layout. This method retrieves the associated
DockablePropertySet
by calling getDockingProperties()
on
the specified Dockable
. It then returns the value retrieved from
calling getDockableDesc()
on the DockablePropertySet
instance. If the specified Dockable
is null
, then this
method returns null
.dockable
- the Dockable
whose tab-text is to be returnedDockable
as a tab label within a
tabbed layout.Dockable.getDockingProperties()
,
DockablePropertySet.getDockableDesc()
public static boolean isDockable(Object obj)
true
if the specific Object
is a Dockable
.
If obj instanceof Dockable
is true
, then this method
returns true
. A null
parameter will cause this method to
return false
.
Registered Dockable
components, if they are JComponents
,
will also have a Boolean
client property present with the key
Dockable.DOCKABLE_INDICATOR
, used by dockable
JComponents
that don't implement the Dockable
interface
directly, but acquire docking capabilities through a separate wrapper
Dockable
implementation. For these components, the
instanceof
check is insufficient since the valid Dockable
is implemented by a separate class. Therefore, if the instanceof
check fails, and the supplied Object
parameter is a
JComponent
, a client property with the key
Dockable.DOCKABLE_INDICATOR
is checked for a value of
Boolean.TRUE
. If the client property is present, then this
method returns true
.
obj
- the Object
to be checked to see if it represents a
valid Dockable
true
if the specific Object
is a Dockable
Dockable.DOCKABLE_INDICATOR
,
Boolean.TRUE
,
JComponent.getClientProperty(java.lang.Object)
public static boolean isActive(Dockable dockable)