bibliothek.gui.dock.station.split.SplitDockAccess Maven / Gradle / Ivy

Go to download
/*
 * 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) 2007 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.station.split;

import bibliothek.gui.Dockable;
import bibliothek.gui.dock.DockHierarchyLock;
import bibliothek.gui.dock.SplitDockStation;
import bibliothek.gui.dock.DockHierarchyLock.Token;
import bibliothek.gui.dock.event.DockStationListener;
import bibliothek.gui.dock.station.DockableDisplayer;
import bibliothek.gui.dock.station.StationChildHandle;
import bibliothek.gui.dock.station.StationDropItem;
import bibliothek.gui.dock.station.span.Span;
import bibliothek.gui.dock.station.span.SpanFactory;
import bibliothek.gui.dock.title.DockTitleVersion;

/**
 * Provides access to some internal methods and attributes of a {@link SplitDockStation}. An access
 * is granted only to a few selected friend classes.
 * @author Benjamin Sigg
 */
public interface SplitDockAccess {
	/**
	 * Gets the station to which this object grants access.
	 * @return the owner
	 */
    public SplitDockStation getOwner();
        
    /**
     * Gets the kind of title {@link #getOwner() owner} uses.
     * @return the kind of title, can be null
     */
    public DockTitleVersion getTitleVersion();
    
    /**
     * Gets the {@link DockableDisplayer} which is currently in fullscreen-mode.
     * @return the displayer, may be null
     */
    public StationChildHandle getFullScreenDockable();
    
    /**
     * Tests whether the given value of the divider is a legal value or not.
     * @param divider The value of the divider
     * @param node the node for which the divider is validated
     * @return a legal value, as near as possible to divider.
     */
    public double validateDivider( double divider, Node node );
    
    /**
     * Creates a new handle but does not take any other action.
     * @param dockable the target for the new handle
     * @return the new handle
     */
    public StationChildHandle newHandle( Dockable dockable );
    
    /**
     * Adds the new handle to the station and adds
     * the displayer to the station. Binds the dockable.
     * @param handle the new handle
     * @param token if null, then a token will be acquired by this method
     * and this method will fire events, otherwise this methods is executed silently
     */
    public void addHandle( StationChildHandle handle, DockHierarchyLock.Token token );
    
    /**
     * Removes an element from the station.
     * @param handle the element to remove
     * @param token if null, then a token will be acquired by this method
     * and this method will fire events, otherwise this methods is executed silently
     */
    public void removeHandle( StationChildHandle handle, DockHierarchyLock.Token token );
    
    /**
     * Tries to add Dockable such that the boundaries given
     * by property are full filled.
     * @param dockable a new child of this station
     * @param property the preferred location of the child
     * @param root the root of all possible parents where the child could be inserted
     * @return true if the child could be added, false
     * if no location could be found
     */
    public boolean drop( Dockable dockable, final SplitDockProperty property, SplitNode root );
    
    /**
     * Invoked whenever a node changes its shape. Leads to a call to {@link DockStationListener#dockablesRepositioned(bibliothek.gui.DockStation, Dockable[])}
     * for all {@link Dockable}s that are in node or children of node.
     * @param node the source of the event
     */
    public void repositioned( SplitNode node );
    
    /**
     * Checks whether info is valid or not.
     * @param info the preferred drop location
     * @return info if it is valid, null otherwise
     */
    public PutInfo validatePutInfo( PutInfo info );
    
    /**
     * Creates a unique id for a {@link SplitNode}.
     * @return the new unique id
     */
    public long uniqueID();
    
    /**
     * Tells whether nodes can currently be automatically removed from the tree.
     * @return true if auto-removal is enabled
     */
	public boolean isTreeAutoCleanupEnabled();
	
	/**
	 * Gets the set which keeps track of all placeholders and makes sure that
	 * no placeholder is used twice.
	 * @return the placeholder set
	 */
	public SplitPlaceholderSet getPlaceholderSet();
	
	/**
	 * Gets the object that manages all {@link Span}s.
	 * @return access to the current {@link SpanFactory}
	 */
	public SplitSpanStrategy getSpanStrategy();
	
	/**
	 * Creates a new {@link Leaf}.
	 * @param id the unique identifier of the leaf
	 * @return the new leaf
	 */
	public Leaf createLeaf( long id );
	
	/**
	 * Creates a new {@link Node}.
	 * @param id the unique identifier of the node
	 * @return the new node
	 */
	public Node createNode( long id );
	
	/**
	 * Creates a new {@link Placeholder}.
	 * @param id the unique identifier of this placeholder
	 * @return the new placeholder
	 */
	public Placeholder createPlaceholder( long id );
	
	/**
	 * Sets the current information telling where and how an item is to be dropped.
	 * @param putInfo the current drop information
	 */
	public void setDropInfo( PutInfo putInfo );

	/**
	 * Resets the information telling where and how an item is to be dropped.
	 */
	public void unsetDropInfo();
	
	/**
	 * Moves the dockable described by putInfo at a new location
	 * @param putInfo description of the new location
	 * @param item more information about the drag and drop operation that is currently happening
	 */
	public void move( PutInfo putInfo, StationDropItem item );
	
	/**
	 * Adds the {@link Dockable} given by putInfo to this station.
     * @param token if null, then a token will be acquired by this method
     * and this method will fire events, otherwise this methods is executed silently
     * @param putInfo information about where to drop the new {@link Dockable}
     * @param item detailed information about the drag and drop operation that is going on
	 */
	public void drop( Token token, PutInfo putInfo, StationDropItem item );
}