bibliothek.gui.dock.common.grouping.DockableGrouping Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of docking-frames-common Show documentation
DockingFrames is an open source Java Swing docking framework, licenced under LGPL 2.1. This is the same distribution as the original distribution (http://www.docking-frames.org/), only reinstalled in maven
There is a newer version: 1.1.2p20b.fix-1
Show newest version
/*
 * Bibliothek - DockingFrames
 * Library built on Java/Swing, allows the user to "drag and drop"
 * panels containing any Swing-Component the developer likes to add.
 * 
 * Copyright (C) 2015 Benjamin Sigg
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 * Benjamin Sigg
 * [email protected]
 * CH - Switzerland
 */
package bibliothek.gui.dock.common.grouping;

import bibliothek.gui.Dockable;
import bibliothek.gui.dock.common.mode.CLocationMode;
import bibliothek.gui.dock.common.mode.ExtendedMode;
import bibliothek.gui.dock.event.DockHierarchyListener;
import bibliothek.gui.dock.facile.mode.Location;

/**
 * A {@link DockableGrouping} is an algorithm that rewrites the location of a {@link 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
 * {@link Dockable}s.

 * The two most common events that may be interesting for a {@link DockableGrouping}, when a 
 * {@link #hierarchyChanged(Dockable) the path of a dockable changes}, and
 * {@link #focusGained(Dockable) 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
 */
public interface DockableGrouping {
	/**
	 * Tries to find out how to display dockable initially.
	 * @param dockable an invisible dockable that is about to be made visible, and that does not have a location defined.
	 * @return the initial mode of dockable, or null
	 */
	public ExtendedMode getInitialMode( Dockable dockable );
	
	/**
	 * Called right after an old location of dockable for mode was read. The method
	 * may change the location of dockable by returning a new {@link Location} object.

	 * If this method is called, then {@link #getValidatedLocation(Dockable, CLocationMode, Location)} will be called
	 * before dockable actually is moved to a new location.
	 * @param dockable the dockable whose location is about to be changed
	 * @param mode the target mode for dockable
	 * @param history the old location of dockable, may be null
	 * @return 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.
	 */
	public Location getStoredLocation( Dockable dockable, CLocationMode mode, Location history );
	
	/**
	 * Called right before dockable is moved to a new location. 
	 * @param dockable the {@link Dockable} whose location is about to be changed
	 * @param mode the target mode for dockable
	 * @param validatedHistory a validated location. This may be the result of {@link #getStoredLocation(Dockable, CLocationMode, Location)} 
	 * if that result already was a valid location, or it may be a new location, may be null
	 * @return 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
	 */
	public Location getValidatedLocation( Dockable dockable, CLocationMode mode, Location validatedHistory );
	
	/**
	 * Always called after dockable has changed its location. This method will be called for any {@link Dockable} that
	 * changed its location, even if {@link #getStoredLocation(Dockable, CLocationMode, Location)} or {@link #getValidatedLocation(Dockable, CLocationMode, Location)} 
	 * was never called.

	 * Note: this method acts as if a {@link DockHierarchyListener} would have been added to dockable
	 * @param dockable a {@link Dockable} that has a new place
	 */
	public void hierarchyChanged( Dockable dockable );

	/**
	 * Called after dockable has gained the focus.
	 * @param dockable the element that just gained the focus
	 */
	public void focusGained( Dockable dockable );
}