bibliothek.gui.dock.common.grouping
Class PlaceholderGrouping

java.lang.Object
  extended by 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.