bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/internal/keys/KeyBindingState.java

/*******************************************************************************
 * Copyright (c) 2000, 2007 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.ui.internal.keys;

import org.eclipse.jface.action.IContributionItem;
import org.eclipse.jface.action.IStatusLineManager;
import org.eclipse.jface.action.StatusLineContributionItem;
import org.eclipse.jface.bindings.keys.KeySequence;
import org.eclipse.ui.IWorkbench;
import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.internal.WorkbenchWindow;

/**
 * <p>
 * The mutable state of the key binding architecture. This is the only piece of
 * the key binding architecture that changes (internally). It keeps track of
 * what partial key strokes the user has entered. In the case of functional
 * groups of key bindings, it allows the user to keep part of the key sequence
 * even after a match has been made. Only after releasing all of the modifier
 * keys would the sequence reset itself.
 * </p>
 * <p>
 * In the current implementation, a partial reset results in only one key
 * stroke being left in the sequence. However, this may change in the future.
 * </p>
 * 
 * @since 3.0
 */
class KeyBindingState {

    /**
     * The workbench window associated with this state. The state can only
     * exist for one window. When the focus leaves this window then the mode
     * must automatically be reset.
     */
    private IWorkbenchWindow associatedWindow;

    /**
     * This is the current extent of the sequence entered by the user. In an
     * application with only single-stroke key bindings, this will also be
     * empty. However, in applications with multi-stroke key bindings, this is
     * the sequence entered by the user that partially matches another one of
     * the application's active key bindings.
     */
    private KeySequence currentSequence;

    /**
     * The workbench that should be notified of changes to the key binding
     * state. This is done by updating one of the contribution items on the
     * status line.
     */
    private final IWorkbench workbench;

    /**
     * Constructs a new instance of <code>KeyBindingState</code> with an
     * empty key sequence, set to reset fully.
     * 
     * @param workbenchToNotify
     *            The workbench that this state should keep advised of changes
     *            to the key binding state; must not be <code>null</code>.
     */
    KeyBindingState(IWorkbench workbenchToNotify) {
        currentSequence = KeySequence.getInstance();
        workbench = workbenchToNotify;
        associatedWindow = workbench.getActiveWorkbenchWindow();
    }

    /**
     * An accessor for the workbench window associated with this state. This
     * should never be <code>null</code>, as the setting follows the last
     * workbench window to have focus.
     * 
     * @return The workbench window to which the key binding architecture is
     *         currently attached; should never be <code>null</code>.
     */
    IWorkbenchWindow getAssociatedWindow() {
        return associatedWindow;
    }

    /**
     * An accessor for the current key sequence waiting for completion.
     * 
     * @return The current incomplete key sequence; never <code>null</code>,
     *         but may be empty.
     */
    KeySequence getCurrentSequence() {
        return currentSequence;
    }

    /**
     * Gets the status line contribution item which the key binding
     * architecture uses to keep the user up-to-date as to the current state.
     * 
     * @return The status line contribution item, if any; <code>null</code>,
     *         if none.
     */
    StatusLineContributionItem getStatusLine() {
        if (associatedWindow instanceof WorkbenchWindow) {
            WorkbenchWindow window = (WorkbenchWindow) associatedWindow;
            IStatusLineManager statusLine = window.getStatusLineManager();
            // TODO implicit dependency on IDE's action builder
            // @issue implicit dependency on IDE's action builder
            if (statusLine != null) { // this can be null if we're exiting
                IContributionItem item = statusLine
                        .find("ModeContributionItem"); //$NON-NLS-1$
                if (item instanceof StatusLineContributionItem) {
                    return ((StatusLineContributionItem) item);
                }
            }
        }

        return null;
    }

    /**
     * <p>
     * Resets the state based on the current properties. If the state is to
     * collapse fully or if there are no key strokes, then it sets the state to
     * have an empty key sequence. Otherwise, it leaves the first key stroke in
     * the sequence.
     * </p>
     * <p>
     * The workbench's status lines are updated, if appropriate.
     * </p>
     */
    void reset() {
        currentSequence = KeySequence.getInstance();
        updateStatusLines();
    }

    /**
     * A mutator for the workbench window to which this state is associated.
     * 
     * @param window
     *            The workbench window to associated; should never be <code>null</code>.
     */
    void setAssociatedWindow(IWorkbenchWindow window) {
        associatedWindow = window;
    }

    /**
     * A mutator for the partial sequence entered by the user.
     * 
     * @param sequence
     *            The current key sequence; should not be <code>null</code>,
     *            but may be empty.
     */
    void setCurrentSequence(KeySequence sequence) {
        currentSequence = sequence;
        updateStatusLines();
    }

    /**
     * Updates the text of the status line of the associated shell with the
     * current sequence.
     */
    private void updateStatusLines() {
        StatusLineContributionItem statusLine = getStatusLine();
        if (statusLine != null) {
            statusLine.setText(getCurrentSequence().format());
        }
    }
}