bibliothek.gui.dock.layout.location.AsideRequest Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of docking-frames-core Show documentation
A window docking framework for Swing
The 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) 2012 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.layout.location;

import bibliothek.gui.DockStation;
import bibliothek.gui.dock.layout.DockableProperty;
import bibliothek.gui.dock.station.Combiner;
import bibliothek.gui.dock.station.support.PlaceholderMap;
import bibliothek.gui.dock.util.DockProperties;
import bibliothek.gui.dock.util.PropertyKey;
import bibliothek.gui.dock.util.property.DynamicPropertyFactory;
import bibliothek.util.Path;

/**
 * An {@link AsideRequest} represents the action of generating a {@link DockableProperty} that is
 * "aside" another property, this includes modifying {@link DockStation}s and layouts to store
 * a placeholder for the new property.

 * One {@link AsideRequest} is always tied to exactly one {@link DockStation} or {@link Combiner},
 * forwarding a request to another {@link DockStation} will produce very strange results.
 * @author Benjamin Sigg
 */
public interface AsideRequest {
	/**
	 * Property key for getting the default {@link AsideRequestFactory}.
	 */
	public static final PropertyKey REQUEST_FACTORY = new PropertyKey( "dock.AsideRequestFactory",
			new DynamicPropertyFactory(){
				public AsideRequestFactory getDefault( PropertyKey key, DockProperties properties ){
					return new DefaultAsideRequestFactory( properties );
				}
			}, true );
	
	/**
	 * Executes this request calling the aside method of station.
	 * @param station the station whose {@link DockStation#aside(AsideRequest) aside} method is to be called
	 * @return a new location
	 * @throws IllegalStateException if this request is already executed
	 */
	public AsideAnswer execute( DockStation station );
	
	/**
	 * Gets the old location, the location whose neighbor is searched. The property
	 * may have a {@link DockableProperty#getSuccessor() successor}.
	 * @return the old location, can be null
	 */
	public DockableProperty getLocation();

	/**
	 * The placeholder that should be used for the new location. 
	 * @return the placeholder, may be null
	 */
	public Path getPlaceholder();

	/**
	 * Gets the layout of the current non-existent station. The layout is only set in
	 * situations where no {@link DockStation} is available, and it is only set if it
	 * is known.
	 * @return the layout as it was created by {@link DockStation#getPlaceholders()}, null
	 * if not known or not necessary
	 */
	public PlaceholderMap getLayout();
	
	/**
	 * Gets the {@link DockStation} that is the parent of the current {@link DockStation} or {@link Combiner}.
	 * @return the parent station, may be null either for a root station or if the recursion of
	 * {@link Combiner}s is too high
	 */
	public DockStation getParentStation();

	/**
	 * Shortcut for calling {@link #answer(DockableProperty)} with a value of null.
	 */
	public void answer();

	/**
	 * Sets the result of this request, location will be merged with other
	 * results from the parent and children stations using the 
	 * {@link DockableProperty#setSuccessor(DockableProperty) successor} property. If location
	 * already has a successor, then the successor of the last {@link DockableProperty} in the chain
	 * may be modified by this method.

	 * By not calling this method at all, clients can tell the action that no "neighbor" location was found, in
	 * this case the request will be cancled. Note how "not calling" and "calling with null" are
	 * two different things.
	 * @param location the location describing the "neighbor" of {@link DockableProperty}, a value
	 * of null indicates that the parent and child request should be merged directly 
	 */
	public void answer( DockableProperty location );

	/**
	 * Tells this request how the layout of a non-existent station looks after the request has been handled.
	 * Calling this method with a value of null indicates that there will be no layout after the
	 * request finished. Not calling the method at all indicates that the current layout is not affected.

	 * Note that calling this method does not change the result of {@link #getLayout()}.
	 * @param station the new layout, can be null
	 */
	public void answer( PlaceholderMap station );
	
	/**
	 * Sets the result of this request, and tells how the layout of a non-existent stations looks after the request
	 * has been handled. The arguments can be null, as described in {@link #answer(DockableProperty)}
	 * and {@link #answer(PlaceholderMap)}.
	 * @param location the location describing the "neighbor" of {@link DockableProperty}, a value
	 * of null indicates that the parent and child request should be merged directly
	 * @param station the new layout, can be null
	 */
	public void answer( DockableProperty location, PlaceholderMap station );

	/**
	 * Calls the {@link DockStation#aside(AsideRequest)} method of station with the 
	 * {@link DockableProperty#getSuccessor() successor} of the {@link #getLocation() current location}.
	 * The aside method is called in any case, even if the current location is null
	 * or has no successor.
	 * @param station the station on which to continue the request
	 * @return how station reacted to the request
	 */
	public AsideAnswer forward( DockStation station );

	/**
	 * Calls the {@link Combiner#aside(AsideRequest)} method of combiner with the
	 * {@link DockableProperty#getSuccessor() successor} of the {@link #getLocation() current location}.
	 * The aside method is called in any case, even if the current location is null
	 * or has no successor.
	 * @param combiner the non-existent station on which to continue the request
	 * @return how combiner reacted to the request
	 */
	public AsideAnswer forward( Combiner combiner );

	/**
	 * Calls the {@link Combiner#aside(AsideRequest)} method of combiner with the
	 * {@link DockableProperty#getSuccessor() successor} of the {@link #getLocation() current location}.
	 * The aside method is called in any case, even if the current location is null
	 * or has no successor.
	 * @param combiner the non-existent station on which to continue the request
	 * @param layout the layout of the non-existent station, as was created by {@link DockStation#getPlaceholders()}.
	 * Can be null in which case this method behaves like {@link #forward(Combiner)}
	 * @return how combiner reacted to the request
	 */
	public AsideAnswer forward( Combiner combiner, PlaceholderMap layout );
}