/*
 * @(#)KeyActionAdapter.java    2.3.3   3 January 2005
 *
 * Copyright 2005
 * College of Computer and Information Science
 * Northeastern University
 * Boston, MA  02115
 *
 * The Java Power Tools software may be used for educational
 * purposes as long as this copyright notice is retained intact
 * at the top of all source files.
 *
 * To discuss possible commercial use of this software, 
 * contact Richard Rasala at Northeastern University, 
 * College of Computer and Information Science,
 * 617-373-2462 or rasala@ccs.neu.edu.
 *
 * The Java Power Tools software has been designed and built
 * in collaboration with Viera Proulx and Jeff Raab.
 *
 * Should this software be modified, the words "Modified from 
 * Original" must be included as a comment below this notice.
 *
 * All publication rights are retained.  This software or its 
 * documentation may not be published in any media either
 * in whole or in part without explicit permission.
 *
 * This software was created with support from Northeastern 
 * University and from NSF grant DUE-9950829.
 */

package edu.neu.ccs.gui;

import java.awt.*;
import java.awt.event.*;
import java.io.Serializable;
import java.util.*;
import javax.swing.*;

/**
 * <P>An adapter class for receiving key events, 
 * and performing action listeners in response to those events.</P>
 * 
 * @author  Jeff Raab
 * @author  Richard Rasala
 * @version 2.3.3
 * @since   1.0
 */
public class KeyActionAdapter 
    implements KeyListener, Cloneable, Serializable
{
    /** 
     * List of action listeners to be performed upon the
     * notification of key pressed events. 
     */
    protected ActionSequence pressedActions = new ActionSequence();
    
    /**
     * List of action listeners to be performed upon the
     * notification of key released events.
     */
    protected ActionSequence releasedActions = new ActionSequence();
    
    /**
     * List of action listeners to be performed upon the
     * notification of key typed events.
     */
    protected ActionSequence typedActions = new ActionSequence();
    
    
    //////////////////
    // Constructors //
    //////////////////
    
    /**
     * Constructs a key action adapter.
     */
    public KeyActionAdapter() {
        this(null);
    }
    
    
    /**
     * Constructs a key action adapter
     * listening for key events
     * generated by the given component.
     *
     * If <CODE>null</CODE>, this adapter does not listen
     * to a particular component by default.
     *
     * @param source the source component to listen to
     */
    public KeyActionAdapter(Component target) {
        if (target != null)
            target.addKeyListener(this);
    }
    
    
    /////////////////
    // KeyListener //
    /////////////////

    /**
     * Performs the stored action sequence 
     * when a key has been pressed.
     *
     * @param evt the key pressed event to be handled
     */
    public final void keyPressed(KeyEvent evt) {
        pressedActions.actionPerformed(
            new KeyActionEvent(
                evt,
                evt.getSource(),
                ActionEvent.ACTION_PERFORMED,
                null,
                evt.getModifiers()));
    }
    
    
    /**
     * Performs the stored action sequence 
     * when a key has been released.
     *
     * @param evt the key released event to be handled
     */
    public final void keyReleased(KeyEvent evt) {
        releasedActions.actionPerformed(
            new KeyActionEvent(
                evt,
                evt.getSource(),
                ActionEvent.ACTION_PERFORMED,
                null,
                evt.getModifiers()));
    }
    
    
    /**
     * Performs the stored action sequence 
     * when a key has been typed.
     *
     * @param evt the key typed event to be handled
     */
    public final void keyTyped(KeyEvent evt) {
        typedActions.actionPerformed(
            new KeyActionEvent(
                evt,
                evt.getSource(),
                ActionEvent.ACTION_PERFORMED,
                null,
                evt.getModifiers()));
    }
    
    
    ////////////////
    // Public API //
    ////////////////
    
    /**
     * Adds an action listener to this adapter
     * so that it will be performed when a key is pressed.
     *
     * @param a the action listener to be performed
     * @see #removeKeyPressedAction(ActionListener)
     * @see #setKeyPressedActions(ActionSequence)
     * @see #getKeyPressedActions()
     */
    public void addKeyPressedAction(ActionListener a) {
        pressedActions.add(a);
    }
    
    
    /**
     * Adds an action listener to this adapter
     * so that it will be performed when a key is released.
     *
     * @param a the action listener to be performed
     * @see #removeKeyReleasedAction(ActionListener)
     * @see #setKeyReleasedActions(ActionSequence)
     * @see #getKeyReleasedActions()
     */
    public void addKeyReleasedAction(ActionListener a) {
        releasedActions.add(a);
    }
    
    
    /**
     * Adds an action listener to this adapter
     * so that it will be performed when a key is typed.
     *
     * @param a the action listener to be performed
     * @see #removeKeyTypedAction(ActionListener)
     * @see #setKeyTypedActions(ActionSequence)
     * @see #getKeyTypedActions()
     */
    public void addKeyTypedAction(ActionListener a) {
        typedActions.add(a);
    }
    
    
    /**
     * Removes the given action listener from this adapter
     * so that it will be no longer be performed 
     * when a key is pressed.
     *
     * @param a the action listener to be removed
     * @see #addKeyPressedAction(ActionListener)
     * @see #setKeyPressedActions(ActionSequence)
     * @see #getKeyPressedActions()
     */
    public void removeKeyPressedAction(ActionListener a) {
        pressedActions.remove(a);
    }
    
    
    /**
     * Removes the given action listener from this adapter
     * so that it will be no longer be performed 
     * when a key is released.
     *
     * @param a the action listener to be removed
     * @see #addKeyReleasedAction(ActionListener)
     * @see #setKeyReleasedActions(ActionSequence)
     * @see #getKeyReleasedActions()
     */
    public void removeKeyReleasedAction(ActionListener a) {
        releasedActions.remove(a);
    }
    
    
    /**
     * Removes the given action listener from this adapter
     * so that it will be no longer be performed 
     * when a key is typed.
     *
     * @param a the action listener to be removed
     * @see #addKeyTypedAction(ActionListener)
     * @see #setKeyTypedActions(ActionSequence)
     * @see #getKeyTypedActions()
     */
    public void removeKeyTypedAction(ActionListener a) {
        typedActions.remove(a);
    }
    
    
    /**
     * Sets the action sequence for key pressed events
     * to the provided action sequence.
     *
     * If <CODE>null</CODE>, the action sequence
     * for key pressed events is cleared.
     *
     * @param sequence the desired action sequence
     * @see #getKeyPressedActions()
     * @see #addKeyPressedAction(ActionListener)
     * @see #removeKeyPressedAction(ActionListener)
     */
    public void setKeyPressedActions(ActionSequence sequence) {
        if (sequence == null)
            pressedActions.clear();
        else
            pressedActions = sequence;
    }
    
    
    /**
     * Sets the action sequence for key released events
     * to the provided action sequence.
     *
     * If <CODE>null</CODE>, the action sequence
     * for key released events is cleared.
     *
     * @param sequence the desired action sequence
     * @see #getKeyReleasedActions()
     * @see #addKeyReleasedAction(ActionListener)
     * @see #removeKeyReleasedAction(ActionListener)
     */
    public void setKeyReleasedActions(ActionSequence sequence) {
        if (sequence == null)
            releasedActions.clear();
        else
            releasedActions = sequence;
    }
    
    /**
     * Sets the action sequence for key typed events
     * to the provided action sequence.
     *
     * If <CODE>null</CODE>, the action sequence
     * for key typed events is cleared.
     *
     * @param sequence the desired action sequence
     * @see #getKeyTypedActions()
     * @see #addKeyTypedAction(ActionListener)
     * @see #removeKeyTypedAction(ActionListener)
     */
    public void setKeyTypedActions(ActionSequence sequence) {
        if (sequence == null)
            typedActions.clear();
        else
            typedActions = sequence;
    }
    
    /**
     * Returns the action sequence for key pressed events.
     *
     * @see #setKeyPressedActions(ActionSequence)
     * @see #addKeyPressedAction(ActionListener)
     * @see #removeKeyPressedAction(ActionListener)
     */
    public ActionSequence getKeyPressedActions() {
        return pressedActions;
    }
    
    /**
     * Returns the action sequence for key released events.
     *
     * @see #setKeyReleasedActions(ActionSequence)
     * @see #addKeyReleasedAction(ActionListener)
     * @see #removeKeyReleasedAction(ActionListener)
     */
    public ActionSequence getKeyReleasedActions() {
        return releasedActions;
    }
    
    /**
     * Returns the action sequence for key typed events.
     *
     * @see #setKeyTypedActions(ActionSequence)
     * @see #addKeyTypedAction(ActionListener)
     * @see #removeKeyTypedAction(ActionListener)
     */
    public ActionSequence getKeyTypedActions() {
        return typedActions;
    }
    
}