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

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

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