/*
 * @(#)PaintActionCapsule.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 edu.neu.ccs.util.*;

import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

/**
 * <P>A <CODE>JComponent</CODE> that contains 
 * a sequence of action listeners performed every time 
 * this component is painted.</P>
 *
 * @author  Jeff Raab
 * @version 2.2
 * @since 2.2
 */
public class PaintActionCapsule extends JComponent {

    /** Sequence of action listeners to perform when painted. */
    protected ActionSequence actions = new ActionSequence();
    
    
    //////////////////
    // Constructors //
    //////////////////

    /** Constructs a component with no action listeners to perform. */
    public PaintActionCapsule() {}
    
    
    /**
     * Constructs a component
     * that performs the given action listener
     * each time it is painted.
     *
     * @param a action listener to perform
     * @see #PaintActionCapsule(ActionListener, Color)
     * @see #PaintActionCapsule(ActionListener, Dimension)
     * @see #PaintActionCapsule(ActionListener, int, int)
     * @see #PaintActionCapsule(ActionListener, Color, Dimension)
     * @see #PaintActionCapsule(ActionListener, Color, int, int)
     */
    public PaintActionCapsule(ActionListener a) {
        this(new ActionListener[] { a });
    }
    
    
    /**
     * Constructs a component with the given foreground color
     * that performs the given action listener
     * each time it is painted.
     *
     * @param a action listener to perform
     * @param c foreground color for component
     * @see #PaintActionCapsule(ActionListener)
     * @see #PaintActionCapsule(ActionListener, Dimension)
     * @see #PaintActionCapsule(ActionListener, int, int)
     * @see #PaintActionCapsule(ActionListener, Color, Dimension)
     * @see #PaintActionCapsule(ActionListener, Color, int, int)
     */
    public PaintActionCapsule(ActionListener a, Color c) {
        this(new ActionListener[] { a }, c);
    }
    
    
    /**
     * Constructs a component with the given preferred size
     * that performs the given action listener
     * each time it is painted.
     *
     * @param a action listener to perform
     * @param d preferred size for component
     * @see #PaintActionCapsule(ActionListener)
     * @see #PaintActionCapsule(ActionListener, Color)
     * @see #PaintActionCapsule(ActionListener, int, int)
     * @see #PaintActionCapsule(ActionListener, Color, Dimension)
     * @see #PaintActionCapsule(ActionListener, Color, int, int)
     */
    public PaintActionCapsule(ActionListener a, Dimension d) {
        this(new ActionListener[] { a }, d);
    }
    
    
    /**
     * Constructs a component with the given preferred dimensions
     * that performs the given action listener
     * each time it is painted.
     *
     * @param a action listener to perform
     * @param width preferred width for component
     * @param height preferred height for component
     * @see #PaintActionCapsule(ActionListener)
     * @see #PaintActionCapsule(ActionListener, Color)
     * @see #PaintActionCapsule(ActionListener, Dimension)
     * @see #PaintActionCapsule(ActionListener, Color, Dimension)
     * @see #PaintActionCapsule(ActionListener, Color, int, int)
     */
    public PaintActionCapsule(ActionListener a, int width, int height) {
        this(new ActionListener[] { a }, 
             DimensionUtilities.createDimension(width, height));
    }
    
    
    /**
     * Constructs a component 
     * with the given foreground color and preferred size
     * that performs the given action listener
     * each time it is painted.
     *
     * @param a action listener to perform
     * @param c foreground color for component
     * @param d preferred size for component
     * @see #PaintActionCapsule(ActionListener)
     * @see #PaintActionCapsule(ActionListener, Color)
     * @see #PaintActionCapsule(ActionListener, Dimension)
     * @see #PaintActionCapsule(ActionListener, int, int)
     * @see #PaintActionCapsule(ActionListener, Color, int, int)
     */
    public PaintActionCapsule(ActionListener a, Color c, Dimension d) {
        this(new ActionListener[] { a }, c, d);
    }
    
    
    /**
     * Constructs a component 
     * with the given foreground color and preferred dimensions
     * that performs the given action listener
     * each time it is painted.
     *
     * @param a action listener to perform
     * @param c foreground color for component
     * @param width preferred width for component
     * @param height preferred height for component
     * @see #PaintActionCapsule(ActionListener)
     * @see #PaintActionCapsule(ActionListener, Color)
     * @see #PaintActionCapsule(ActionListener, Dimension)
     * @see #PaintActionCapsule(ActionListener, int, int)
     * @see #PaintActionCapsule(ActionListener, Color, Dimension)
     */
    public PaintActionCapsule(ActionListener a, Color c, int width, int height) {
        this(new ActionListener[] { a }, 
             c, 
             DimensionUtilities.createDimension(width, height));
    }
    
    
    /**
     * Constructs a component
     * that performs the given action listeners
     * each time it is painted.
     *
     * @param a array of action listeners to perform
     * @see #PaintActionCapsule(ActionListener[], Color)
     * @see #PaintActionCapsule(ActionListener[], Dimension)
     * @see #PaintActionCapsule(ActionListener[], int, int)
     * @see #PaintActionCapsule(ActionListener[], Color, Dimension)
     * @see #PaintActionCapsule(ActionListener[], Color, int, int)
     */
    public PaintActionCapsule(ActionListener[] a) {
        setActions(a);
    }
    
    
    /**
     * Constructs a component with the given foreground color
     * that performs the given action listeners
     * each time it is painted.
     *
     * @param a array of action listeners to perform
     * @param c foreground color for component
     * @see #PaintActionCapsule(ActionListener[])
     * @see #PaintActionCapsule(ActionListener[], Dimension)
     * @see #PaintActionCapsule(ActionListener[], int, int)
     * @see #PaintActionCapsule(ActionListener[], Color, Dimension)
     * @see #PaintActionCapsule(ActionListener[], Color, int, int)
     */
    public PaintActionCapsule(ActionListener[] a, Color c) {
        setActions(a);
        setForeground(c);
    }
    
    
    /**
     * Constructs a component with the given preferred size
     * that performs the given action listeners
     * each time it is painted.
     *
     * @param a array of action listeners to perform
     * @param d preferred size for component
     * @see #PaintActionCapsule(ActionListener[])
     * @see #PaintActionCapsule(ActionListener[], Color)
     * @see #PaintActionCapsule(ActionListener[], int, int)
     * @see #PaintActionCapsule(ActionListener[], Color, Dimension)
     * @see #PaintActionCapsule(ActionListener[], Color, int, int)
     */
    public PaintActionCapsule(ActionListener[] a, Dimension d) {
        setActions(a);
        setPreferredSize(d);
    }
    
    
    /**
     * Constructs a component with the given preferred size
     * that performs the given action listeners
     * each time it is painted.
     *
     * @param a array of action listeners to perform
     * @param width preferred width for component
     * @param height preferred height for component
     * @see #PaintActionCapsule(ActionListener[])
     * @see #PaintActionCapsule(ActionListener[], Color)
     * @see #PaintActionCapsule(ActionListener[], Dimension)
     * @see #PaintActionCapsule(ActionListener[], Color, Dimension)
     * @see #PaintActionCapsule(ActionListener[], Color, int, int)
     */
    public PaintActionCapsule(ActionListener[] a, int width, int height) {
        this(a, DimensionUtilities.createDimension(width, height));
    }
    
    
    /**
     * Constructs a component 
     * with the given foreground color and preferred size
     * that performs the given action listeners
     * each time it is painted.
     *
     * @param a array of action listeners to perform
     * @param c foreground color for component
     * @param d preferred size for component
     * @see #PaintActionCapsule(ActionListener[])
     * @see #PaintActionCapsule(ActionListener[], Color)
     * @see #PaintActionCapsule(ActionListener[], Dimension)
     * @see #PaintActionCapsule(ActionListener[], int, int)
     * @see #PaintActionCapsule(ActionListener[], Color, int, int)
     */
    public PaintActionCapsule(ActionListener[] a, Color c, Dimension d) {
        setActions(a);
        setForeground(c);
        setPreferredSize(d);
    }
    
    
    /**
     * Constructs a component 
     * with the given foreground color and preferred dimensions
     * that performs the given action listeners
     * each time it is painted.
     *
     * @param a array of action listeners to perform
     * @param c foreground color for component
     * @param width preferred width for component
     * @param height preferred height for component
     * @see #PaintActionCapsule(ActionListener[])
     * @see #PaintActionCapsule(ActionListener[], Color)
     * @see #PaintActionCapsule(ActionListener[], Dimension)
     * @see #PaintActionCapsule(ActionListener[], int, int)
     * @see #PaintActionCapsule(ActionListener[], Color, Dimension)
     */
    public PaintActionCapsule(ActionListener[] a, Color c, int width, int height) {
        this(a, c, DimensionUtilities.createDimension(width, height));
    }
    
    
    ////////////////
    // Public API //
    ////////////////
    
    /** 
     * Returns the sequence of action listeners 
     * performed when this component is painted. 
     *
     * @see #setActionSequence(ActionSequence)
     */
    public ActionSequence getActionSequence() {
        return actions;
    }
    
    
    /**
     * Sets the sequence of action listeners
     * performed when this component is painted
     * to the given sequence of action listeners.
     *
     * If the given sequence of action listeners
     * is <CODE>null</CODE>,
     * the sequence of action listeners 
     * performed when this component is painted
     * is set to a new empty sequence.
     *
     * @param sequence sequence of action listeners to perform
     * @see #getActionSequence()
     */
    public void setActionSequence(ActionSequence sequence) {
        if (sequence == null)
            sequence = new ActionSequence();
        
        actions = sequence;
    }
    
    
    /**
     * Adds the given action listener to the end of the sequence
     * of action listeners
     * performed when this component is painted.
     *
     * If the given action is <CODE>null</CODE>,
     * the sequence of action listeners is not changed.
     *
     * @param a action listener to add to the sequence of action listeners
     * @see #addActions(ActionListener[])
     * @see #setAction(ActionListener)
     * @see #setActions(ActionListener[])
     */
    public void addAction(ActionListener a) {
        if (a == null)
            return;
            
        actions.add(a);
    }
    
    
    /**
     * Adds the action listeners in the given array, in order,
     * to the end of the sequence of action listeners
     * performed when this component is painted.
     *
     * If the given array is <CODE>null</CODE>,
     * the sequence of action listeners is not changed.
     *
     * @see #addAction(ActionListener)
     * @see #setAction(ActionListener)
     * @see #setActions(ActionListener[])
     */
    public void addActions(ActionListener[] a) {
        if (a == null)
            return;
        
        for (int i = 0; i < a.length; i++)
            actions.add(a[i]);
    }
    
    
    /**
     * Removes the first occurrence of the given action listener in 
     * the sequence of action listeners performed when this component
     * is painted, and returns <CODE>true</CODE>, 
     * or returns <CODE>false</CODE> if the sequence 
     * does not contain the action listener.
     *
     * If the given action listener is not in the sequence,
     * the sequence is not changed.
     *
     * @param a action listener to no longer perform
     * @return the action that was removed
     */
    public boolean removeAction(ActionListener a) {
        if (a == null)
            return false;
        
        return actions.remove(a);
    }
    
    
    /**
     * Sets the action performed when this component is painted
     * to the given action listener.
     *
     * The existing sequence of action listeners is eliminated.
     *
     * If the given action listener is <CODE>null</CODE>,
     * the sequence of action listeners 
     * performed when this component is painted
     * is set to a new empty sequence.
     *
     * @param a action listener to perform
     * @see #setActions(ActionListener[])
     * @see #addAction(ActionListener)
     * @see #addActions(ActionListener[])
     */
    public void setAction(ActionListener a) {
        if (a == null)
            setActions(null);
        else
            setActions(new ActionListener[] { a });
    }
    
    
    /**
     * Sets the action listeners performed when this component
     * is painted to the action listeners in the given array,
     * in order.
     *
     * The existing sequence of action listeners is eliminated.
     *
     * If the given array is <CODE>null</CODE>,
     * the sequence of action listeners 
     * performed when this component is painted
     * is set to a new empty sequence.
     *
     * @param a array of action listeners to perform
     * @see #setAction(ActionListener)
     * @see #addAction(ActionListener)
     * @see #addActions(ActionListener[])
     */
    public void setActions(ActionListener[] a) {
        actions.clear();
        
        addActions(a);
    }
    
    
    ///////////////////////
    // Protected methods //
    ///////////////////////
    
    /**
     * Performs the stored sequence of action listeners.
     *
     * @param g graphics context on which to paint
     */
    protected final void paintComponent(Graphics g) {
        super.paintComponent(g);
        
        PaintActionEvent pevt = new PaintActionEvent(this, g);
        
        actions.actionPerformed(pevt);
    }
    
}