bibliothek.gui.dock.station.DockableDisplayer 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) 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;

import java.awt.Component;
import java.awt.Insets;
import java.awt.Point;

import bibliothek.gui.DockController;
import bibliothek.gui.DockStation;
import bibliothek.gui.Dockable;
import bibliothek.gui.dock.DockElementRepresentative;
import bibliothek.gui.dock.component.DockComponentRoot;
import bibliothek.gui.dock.displayer.DisplayerCombinerTarget;
import bibliothek.gui.dock.station.support.CombinerSource;
import bibliothek.gui.dock.station.support.Enforcement;
import bibliothek.gui.dock.title.DockTitle;

/**
 * A panel which shows one {@link Dockable} and one {@link DockTitle}. The location
 * of the {@link DockTitle} is at one of the four borders (left,
 * right, top, bottom). The title may be null, in this case only
 * the Dockable is shown.

 * Clients using a displayer should try to set the {@link #setController(DockController) controller}
 * and the {@link #setStation(DockStation) station} property.
 * @see DisplayerCollection
 * @see DisplayerFactory
 * @author Benjamin Sigg
 */
public interface DockableDisplayer extends DockComponentRoot{
    /** The four possible locations of the title */
    public static enum Location{
        /** the left side */
        LEFT, 
        /** the right side */
        RIGHT, 
        /** the top side */
        TOP,
        /** the bottom side */
        BOTTOM };
    
        
    /**
     * Sets the controller for which this displayer is used. That property
     * must be set by the client. Note that there is no guarantee, that a
     * client sets this property.
     * @param controller the controller, can be null
     */
    public void setController( DockController controller );
    
    /**
     * Gets the controller for which this displayer is used. Note that
     * there is no guarantee, that this property is set.
     * @return the controller or null
     */
    public DockController getController();
    
    /**
     * Adds listener to this displayer.
     * @param listener the new listener, not null
     */
    public void addDockableDisplayerListener( DockableDisplayerListener listener );
    
    /**
     * Removes listener from this displayer.
     * @param listener the listener to remove
     */
    public void removeDockableDisplayerListener( DockableDisplayerListener listener );
    
    /**
     * Sets the station on which this displayer is shown. That property
     * must be set by the station itself. Note that there is no guarantee,
     * that a station sets this property.
     * @param station the station or null
     */
    public void setStation( DockStation station );
    
    /**
     * Gets the station on which this displayer might be shown. Note that
     * there is no guarantee, that a parent-station sets this property.
     * @return the station or null
     */
    public DockStation getStation();
    
    /**
     * Gets the Dockable which is shown on this displayer.
     * @return the child, can be null
     */
    public Dockable getDockable();

    /**
     * Sets the Dockable which should be shown on this displayer. A value
     * of null means that no Dockable should be visible at all.
     * @param dockable the child, can be null
     */
    public void setDockable( Dockable dockable );

    /**
     * Gets the location of the title in respect to the Dockable.
     * @return the location
     */
    public Location getTitleLocation();

    /**
     * Sets the location of the title in respect to the Dockable.
     * @param location the location, a value of null is transformed
     * into the default-value
     */
    public void setTitleLocation( Location location );
    
    /**
     * Gets a {@link DockElementRepresentative representation} of the {@link Dockable} that can
     * be used for grabbing and moving around the displayer. The result of this method should be
     * the first match of this list:
     * 
     * 	A {@link DockTitle}
     *  Any kind of {@link DockElementRepresentative}
     *  The {@link Dockable} itself
     *   null 
     * 
     * Changes of the result of this method should be communicated through the 
     * {@link DockableDisplayerListener}s.
     * @return an element for moving around this displayer, can be null
     */
    public DockElementRepresentative getMoveableElement();
    
    /**
     * Gets the title which is shown on this displayer.
     * @return the title, can be null
     */
    public DockTitle getTitle();

    /**
     * Gets the center point of the {@link #getTitle() title} or any {@link Component} that
     * behaves as if it would be the title. Some {@link DockStation}s may use this information
     * to make sure, that the user can always grab and move around the {@link Dockable}.
     * @return the center point, may be null
     */
    public Point getTitleCenter();
    
    /**
     * Sets the title of this displayer. If the title is set to null,
     * no title is visible. The displayer will change the 
     * {@link DockTitle#setOrientation(bibliothek.gui.dock.title.DockTitle.Orientation) orientation}
     * of the title.
     * @param title the title or null
     */
    public void setTitle( DockTitle title );
    
    /**
     * Tells whether the point x/y is inside the title of this 
     * displayer or not.
     * @param x the x-coordinate, relatively to this component
     * @param y the y-coordinate, relatively to this component
     * @return true if the title contains the point
     */
    public boolean titleContains( int x, int y );
    
    /**
     * Gets an estimate of the insets around the {@link Dockable} of this 
     * displayer compared to the whole size of this displayer.
     * @return the estimate of the insets
     */
    public Insets getDockableInsets();
    
    /**
     * Gets the Component which represents this displayer.
     * @return the component
     */
    public Component getComponent();
    
    /**
     * This method tells how this displayer would like to combine itself with a {@link Dockable} that is dropped
     * over it. This method is usually called by a {@link Combiner} or by a {@link DockStation}, but other modules
     * may call this method as well.
     * @param source information about the dockable that is dropped, the location of the mouse, etc...
     * @param force tells how much the caller would like the result not to be null, if the
     * {@link Enforcement#getForce() force} property is high, then the result should more likely not be null.
     * Note that a result of null is always a valid result, even if the caller does not like it. 
     * @return the operation that could be performed or null if this displayer does not
     * have any specific information
     */
    public DisplayerCombinerTarget prepareCombination( CombinerSource source, Enforcement force );
}