/*

 * Copyright (c) 1997, 2009, Oracle and/or its affiliates. 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.  Oracle designates this

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

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.swing;

import java.awt.Component;

import java.awt.Font;

import java.awt.Image;

import java.awt.*;

import java.text.*;

import java.awt.geom.*;

import java.beans.Transient;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

import javax.swing.plaf.LabelUI;

import javax.accessibility.*;

import javax.swing.text.*;

import javax.swing.text.html.*;

import javax.swing.plaf.basic.*;

import java.util.*;

/**

 * A display area for a short text string or an image,

 * or both.

 * A label does not react to input events.

 * As a result, it cannot get the keyboard focus.

 * A label can, however, display a keyboard alternative

 * as a convenience for a nearby component

 * that has a keyboard alternative but can't display it.

 * <p>

 * A <code>JLabel</code> object can display

 * either text, an image, or both.

 * You can specify where in the label's display area

 * the label's contents are aligned

 * by setting the vertical and horizontal alignment.

 * By default, labels are vertically centered

 * in their display area.

 * Text-only labels are leading edge aligned, by default;

 * image-only labels are horizontally centered, by default.

 * <p>

 * You can also specify the position of the text

 * relative to the image.

 * By default, text is on the trailing edge of the image,

 * with the text and image vertically aligned.

 * <p>

 * A label's leading and trailing edge are determined from the value of its

 * {@link java.awt.ComponentOrientation} property.  At present, the default

 * ComponentOrientation setting maps the leading edge to left and the trailing

 * edge to right.

 *

 * <p>

 * Finally, you can use the <code>setIconTextGap</code> method

 * to specify how many pixels

 * should appear between the text and the image.

 * The default is 4 pixels.

 * <p>

 * See <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/label.html">How to Use Labels</a>

 * in <em>The Java Tutorial</em>

 * for further documentation.

 * <p>

 * <strong>Warning:</strong> Swing is not thread safe. For more

 * information see <a

 * href="package-summary.html#threading">Swing's Threading

 * Policy</a>.

 * <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™

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

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

 *

 * @beaninfo

 *   attribute: isContainer false

 * description: A component that displays a short string and an icon.

 *

 * @author Hans Muller

 */

@SuppressWarnings("serial")

public class JLabel extends JComponent implements SwingConstants, Accessible

{

    /**

     * @see #getUIClassID

     * @see #readObject

     */

    private static final String uiClassID = "LabelUI";

    private int mnemonic = '\0';

    private int mnemonicIndex = -1;

    private String text = "";         // "" rather than null, for BeanBox

    private Icon defaultIcon = null;

    private Icon disabledIcon = null;

    private boolean disabledIconSet = false;

    private int verticalAlignment = CENTER;

    private int horizontalAlignment = LEADING;

    private int verticalTextPosition = CENTER;

    private int horizontalTextPosition = TRAILING;

    private int iconTextGap = 4;

    protected Component labelFor = null;

    /**

     * Client property key used to determine what label is labeling the

     * component.  This is generally not used by labels, but is instead

     * used by components such as text areas that are being labeled by

     * labels.  When the labelFor property of a label is set, it will

     * automatically set the LABELED_BY_PROPERTY of the component being

     * labelled.

     *

     * @see #setLabelFor

     */

    static final String LABELED_BY_PROPERTY = "labeledBy";

    /**

     * Creates a <code>JLabel</code> instance with the specified

     * text, image, and horizontal alignment.

     * The label is centered vertically in its display area.

     * The text is on the trailing edge of the image.

     *

     * @param text  The text to be displayed by the label.

     * @param icon  The image to be displayed by the label.

     * @param horizontalAlignment  One of the following constants

     *           defined in <code>SwingConstants</code>:

     *           <code>LEFT</code>,

     *           <code>CENTER</code>,

     *           <code>RIGHT</code>,

     *           <code>LEADING</code> or

     *           <code>TRAILING</code>.

     */

    public JLabel(String text, Icon icon, int horizontalAlignment) {

        setText(text);

        setIcon(icon);

        setHorizontalAlignment(horizontalAlignment);

        updateUI();

        setAlignmentX(LEFT_ALIGNMENT);

    }

    /**

     * Creates a <code>JLabel</code> instance with the specified

     * text and horizontal alignment.

     * The label is centered vertically in its display area.

     *

     * @param text  The text to be displayed by the label.

     * @param horizontalAlignment  One of the following constants

     *           defined in <code>SwingConstants</code>:

     *           <code>LEFT</code>,

     *           <code>CENTER</code>,

     *           <code>RIGHT</code>,

     *           <code>LEADING</code> or

     *           <code>TRAILING</code>.

     */

    public JLabel(String text, int horizontalAlignment) {

        this(text, null, horizontalAlignment);

    }

    /**

     * Creates a <code>JLabel</code> instance with the specified text.

     * The label is aligned against the leading edge of its display area,

     * and centered vertically.

     *

     * @param text  The text to be displayed by the label.

     */

    public JLabel(String text) {

        this(text, null, LEADING);

    }

    /**

     * Creates a <code>JLabel</code> instance with the specified

     * image and horizontal alignment.

     * The label is centered vertically in its display area.

     *

     * @param image  The image to be displayed by the label.

     * @param horizontalAlignment  One of the following constants

     *           defined in <code>SwingConstants</code>:

     *           <code>LEFT</code>,

     *           <code>CENTER</code>,

     *           <code>RIGHT</code>,

     *           <code>LEADING</code> or

     *           <code>TRAILING</code>.

     */

    public JLabel(Icon image, int horizontalAlignment) {

        this(null, image, horizontalAlignment);

    }

    /**

     * Creates a <code>JLabel</code> instance with the specified image.

     * The label is centered vertically and horizontally

     * in its display area.

     *

     * @param image  The image to be displayed by the label.

     */

    public JLabel(Icon image) {

        this(null, image, CENTER);

    }

    /**

     * Creates a <code>JLabel</code> instance with

     * no image and with an empty string for the title.

     * The label is centered vertically

     * in its display area.

     * The label's contents, once set, will be displayed on the leading edge

     * of the label's display area.

     */

    public JLabel() {

        this("", null, LEADING);

    }

    /**

     * Returns the L&F object that renders this component.

     *

     * @return LabelUI object

     */

    public LabelUI getUI() {

        return (LabelUI)ui;

    }

    /**

     * Sets the L&F object that renders this component.

     *

     * @param ui  the LabelUI L&F object

     * @see UIDefaults#getUI

     * @beaninfo

     *        bound: true

     *       hidden: true

     *    attribute: visualUpdate true

     *  description: The UI object that implements the Component's LookAndFeel.

     */

    public void setUI(LabelUI ui) {

        super.setUI(ui);

        // disabled icon is generated by LF so it should be unset here

        if (!disabledIconSet && disabledIcon != null) {

            setDisabledIcon(null);

        }

    }

    /**

     * Resets the UI property to a value from the current look and feel.

     *

     * @see JComponent#updateUI

     */

    public void updateUI() {

        setUI((LabelUI)UIManager.getUI(this));

    }

    /**

     * Returns a string that specifies the name of the l&f class

     * that renders this component.

     *

     * @return String "LabelUI"

     *

     * @see JComponent#getUIClassID

     * @see UIDefaults#getUI

     */

    public String getUIClassID() {

        return uiClassID;

    }

    /**

     * Returns the text string that the label displays.

     *

     * @return a String

     * @see #setText

     */

    public String getText() {

        return text;

    }

    /**

     * Defines the single line of text this component will display.  If

     * the value of text is null or empty string, nothing is displayed.

     * <p>

     * The default value of this property is null.

     * <p>

     * This is a JavaBeans bound property.

     *

     * @see #setVerticalTextPosition

     * @see #setHorizontalTextPosition

     * @see #setIcon

     * @beaninfo

     *    preferred: true

     *        bound: true

     *    attribute: visualUpdate true

     *  description: Defines the single line of text this component will display.

     */

    public void setText(String text) {

        String oldAccessibleName = null;

        if (accessibleContext != null) {

            oldAccessibleName = accessibleContext.getAccessibleName();

        }

        String oldValue = this.text;

        this.text = text;

        firePropertyChange("text", oldValue, text);

        setDisplayedMnemonicIndex(

                      SwingUtilities.findDisplayedMnemonicIndex(

                                          text, getDisplayedMnemonic()));

        if ((accessibleContext != null)

            && (accessibleContext.getAccessibleName() != oldAccessibleName)) {

                accessibleContext.firePropertyChange(

                        AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,

                        oldAccessibleName,

                        accessibleContext.getAccessibleName());

        }

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

            revalidate();

            repaint();

        }

    }

    /**

     * Returns the graphic image (glyph, icon) that the label displays.

     *

     * @return an Icon

     * @see #setIcon

     */

    public Icon getIcon() {

        return defaultIcon;

    }

    /**

     * Defines the icon this component will display.  If

     * the value of icon is null, nothing is displayed.

     * <p>

     * The default value of this property is null.

     * <p>

     * This is a JavaBeans bound property.

     *

     * @see #setVerticalTextPosition

     * @see #setHorizontalTextPosition

     * @see #getIcon

     * @beaninfo

     *    preferred: true

     *        bound: true

     *    attribute: visualUpdate true

     *  description: The icon this component will display.

     */

    public void setIcon(Icon icon) {

        Icon oldValue = defaultIcon;

        defaultIcon = icon;

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

         * generated the disabled icon for this component

         * (in other words, setDisabledIcon() was never called), then

         * clear the disabledIcon field.

         */

        if ((defaultIcon != oldValue) && !disabledIconSet) {

            disabledIcon = null;

        }

        firePropertyChange("icon", oldValue, defaultIcon);

        if ((accessibleContext != null) && (oldValue != defaultIcon)) {

                accessibleContext.firePropertyChange(

                        AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,

                        oldValue, defaultIcon);

        }

        /* If the default icon has changed and the new one is

         * a different size, then revalidate.   Repaint if the

         * default icon has changed.

         */

        if (defaultIcon != oldValue) {

            if ((defaultIcon == null) ||

                (oldValue == null) ||

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

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

                revalidate();

            }

            repaint();

        }

    }

    /**

     * Returns the icon used by the label when it's disabled.

     * If no disabled icon has been set this will forward the call to

     * the look and feel to construct an appropriate disabled Icon.

     * <p>

     * Some look and feels might not render the disabled Icon, in which

     * case they will ignore this.

     *

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

     * @see #setDisabledIcon

     * @see javax.swing.LookAndFeel#getDisabledIcon

     * @see ImageIcon

     */

    @Transient

    public Icon getDisabledIcon() {

        if (!disabledIconSet && disabledIcon == null && defaultIcon != null) {

            disabledIcon = UIManager.getLookAndFeel().getDisabledIcon(this, defaultIcon);

            if (disabledIcon != null) {

                firePropertyChange("disabledIcon", null, disabledIcon);

            }

        }

        return disabledIcon;

    }

    /**

     * Set the icon to be displayed if this JLabel is "disabled"

     * (JLabel.setEnabled(false)).

     * <p>

     * The default value of this property is null.

     *

     * @param disabledIcon the Icon to display when the component is disabled

     * @see #getDisabledIcon

     * @see #setEnabled

     * @beaninfo

     *        bound: true

     *    attribute: visualUpdate true

     *  description: The icon to display if the label is disabled.

     */

    public void setDisabledIcon(Icon disabledIcon) {

        Icon oldValue = this.disabledIcon;

        this.disabledIcon = disabledIcon;

        disabledIconSet = (disabledIcon != null);

        firePropertyChange("disabledIcon", oldValue, disabledIcon);

        if (disabledIcon != oldValue) {

            if (disabledIcon == null || oldValue == null ||

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

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

                revalidate();

            }

            if (!isEnabled()) {

                repaint();

            }

        }

    }

    /**

     * Specify a keycode that indicates a mnemonic key.

     * This property is used when the label is part of a larger component.

     * If the labelFor property of the label is not null, the label will

     * call the requestFocus method of the component specified by the

     * labelFor property when the mnemonic is activated.

     *

     * @see #getLabelFor

     * @see #setLabelFor

     * @beaninfo

     *        bound: true

     *    attribute: visualUpdate true

     *  description: The mnemonic keycode.

     */

    public void setDisplayedMnemonic(int key) {

        int oldKey = mnemonic;

        mnemonic = key;

        firePropertyChange("displayedMnemonic", oldKey, mnemonic);

        setDisplayedMnemonicIndex(

            SwingUtilities.findDisplayedMnemonicIndex(getText(), mnemonic));

        if (key != oldKey) {

            revalidate();

            repaint();

        }

    }

    /**

     * Specifies the displayedMnemonic as a char value.

     *

     * @param aChar  a char specifying the mnemonic to display

     * @see #setDisplayedMnemonic(int)

     */

    public void setDisplayedMnemonic(char aChar) {

        int vk = java.awt.event.KeyEvent.getExtendedKeyCodeForChar(aChar);

        if (vk != java.awt.event.KeyEvent.VK_UNDEFINED) {

            setDisplayedMnemonic(vk);

        }

    }

    /**

     * Return the keycode that indicates a mnemonic key.

     * This property is used when the label is part of a larger component.

     * If the labelFor property of the label is not null, the label will

     * call the requestFocus method of the component specified by the

     * labelFor property when the mnemonic is activated.

     *

     * @return int value for the mnemonic key

     *

     * @see #getLabelFor

     * @see #setLabelFor

     */

    public int getDisplayedMnemonic() {