bibliothek.gui.dock.common.grouping

Interface DockableGrouping

All Known Implementing Classes:

PlaceholderGrouping

public interface DockableGrouping

A DockableGrouping is an algorithm that rewrites the location of a Dockable, allowing clients to group several dockables together.
While the name of the interface implies that dockables should be grouped together, nothing prevents a client from writing an implementation that does the opposite, e.g. tries to distribute Dockables.
The two most common events that may be interesting for a DockableGrouping, when a the path of a dockable changes, and when a dockable gains focus, are automatically forwarded to this interface. Strategies that require more events, have to add the observers they need themselves to the right objects.

Author:

Benjamin Sigg

Method Summary

Modifier and Type	Method and Description
void	focusGained(Dockable dockable) Called after dockable has gained the focus.
ExtendedMode	getInitialMode(Dockable dockable) Tries to find out how to display dockable initially.
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.

Method Detail

getInitialMode

ExtendedMode getInitialMode(Dockable dockable)

Tries to find out how to display dockable initially.

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

getStoredLocation

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

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 getValidatedLocation(Dockable, CLocationMode, Location) will be called before dockable actually is moved to a new location.

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

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

Called right before dockable is moved to a new location.

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 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

hierarchyChanged

void hierarchyChanged(Dockable dockable)

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

Parameters:

dockable - a Dockable that has a new place

focusGained

void focusGained(Dockable dockable)

Called after dockable has gained the focus.

Parameters:

dockable - the element that just gained the focus