bibliothek.gui.dock.action.DockAction 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
${project.name} is base or core library
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.action;

import bibliothek.gui.Dockable;
import bibliothek.gui.dock.action.view.ActionViewConverter;
import bibliothek.gui.dock.action.view.ViewTarget;
import bibliothek.gui.dock.title.DockTitle;
import bibliothek.gui.dock.util.PropertyKey;
import bibliothek.gui.dock.util.property.ConstantPropertyFactory;

/**
 * A DockAction is an object that represents an action which can be triggered by the user. Every
 * DockAction has a graphical representation which is shown at many places, for example
 * on a {@link DockTitle} or in a popupmenu.

 * A DockAction may choose its own graphical representation, or use the 
 * {@link ActionViewConverter} to get the default-representations.

 * Every DockAction is associated with some Dockables. The {@link #bind(Dockable)}-method will be invoked
 * before a representation is shown, and the {@link #unbind(Dockable)} when a representation is no
 * longer shown.
 * 
 * @author Benjamin Sigg
 */
public interface DockAction {
	/**
	 * The {@link ButtonContentFilter} decides whether text is shown on buttons that represent {@link DockAction}s.
	 */
	public static final PropertyKey BUTTON_CONTENT_FILTER = new PropertyKey( "dock.buttonContentFilter", new ConstantPropertyFactory( ButtonContentFilter.NEVER ), true );
	
    /**
     * Creates a view for this action, for the platform target and
     * with help of converter. Clients might use their own
     * code to create a new view, but the preferred way is to call
     * {@link ActionViewConverter#createView(ActionType, DockAction, ViewTarget, Dockable)}
     * with an {@link ActionType} that fits to this DockAction.
     * @param  the type of view requested
     * @param target The platform on which the view will be used
     * @param converter A set of methods that can be used to create a view
     * @param dockable The Dockable for which the view will be shown. Note that
     * this action may not yet be {@link #bind(Dockable) bound} to this action.
     * @return a new view
     */
    public  V createView( ViewTarget target, ActionViewConverter converter, Dockable dockable );
    
    /**
     * Informs this DockAction that icons, text, and other stuff like that,
     * will be requested from this DockAction. This method should be called
     * from the object that will display the view of this action.
     * @param dockable the {@link Dockable} that may be used in the future
     * @see #unbind(Dockable)
     */
    public void bind( Dockable dockable );

    /**
     * Invoked only if the dockable was {@link #bind(Dockable) bound}
     * to this DockAction, and if the dockable will no longer be
     * used for any method calls (except {@link #bind(Dockable) bind}) on 
     * this DockAction.
     * @param dockable The {@link Dockable} that will never be seen again, except
     * it is maybe {@link #bind(Dockable) bind} again.
     */
    public void unbind( Dockable dockable );
    
    /**
     * Does the appropriate action that can be done respecting the current
     * state of this action.
     * @param dockable the element for which this action is called
     * @return true if this action could do anything, false
     * if this action was not able to react in any way to the event.
     */
    public boolean trigger( Dockable dockable );
}