/*

 * Copyright 1997-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code 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

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.swing;

import java.awt.*;

import java.awt.event.*;

import java.awt.image.*;

import java.text.*;

import java.awt.geom.*;

import java.beans.*;

import java.util.Enumeration;

import java.util.Vector;

import java.io.Serializable;

import javax.swing.event.*;

import javax.swing.border.*;

import javax.swing.plaf.*;

import javax.accessibility.*;

import javax.swing.text.*;

import javax.swing.text.html.*;

import javax.swing.plaf.basic.*;

import java.util.*;

/**

 * Defines common behaviors for buttons and menu items.

 * <p>

 * Buttons can be configured, and to some degree controlled, by

 * <code><a href="Action.html">Action</a></code>s.  Using an

 * <code>Action</code> with a button has many benefits beyond directly

 * configuring a button.  Refer to <a href="Action.html#buttonActions">

 * Swing Components Supporting <code>Action</code></a> for more

 * details, and you can find more information in <a

 * href="http://java.sun.com/docs/books/tutorial/uiswing/misc/action.html">How

 * to Use Actions</a>, a section in <em>The Java Tutorial</em>.

 * <p>

 * For further information see

 * <a

 href="http://java.sun.com/docs/books/tutorial/uiswing/components/button.html">How to Use Buttons, Check Boxes, and Radio Buttons</a>,

 * a section in <em>The Java Tutorial</em>.

 * <p>

 * <strong>Warning:</strong>

 * Serialized objects of this class will not be compatible with

 * future Swing releases. The current serialization support is

 * appropriate for short term storage or RMI between applications running

 * the same version of Swing.  As of 1.4, support for long term storage

 * of all JavaBeans<sup><font size="-2">TM</font></sup>

 * has been added to the <code>java.beans</code> package.

 * Please see {@link java.beans.XMLEncoder}.

 *

 * @author Jeff Dinkins

 */

public abstract class AbstractButton extends JComponent implements ItemSelectable, SwingConstants {

    // *********************************

    // ******* Button properties *******

    // *********************************

    /** Identifies a change in the button model. */

    public static final String MODEL_CHANGED_PROPERTY = "model";

    /** Identifies a change in the button's text. */

    public static final String TEXT_CHANGED_PROPERTY = "text";

    /** Identifies a change to the button's mnemonic. */

    public static final String MNEMONIC_CHANGED_PROPERTY = "mnemonic";

    // Text positioning and alignment

    /** Identifies a change in the button's margins. */

    public static final String MARGIN_CHANGED_PROPERTY = "margin";

    /** Identifies a change in the button's vertical alignment. */

    public static final String VERTICAL_ALIGNMENT_CHANGED_PROPERTY = "verticalAlignment";

    /** Identifies a change in the button's horizontal alignment. */

    public static final String HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY = "horizontalAlignment";

    /** Identifies a change in the button's vertical text position. */

    public static final String VERTICAL_TEXT_POSITION_CHANGED_PROPERTY = "verticalTextPosition";

    /** Identifies a change in the button's horizontal text position. */

    public static final String HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY = "horizontalTextPosition";

    // Paint options

    /**

     * Identifies a change to having the border drawn,

     * or having it not drawn.

     */

    public static final String BORDER_PAINTED_CHANGED_PROPERTY = "borderPainted";

    /**

     * Identifies a change to having the border highlighted when focused,

     * or not.

     */

    public static final String FOCUS_PAINTED_CHANGED_PROPERTY = "focusPainted";

    /**

     * Identifies a change from rollover enabled to disabled or back

     * to enabled.

     */

    public static final String ROLLOVER_ENABLED_CHANGED_PROPERTY = "rolloverEnabled";

    /**

     * Identifies a change to having the button paint the content area.

     */

    public static final String CONTENT_AREA_FILLED_CHANGED_PROPERTY = "contentAreaFilled";

    // Icons

    /** Identifies a change to the icon that represents the button. */

    public static final String ICON_CHANGED_PROPERTY = "icon";

    /**

     * Identifies a change to the icon used when the button has been

     * pressed.

     */

    public static final String PRESSED_ICON_CHANGED_PROPERTY = "pressedIcon";

    /**

     * Identifies a change to the icon used when the button has

     * been selected.

     */

    public static final String SELECTED_ICON_CHANGED_PROPERTY = "selectedIcon";

    /**

     * Identifies a change to the icon used when the cursor is over

     * the button.

     */

    public static final String ROLLOVER_ICON_CHANGED_PROPERTY = "rolloverIcon";

    /**

     * Identifies a change to the icon used when the cursor is

     * over the button and it has been selected.

     */

    public static final String ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY = "rolloverSelectedIcon";

    /**

     * Identifies a change to the icon used when the button has

     * been disabled.

     */

    public static final String DISABLED_ICON_CHANGED_PROPERTY = "disabledIcon";

    /**

     * Identifies a change to the icon used when the button has been

     * disabled and selected.

     */

    public static final String DISABLED_SELECTED_ICON_CHANGED_PROPERTY = "disabledSelectedIcon";

    /** The data model that determines the button's state. */

    protected ButtonModel model                = null;

    private String     text                    = ""; // for BeanBox

    private Insets     margin                  = null;

    private Insets     defaultMargin           = null;

    // Button icons

    // PENDING(jeff) - hold icons in an array

    private Icon       defaultIcon             = null;

    private Icon       pressedIcon             = null;

    private Icon       disabledIcon            = null;

    private Icon       selectedIcon            = null;

    private Icon       disabledSelectedIcon    = null;

    private Icon       rolloverIcon            = null;

    private Icon       rolloverSelectedIcon    = null;

    // Display properties

    private boolean    paintBorder             = true;

    private boolean    paintFocus              = true;

    private boolean    rolloverEnabled         = false;

    private boolean    contentAreaFilled         = true;

    // Icon/Label Alignment

    private int        verticalAlignment       = CENTER;

    private int        horizontalAlignment     = CENTER;

    private int        verticalTextPosition    = CENTER;

    private int        horizontalTextPosition  = TRAILING;

    private int        iconTextGap             = 4;

    private int        mnemonic;

    private int        mnemonicIndex           = -1;

    private long       multiClickThreshhold    = 0;

    private boolean    borderPaintedSet        = false;

    private boolean    rolloverEnabledSet      = false;

    private boolean    iconTextGapSet          = false;

    private boolean    contentAreaFilledSet    = false;

    // Whether or not we've set the LayoutManager.

    private boolean setLayout = false;

    // This is only used by JButton, promoted to avoid an extra

    // boolean field in JButton

    boolean defaultCapable = true;

    /**

     * Combined listeners: ActionListener, ChangeListener, ItemListener.

     */

    private Handler handler;

    /**

     * The button model's <code>changeListener</code>.

     */

    protected ChangeListener changeListener = null;

    /**

     * The button model's <code>ActionListener</code>.

     */

    protected ActionListener actionListener = null;

    /**

     * The button model's <code>ItemListener</code>.

     */

    protected ItemListener itemListener = null;

    /**

     * Only one <code>ChangeEvent</code> is needed per button

     * instance since the

     * event's only state is the source property.  The source of events

     * generated is always "this".

     */

    protected transient ChangeEvent changeEvent;

    private boolean hideActionText = false;

    /**

     * Sets the <code>hideActionText</code> property, which determines

     * whether the button displays text from the <code>Action</code>.

     * This is useful only if an <code>Action</code> has been

     * installed on the button.

     *

     * @param hideActionText <code>true</code> if the button's

     *                       <code>text</code> property should not reflect

     *                       that of the <code>Action</code>; the default is

     *                       <code>false</code>

     * @see <a href="Action.html#buttonActions">Swing Components Supporting

     *      <code>Action</code></a>

     * @since 1.6

     * @beaninfo

     *        bound: true

     *    expert: true

     *  description: Whether the text of the button should come from

     *               the <code>Action</code>.

     */

    public void setHideActionText(boolean hideActionText) {

        if (hideActionText != this.hideActionText) {

            this.hideActionText = hideActionText;

            if (getAction() != null) {

                setTextFromAction(getAction(), false);

            }

            firePropertyChange("hideActionText", !hideActionText,

                               hideActionText);

        }

    }

    /**

     * Returns the value of the <code>hideActionText</code> property, which

     * determines whether the button displays text from the

     * <code>Action</code>.  This is useful only if an <code>Action</code>

     * has been installed on the button.

     *

     * @return <code>true</code> if the button's <code>text</code>

     *         property should not reflect that of the

     *         <code>Action</code>; the default is <code>false</code>

     * @since 1.6

     */

    public boolean getHideActionText() {

        return hideActionText;

    }

    /**

     * Returns the button's text.

     * @return the buttons text

     * @see #setText

     */

    public String getText() {

        return text;

    }

    /**

     * Sets the button's text.

     * @param text the string used to set the text

     * @see #getText

     * @beaninfo

     *        bound: true

     *    preferred: true

     *    attribute: visualUpdate true

     *  description: The button's text.

     */

    public void setText(String text) {

        String oldValue = this.text;

        this.text = text;

        firePropertyChange(TEXT_CHANGED_PROPERTY, oldValue, text);

        updateDisplayedMnemonicIndex(text, getMnemonic());

        if (accessibleContext != null) {

            accessibleContext.firePropertyChange(

                AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,

                oldValue, text);

        }

        if (text == null || oldValue == null || !text.equals(oldValue)) {

            revalidate();

            repaint();

        }

    }

    /**

     * Returns the state of the button. True if the

     * toggle button is selected, false if it's not.

     * @return true if the toggle button is selected, otherwise false

     */

    public boolean isSelected() {

        return model.isSelected();

    }

    /**

     * Sets the state of the button. Note that this method does not

     * trigger an <code>actionEvent</code>.

     * Call <code>doClick</code> to perform a programatic action change.

     *

     * @param b  true if the button is selected, otherwise false

     */

    public void setSelected(boolean b) {

        boolean oldValue = isSelected();

        // TIGER - 4840653

        // Removed code which fired an AccessibleState.SELECTED

        // PropertyChangeEvent since this resulted in two

        // identical events being fired since

        // AbstractButton.fireItemStateChanged also fires the

        // same event. This caused screen readers to speak the

        // name of the item twice.

        model.setSelected(b);

    }

    /**

     * Programmatically perform a "click". This does the same

     * thing as if the user had pressed and released the button.

     */

    public void doClick() {

        doClick(68);

    }

    /**

     * Programmatically perform a "click". This does the same

     * thing as if the user had pressed and released the button.

     * The button stays visually "pressed" for <code>pressTime</code>

     *  milliseconds.

     *

     * @param pressTime the time to "hold down" the button, in milliseconds

     */

    public void doClick(int pressTime) {

        Dimension size = getSize();

        model.setArmed(true);

        model.setPressed(true);

        paintImmediately(new Rectangle(0,0, size.width, size.height));

        try {

            Thread.currentThread().sleep(pressTime);

        } catch(InterruptedException ie) {

        }

        model.setPressed(false);

        model.setArmed(false);

    }

    /**

     * Sets space for margin between the button's border and

     * the label. Setting to <code>null</code> will cause the button to

     * use the default margin.  The button's default <code>Border</code>

     * object will use this value to create the proper margin.

     * However, if a non-default border is set on the button,

     * it is that <code>Border</code> object's responsibility to create the

     * appropriate margin space (else this property will

     * effectively be ignored).

     *

     * @param m the space between the border and the label

     *

     * @beaninfo

     *        bound: true

     *    attribute: visualUpdate true

     *  description: The space between the button's border and the label.

     */

    public void setMargin(Insets m) {

        // Cache the old margin if it comes from the UI

        if(m instanceof UIResource) {

            defaultMargin = m;

        } else if(margin instanceof UIResource) {

            defaultMargin = margin;

        }

        // If the client passes in a null insets, restore the margin

        // from the UI if possible

        if(m == null && defaultMargin != null) {

            m = defaultMargin;

        }

        Insets old = margin;

        margin = m;

        firePropertyChange(MARGIN_CHANGED_PROPERTY, old, m);

        if (old == null || !old.equals(m)) {

            revalidate();

            repaint();

        }

    }

    /**

     * Returns the margin between the button's border and

     * the label.

     *

     * @return an <code>Insets</code> object specifying the margin

     *          between the botton's border and the label

     * @see #setMargin

     */

    public Insets getMargin() {

        return (margin == null) ? null : (Insets) margin.clone();

    }

    /**

     * Returns the default icon.

     * @return the default <code>Icon</code>

     * @see #setIcon

     */

    public Icon getIcon() {

        return defaultIcon;

    }

    /**

     * Sets the button's default icon. This icon is

     * also used as the "pressed" and "disabled" icon if

     * there is no explicitly set pressed icon.

     *

     * @param defaultIcon the icon used as the default image

     * @see #getIcon

     * @see #setPressedIcon

     * @beaninfo

     *           bound: true

     *       attribute: visualUpdate true

     *     description: The button's default icon

     */

    public void setIcon(Icon defaultIcon) {

        Icon oldValue = this.defaultIcon;

        this.defaultIcon = defaultIcon;

        /* If the default icon has really changed and we had

         * generated the disabled icon for this component,

         * (i.e. setDisabledIcon() was never called) then

         * clear the disabledIcon field.

         */

        if (defaultIcon != oldValue && (disabledIcon instanceof UIResource)) {

            disabledIcon = null;

        }

        firePropertyChange(ICON_CHANGED_PROPERTY, oldValue, defaultIcon);

        if (accessibleContext != null) {

            accessibleContext.firePropertyChange(

                AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,

                oldValue, defaultIcon);

        }

        if (defaultIcon != oldValue) {

            if (defaultIcon == null || oldValue == null ||

                defaultIcon.getIconWidth() != oldValue.getIconWidth() ||

                defaultIcon.getIconHeight() != oldValue.getIconHeight()) {

                revalidate();

            }

            repaint();

        }

    }

    /**

     * Returns the pressed icon for the button.

     * @return the <code>pressedIcon</code> property

     * @see #setPressedIcon

     */

    public Icon getPressedIcon() {

        return pressedIcon;

    }

    /**

     * Sets the pressed icon for the button.

     * @param pressedIcon the icon used as the "pressed" image

     * @see #getPressedIcon

     * @beaninfo

     *        bound: true

     *    attribute: visualUpdate true

     *  description: The pressed icon for the button.

     */

    public void setPressedIcon(Icon pressedIcon) {

        Icon oldValue = this.pressedIcon;

        this.pressedIcon = pressedIcon;

        firePropertyChange(PRESSED_ICON_CHANGED_PROPERTY, oldValue, pressedIcon);

        if (accessibleContext != null) {

            accessibleContext.firePropertyChange(

                AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,

                oldValue, pressedIcon);

        }

        if (pressedIcon != oldValue) {

            if (getModel().isPressed()) {

                repaint();

            }

        }

    }

    /**

     * Returns the selected icon for the button.

     * @return the <code>selectedIcon</code> property

     * @see #setSelectedIcon

     */

    public Icon getSelectedIcon() {

        return selectedIcon;

    }

    /**

     * Sets the selected icon for the button.

     * @param selectedIcon the icon used as the "selected" image

     * @see #getSelectedIcon

     * @beaninfo