bibliothek.gui.dock.common
Class CLocation

java.lang.Object
  bibliothek.gui.dock.common.CLocation

Direct Known Subclasses:

AbstractStackholdingLocation, CBaseLocation, CExtendedModeLocation, CFlapLocation, CSplitLocation

public abstract class CLocation
extends Object

A class describing the current location of a CDockable. CLocations are combined, and a whole path of CLocations describes an actual location.
Some warnings:

• A CLocation is a very short living object: it does not have any ties to the actual layout of the application. Meaning that any change in the layout may invalidate a CLocation. For this reason clients are strongly encouraged not to store CLocations in any kind of collection for later use.
• There is no code available for storing CLocation persistently. This is deliberate, as CLocations are only good for a momentary snapshot of the location. The framework itself provides facilities to persistently store the location of a Dockable for a long time. You may have a look at CControl.writeXML(java.io.File) and CControl.setMissingStrategy(MissingCDockableStrategy).
• While CLocation and DockableProperty both store the location of CDockable or a Dockable, they are not exactly the same thing. A CLocation expresses the current location of a CDockable independent from the dockable itself. A DockableProperty however may also store information that is specific to a Dockable, namely the placeholder. This means that while every CLocation can be converted to a DockableProperty, not every DockableProperty can be converted to a CLocation without loosing some information.

Some examples showing how to create a path of locations:

        // an externalized element
        CLocation location = CLocation.external( 20, 20, 400, 300 );
 
        // a minimized element at the left side of the default panel
        CLocation location = CLocation.base().minimalWest();
  
        // an element in the lower right corner on a stack (tapped pane):
        CLocation location = CLocation.base().normalSouth( 0.5 ).east( 0.5 ).stack( 2 );
  
        // an element in the middle on a specific CContentArea
        CContentArea area = ...
        CLocation location = CLocation.base( area ).normalRectangle( 0.25, 0.25, 0.5, 0.5 );
 

Two CLocations are to be considered equal if findRoot(), findMode() and findProperty() return the same value.

Author:

Benjamin Sigg

Constructor Summary

CLocation()

Method Summary

abstract CLocation	aside() Returns a CLocation that describes the location of an element that should be inserted next to this location.
static CBaseLocation	base() Creates a new location that tells all children to use the default center.
static CBaseLocation	base(CContentArea center) Creates a new location that tells all children to use a station defined on center.
boolean	equals(Object obj)
CLocation	expandProperty(DockableProperty property, CLocationExpandStrategy strategy) Tries to create a location that resembles property.
CLocation	expandProperty(DockController controller, DockableProperty property) Tries to create a location that resembles property.
static CExternalizedLocation	external(int x, int y, int width, int height) Creates a new location representing the externalized mode.
abstract ExtendedMode	findMode() Gets the mode this location represents.
DockableProperty	findProperty() Gets a path describing this location in terms of the DockingFrames.
abstract DockableProperty	findProperty(DockableProperty successor) Gets a path describing this location in terms of the DockingFrames.
abstract String	findRoot() Gets the name of the station this location belongs to.
abstract CLocation	getParent() Gets the parent location of this location.
int	hashCode()
static CMaximizedLocation	maximized() Creates a location representing the maximized mode.
static CMaximizedLocation	maximized(CContentArea area) Creates a location representing the maximized mode on area.
static CMaximizedLocation	maximized(CGridArea area) Creates a location representing the maximized mode on area.
static CMaximalExternalizedLocation	maximized(int x, int y, int width, int height) Creates a location representing an element that is externalized and maximized.
static CMinimizeAreaLocation	minimized(CMinimizeArea area) Creates a new location representing a minimize area.
static CFlapIndexLocation	minimized(CMinimizeArea area, int index) Creates a new location representing a minimize area.
static CGridAreaLocation	normalized(CGridArea area) Creates a new location representing a grid area.
static CWorkingAreaLocation	working(CWorkingArea area) Creates a new location representing the given CWorkingArea.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CLocation

public CLocation()

Method Detail

base

public static CBaseLocation base(CContentArea center)

Creates a new location that tells all children to use a station defined on center.

Parameters:

center - the base of all new locations, can be null

Returns:

the representation of center

base

public static CBaseLocation base()

Creates a new location that tells all children to use the default center.

Returns:

the new base

working

public static CWorkingAreaLocation working(CWorkingArea area)

Creates a new location representing the given CWorkingArea.

Parameters:

area - an area

Returns:

the representation of area

minimized

public static CMinimizeAreaLocation minimized(CMinimizeArea area)

Creates a new location representing a minimize area.

Parameters:

area - the area to which the location refers

Returns:

the new location

minimized

public static CFlapIndexLocation minimized(CMinimizeArea area,
                                           int index)

Creates a new location representing a minimize area.

Parameters:

area - the area to which the location refers

index - the exact location on area

Returns:

the new location

normalized

public static CGridAreaLocation normalized(CGridArea area)

Creates a new location representing a grid area.

Parameters:

area - the area that is represented

Returns:

the new location

external

public static CExternalizedLocation external(int x,
                                             int y,
                                             int width,
                                             int height)

Creates a new location representing the externalized mode.

Parameters:

x - the x-coordinate in pixels

y - the y-coordinate in pixels

width - the width in pixels

height - the height in pixels

Returns:

the new location

maximized

public static CMaximizedLocation maximized()

Creates a location representing the maximized mode.

Returns:

the maximized mode

maximized

public static CMaximizedLocation maximized(CGridArea area)

Creates a location representing the maximized mode on area. It is the clients responsibility to ensure that area actually allows maximization.

Parameters:

area - the area on which an element will be maximized

Returns:

the new maximization location

maximized

public static CMaximizedLocation maximized(CContentArea area)

Creates a location representing the maximized mode on area. It is the clients responsibility to ensure that area actually allows maximization.

Parameters:

area - the area on which an element will be maximized

Returns:

the new maximization location

maximized

public static CMaximalExternalizedLocation maximized(int x,
                                                     int y,
                                                     int width,
                                                     int height)

Creates a location representing an element that is externalized and maximized. The coordinates are used once the CDockable is no longer maximized.

Parameters:

x - the x-coordinate in pixels

y - the y-coordinate in pixels

width - the width in pixels

height - the height in pixels

Returns:

the new location

getParent

public abstract CLocation getParent()

Gets the parent location of this location. Some root-locations may never have a parent.

Returns:

the parent location, can be null

findRoot

public abstract String findRoot()

Gets the name of the station this location belongs to. This can be the id of any CStation.

Returns:

the name of the station or null if this location does not have enough information to find the root

findMode

public abstract ExtendedMode findMode()

Gets the mode this location represents.

Returns:

the mode or null

findProperty

public DockableProperty findProperty()

Gets a path describing this location in terms of the DockingFrames. The method is ignoring any children of this location.

Returns:

the path to this location or null

findProperty

public abstract DockableProperty findProperty(DockableProperty successor)

Gets a path describing this location in terms of the DockingFrames.

Parameters:

successor - the path of the elements above this location or null

Returns:

the path to this location or null, can also be successor

expandProperty

public final CLocation expandProperty(DockController controller,
                                      DockableProperty property)

Tries to create a location that resembles property.

Parameters:

controller - the controller in whose realm this method is called, may be used to load extensions

property - some location

Returns:

a location whose findProperty() would create property again, or null in case that property can't be used

expandProperty

public CLocation expandProperty(DockableProperty property,
                                CLocationExpandStrategy strategy)

Tries to create a location that resembles property.

Parameters:

property - some location

strategy - a strategy helping to convert the properties

Returns:

a location whose findProperty() would create property again, or null in case that property can't be used

aside

public abstract CLocation aside()

Returns a CLocation that describes the location of an element that should be inserted next to this location.

Returns:

the new location

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object