bibliothek.gui.dock.control.focus.FocusController 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) 2010 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.control.focus;

import java.awt.Component;

import bibliothek.gui.DockController;
import bibliothek.gui.Dockable;
import bibliothek.gui.dock.DockElementRepresentative;
import bibliothek.gui.dock.event.DockableFocusListener;
import bibliothek.gui.dock.event.FocusVetoListener;
import bibliothek.gui.dock.event.FocusVetoListener.FocusVeto;
import bibliothek.util.Todo;
import bibliothek.util.Todo.Compatibility;
import bibliothek.util.Todo.Version;


/**
 * The {@link FocusController} is responsible for transfering focus between {@link Dockable}s.
 * @author Benjamin Sigg
 */
public interface FocusController {
    /**
     * Gets the {@link DockController} whose {@link Dockable}s are tracked by this observer.
     * @return the controller
     */
    public DockController getController();
    
    /**
     * Adds a listener to this controller which can cancel a call to the {@link DockController}.
     * @param listener the new listener
     */
    public void addVetoListener( FocusVetoListener listener );
    
    /**
     * Removes a listener from this controller
     * @param listener the listener to remove
     */
    public void removeVetoListener( FocusVetoListener listener );
    
    /**
     * Adds a listener to this controller, the listener will be informed when
     * the focused {@link Dockable} changes.
     * @param listener the new listener
     */
    public void addDockableFocusListener( DockableFocusListener listener );

    /**
     * Removes a listener from this controller.
     * @param listener the listener to remove
     */
    public void removeDockableFocusListener( DockableFocusListener listener );
    
    /**
     * Temporarily disables this {@link FocusController}. Any call that would lead to a change
     * in the focus is silently ignored.
     */
    public void freezeFocus();
    
    /**
     * Re-enabls this {@link FocusController} after it was temporarily disabled.
     */
    public void meltFocus();
    
    /**
     * Sets the strategy which will be used to focus components.
     * @param strategy the new strategy, can be null
     */
    public void setStrategy( FocusStrategy strategy );
    
    /**
     * Gets the strategy that selects the {@link Component}s to focus.
     * @return the strategy, can be null
     */
    public FocusStrategy getStrategy();
    
    /**
     * Gets the {@link Dockable} which is currently focused.
     * @return the focused element or null
     */
    public Dockable getFocusedDockable();
    
    /**
     * Tells whether one of the methods which change the focus is currently
     * running, or not. If the result is true, noone should
     * change the focus.
     * @return true if the focus is currently changing
     */
    public boolean isOnFocusing();
    
    /**
     * Checks whether source can be used to select the next focused {@link Dockable}.
     * @param source the element which may be focused
     * @return whether the focus can be transfered, a value of null indicates that 
     * source does not represent a {@link Dockable}
     */
    public FocusVeto checkFocusedDockable( DockElementRepresentative source );
    
    /**
     * Ensures that a title or a {@link Component} of the currently
     * {@link #getFocusedDockable() focused Dockable} really
     * has the focus.
     * @param dockableOnly if true, then only the {@link Dockable} itself
     * should be focused
     */
    public void ensureFocusSet( boolean dockableOnly );
    
    /**
     * Sets the {@link Dockable} which should have the focus.
     * @param source the item to focus, may be null
     * @param component the {@link Component} which triggered this call for example because the user clicked with the mouse on it. 
     * This method can assume that the focus will automatically be transfered to component by the Swing framework itself.
     * Can be null, in which case this method decides on its own which {@link Component} to focus. This method may or may
     * not do sanity checks concerning component. An invalid argument will silently be ignored and treated 
     * as if it would be null.
     * @param force true if this controller must ensure
     * that all properties are correct, false if some
     * optimizations are allowed. Clients normally can set this argument
     * to false.
     * @param ensureFocusSet if true, then this method should make sure that either focusedDockable
     * itself or one of its {@link DockElementRepresentative} is the focus owner 
     * @param ensureDockableFocused  if true, then this method should make sure that focusedDockable
     * is the focus owner. This parameter is stronger that ensureFocusSet
     * @return whether focus could be transfered, a value of null indicates that {@link #isOnFocusing()} returned
     * true and the call was ignored
     * @deprecated this method will be replaced by {@link #focus(FocusRequest)}
     */
    @Deprecated
    @Todo( compatibility=Compatibility.BREAK_MAJOR, description="remove this method", priority=Todo.Priority.ENHANCEMENT,
		target=Version.VERSION_1_1_3)
    public FocusVeto setFocusedDockable( DockElementRepresentative source, Component component, boolean force, boolean ensureFocusSet, boolean ensureDockableFocused );
    
    /**
     * Sets the {@link Dockable} which should have the focus.
     * @param request information about the {@link Dockable} that should receive the focus, must not be null 
     */
    public void focus( FocusRequest request );
    
    /**
     * After the currently executed {@link FocusRequest} is completed, or if there is currently no {@link FocusRequest} running,
     * run is executed. If this controller is {@link #freezeFocus() frozen}, then run is executed
     * Immediately.
     * @param run some code to execute once a new {@link Dockable} has been focused
     * @see #focus(FocusRequest)
     */
    public void onFocusRequestCompletion( Runnable run );
}