bibliothek.gui.dock.common.grouping
Class PlaceholderGrouping

java.lang.Object
  bibliothek.gui.dock.common.grouping.PlaceholderGrouping

All Implemented Interfaces:

DockableGrouping

@ClientOnly
public class PlaceholderGrouping
extends Object
implements DockableGrouping

When a Dockable is about to be moved to a new position, then this DockableGrouping searches for a unique identifier, called a "placeholder", which indicates where the Dockable should be placed.
The placeholder is placed at the location of the Dockable, for which hierarchyChanged(Dockable) was called last. Basically the placeholder always follows the last Dockable that was moved around.
This object tries to ensure that for each ExtendedMode there is no more than one placeholder set. Meaning there is only one location marked for each mode.
Clients may use the CControlPerspective, and methods like CGridPerspective.gridPlaceholder, to set the initial location of the placeholder.

Author:

Benjamin Sigg

Constructor Summary

PlaceholderGrouping(CControl control, Path placeholder)
Creates a new grouping.

Method Summary

protected Location	findLocationFor(Dockable dockable, CLocationMode mode) Searches a location for dockable.
protected Location	findLocationFor(Dockable dockable, CLocationMode mode, Location validatedHistory) Called by getValidatedLocation(Dockable, CLocationMode, Location), this method tries to find a location on the root station designated by validatedHistory.
void	focusGained(Dockable dockable) Called after dockable has gained the focus.
ExtendedMode	getInitialMode(Dockable dockable) Tries to find out how to display dockable initially.
protected Path	getLastPlaceholder() Placeholder that marks the last position where this PlaceholderGrouping did store something.
protected DockableProperty	getLocation(DockStation root) Searches the ideal location on root that matches the placeholder.
Path	getPlaceholder() Gets the placeholder that is searched by this PlaceholderGrouping, and that is placed wherever a Dockable is moved when hierarchyChanged(Dockable) was called.
Location	getStoredLocation(Dockable dockable, CLocationMode mode, Location history) Called right after an old location of dockable for mode was read.
Location	getValidatedLocation(Dockable dockable, CLocationMode mode, Location validatedHistory) Called right before dockable is moved to a new location.
void	hierarchyChanged(Dockable dockable) Always called after dockable has changed its location.
protected void	markLocation(Dockable dockable) Makes sure that the placeholder marks the current location of dockable.
void	removePlaceholderEverywhere() Removes the last placeholder everywhere.

Methods inherited from class java.lang.Object

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

Constructor Detail

PlaceholderGrouping

public PlaceholderGrouping(CControl control,
                           Path placeholder)

Creates a new grouping.

Parameters:

control - The realm in which this object acts, used to access things like the root DockStations

placeholder - a unique identifier with which the location of a group of Dockables is marked

Method Detail

getPlaceholder

public Path getPlaceholder()

Gets the placeholder that is searched by this PlaceholderGrouping, and that is placed wherever a Dockable is moved when hierarchyChanged(Dockable) was called.

Returns:

the placeholder, not null

getLastPlaceholder

protected Path getLastPlaceholder()

Placeholder that marks the last position where this PlaceholderGrouping did store something. The default implementation always returns placeholder + "last", but subclasses may change the behavior.

Returns:

the last location where something interesting happened

getStoredLocation

public Location getStoredLocation(Dockable dockable,
                                  CLocationMode mode,
                                  Location history)

Description copied from interface: DockableGrouping

Called right after an old location of dockable for mode was read. The method may change the location of dockable by returning a new Location object.
If this method is called, then DockableGrouping.getValidatedLocation(Dockable, CLocationMode, Location) will be called before dockable actually is moved to a new location.

Specified by:

getStoredLocation in interface DockableGrouping

Parameters:

dockable - the dockable whose location is about to be changed

mode - the target mode for dockable

history - the old location of dockable, may be null

Returns:

either history, or a newly created location. Also null is valid result. This method is allowed to return an invalid location, invalid locations however will be replaced with valid location.

getValidatedLocation

public Location getValidatedLocation(Dockable dockable,
                                     CLocationMode mode,
                                     Location validatedHistory)

Description copied from interface: DockableGrouping

Called right before dockable is moved to a new location.

Specified by:

getValidatedLocation in interface DockableGrouping

Parameters:

dockable - the Dockable whose location is about to be changed

mode - the target mode for dockable

validatedHistory - a validated location. This may be the result of DockableGrouping.getStoredLocation(Dockable, CLocationMode, Location) if that result already was a valid location, or it may be a new location, may be null

Returns:

either validatedHistory, or a newly created location. Also null is a valid result. This method should return only valid locations, invalid locations will lead the framework to place the dockable at some default location

getInitialMode

public ExtendedMode getInitialMode(Dockable dockable)

Description copied from interface: DockableGrouping

Tries to find out how to display dockable initially.

Specified by:

getInitialMode in interface DockableGrouping

Parameters:

dockable - an invisible dockable that is about to be made visible, and that does not have a location defined.

Returns:

the initial mode of dockable, or null

findLocationFor

protected Location findLocationFor(Dockable dockable,
                                   CLocationMode mode)

Searches a location for dockable.

Parameters:

dockable - the element whose new location is searched

mode - the target mode of dockable

Returns:

the new location, or null if no location can be calculated

findLocationFor

protected Location findLocationFor(Dockable dockable,
                                   CLocationMode mode,
                                   Location validatedHistory)

Called by getValidatedLocation(Dockable, CLocationMode, Location), this method tries to find a location on the root station designated by validatedHistory.

Parameters:

dockable - the element whose new location is searched

mode - the target mode of dockable

validatedHistory - the location where the unmodified algorithm would place dockable

Returns:

either a replacement for validatedHistory, or validatedHistory. Should not return null.

getLocation

protected DockableProperty getLocation(DockStation root)

Searches the ideal location on root that matches the placeholder.

Parameters:

root - the station on which to search the placeholder

Returns:

the location of the placeholder, or null if the placeholder was not found

hierarchyChanged

public void hierarchyChanged(Dockable dockable)

Description copied from interface: DockableGrouping

Always called after dockable has changed its location. This method will be called for any Dockable that changed its location, even if DockableGrouping.getStoredLocation(Dockable, CLocationMode, Location) or DockableGrouping.getValidatedLocation(Dockable, CLocationMode, Location) was never called.
Note: this method acts as if a DockHierarchyListener would have been added to dockable

Specified by:

hierarchyChanged in interface DockableGrouping

Parameters:

dockable - a Dockable that has a new place

focusGained

public void focusGained(Dockable dockable)

Description copied from interface: DockableGrouping

Called after dockable has gained the focus.

Specified by:

focusGained in interface DockableGrouping

Parameters:

dockable - the element that just gained the focus

markLocation

protected void markLocation(Dockable dockable)

Makes sure that the placeholder marks the current location of dockable.

Parameters:

dockable - defines the location to mark

removePlaceholderEverywhere

public void removePlaceholderEverywhere()

Removes the last placeholder everywhere.