keybindings.java

The ElectricTM VLSI Design System is an open-source Electronic Design Automation (EDA) system that c

/* -*- tab-width: 4 -*-
 *
 * Electric(tm) VLSI Design System
 *
 * File: KeyBindings.java
 * Written by: Jonathan Gainsley, Sun Microsystems.
 *
 * Copyright (c) 2003 Sun Microsystems and Static Free Software
 *
 * Electric(tm) is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * Electric(tm) 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Electric(tm); see the file COPYING.  If not, write to
 * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, Mass 02111-1307, USA.
 */
package com.sun.electric.tool.user.ui;

import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;

import javax.swing.KeyStroke;

/**
 * The KeyBindings object holds information about an action's key bindings.
 * There can be 0 or more default bindings which are set by the program.
 * There can be 0 or more user defined bindings which are stored as preferences by
 * the KeyBindingManager. Finally, there is a set of action listeners that get
 * activated when the action occurs.
 *
 * <p>The action can also be disabled/enabled.
 */
public class KeyBindings implements ActionListener {
    /** description of action */            private String actionDesc;
    /** list of KeyStrokePairs */           private List<KeyStrokePair> keyStrokePairs;
    /** default KeyStrokePairs */           private List<KeyStrokePair> defaultKeyStrokePairs;
    /** actions to perform */               private List<ActionListener> actionListeners;
    /** source to use when sending event to listeners */ private Object eventSource;
    /** true if KeyBindingManager using default keys */  private boolean usingDefaultKeys;
    /** if these bindings are enabled */    private boolean enabled;

    /** separator for keyBindingsToString */private static final String sep = "; ";

    /**
     * Constructs a new KeyBinding.
     * @param actionDesc description of the key binding to show to the user
     */
    public KeyBindings(String actionDesc) {
        this.actionDesc = actionDesc;
        keyStrokePairs = new ArrayList<KeyStrokePair>();
        defaultKeyStrokePairs = new ArrayList<KeyStrokePair>();
        actionListeners = new ArrayList<ActionListener>();
        eventSource = null;
        usingDefaultKeys = true;
        enabled = true;
    }

    // ------------------------ Add/Remove KeyBindings --------------------------

    /**
     * Add a one or two-stroke key binding.
     * @param prefixStroke optional prefix stroke. may be null
     * @param stroke required stroke
     */
    public void addKeyBinding(KeyStroke prefixStroke, KeyStroke stroke) {
        KeyStrokePair k = KeyStrokePair.getKeyStrokePair(prefixStroke, stroke);
        keyStrokePairs.add(k);
    }

    /**
     * Add a key stroke pair
     * @param k the key stroke pair
     */
    public void addKeyBinding(KeyStrokePair k) {
        keyStrokePairs.add(k);
    }

    /**
     * Add key bindings. The string can be a list of KeyStrokePairs.toString(),
     * delimited by <code>KeyBindings.sep</code>.
     * @param str string representing a list of key stroke pairs.
     */
    public void addKeyBindings(String str) {
        // split by separator
        String [] pairs = str.split(sep);
        for (int i = 0; i < pairs.length; i++) {
            String pair = pairs[i];
            KeyStrokePair k = KeyStrokePair.getKeyStrokePair(pair);
            if (k != null)
                keyStrokePairs.add(k);
        }
    }

    /**
     * Removes a key binding
     * @param k the key stroke pair to remove
     */
    public void removeKeyBinding(KeyStrokePair k) {
        keyStrokePairs.remove(k);
    }

    /**
     * Add a one or two-stroke key binding to the default bindings list
     * @param prefixStroke optional prefix stroke. may be null
     * @param stroke required stroke
     */
    public void addDefaultKeyBinding(KeyStroke prefixStroke, KeyStroke stroke) {
        KeyStrokePair k = KeyStrokePair.getKeyStrokePair(prefixStroke, stroke);
        defaultKeyStrokePairs.add(k);
    }

    /**
     * Add a key stroke pair to the default bindings list
     * @param k the key stroke pair
     */
    public void addDefaultKeyBinding(KeyStrokePair k) {
        defaultKeyStrokePairs.add(k);
    }

    /**
     * Clear all active bindings
     */
    public void clearKeyBindings() {
        keyStrokePairs.clear();
    }

    // ----------------------- Action Listener stuff -------------------------

    /**
     * Add an action listener.
     * @param a the action listener to add
     */
    public void addActionListener(ActionListener a) {
        actionListeners.add(a);
    }

    /** Remove an action listener */
    public void removeActionListener(ActionListener a) {
        actionListeners.remove(a);
    }

    /**
     * Perform all registered actions
     * @param e the ActionEvent
     */
    public void actionPerformed(ActionEvent e) {
        if (!enabled) return;
        if (eventSource != null)
            e.setSource(eventSource);               // fake the source of the event
        for (ActionListener action : actionListeners) {
            action.actionPerformed(e);
        }
    }

    // -------------------------------------------------------------------------

    /**
     * Convert key bindings to a string
     */
    public String bindingsToString() {
        StringBuffer buf = new StringBuffer("");
        for (Iterator<KeyStrokePair> it = keyStrokePairs.iterator(); it.hasNext(); ) {
            KeyStrokePair k = it.next();
            buf.append(k.toString());
            if (it.hasNext()) buf.append(sep);
        }
        return buf.toString();
    }

    public String describe() {
        return "KeyBindings for '"+actionDesc+"': [ "+bindingsToString()+" ]";
    }

    /** Get the action description that describes this key binding */
    public String getActionDesc() { return actionDesc; }

    /** Get an iterator over the actionListeners */
    public Iterator getActionListeners() { return actionListeners.iterator(); }

    /** Get an iterator over the user key stroke pairs */
    public Iterator<KeyStrokePair> getKeyStrokePairs() { return keyStrokePairs.iterator(); }

    /** Get an iterator over the default key stroke pairs */
    public Iterator<KeyStrokePair> getDefaultKeyStrokePairs() { return defaultKeyStrokePairs.iterator(); }

    /**
     * Set the object that will used as the "source" when the actions in
     * this KeyBindings object are activated.  This is useful for faking
     * the source of the event, in the case where the actionListeners may
     * be sensitive to that value. (Event.getSource() value).
     * @param source the object to be set as the source of the event passed
     * to the actionListeners on activation.
     */
    public void setEventSource(Object source) { eventSource = source; }

    /**
     * Set the value of usingDefaultKeys. This is a flag used by the
     * KeyBindingManager to keep track of which set of key bindings is
     * active for this KeyBindings object (i.e. the user-modified set
     * or the default set).
     * @param b true if using default keys, false otherwise
     */
    public void setUsingDefaultKeys(boolean b) { usingDefaultKeys = b; }

    public boolean getUsingDefaultKeys() { return usingDefaultKeys; }

    public void setEnabled(boolean b) { enabled = b; }

    public boolean getEnabled() { return enabled; }
}