/*

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

 */

/*

 * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved

 * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved

 *

 * The original version of this source code and documentation is

 * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary

 * of IBM. These materials are provided under terms of a License

 * Agreement between Taligent and Sun. This technology is protected

 * by multiple US and International patents.

 *

 * This notice and attribution to Taligent may not be removed.

 * Taligent is a registered trademark of Taligent, Inc.

 *

 */

package java.awt.font;

import java.io.InvalidObjectException;

import java.text.AttributedCharacterIterator.Attribute;

import java.util.Map;

import java.util.HashMap;

/**

 * The {@code TextAttribute} class defines attribute keys and

 * attribute values used for text rendering.

 * <p>

 * {@code TextAttribute} instances are used as attribute keys to

 * identify attributes in

 * {@link java.awt.Font Font},

 * {@link java.awt.font.TextLayout TextLayout},

 * {@link java.text.AttributedCharacterIterator AttributedCharacterIterator},

 * and other classes handling text attributes. Other constants defined

 * in this class can be used as attribute values.

 * <p>

 * For each text attribute, the documentation provides:

 * <UL>

 *   <LI>the type of its value,

 *   <LI>the relevant predefined constants, if any

 *   <LI>the default effect if the attribute is absent

 *   <LI>the valid values if there are limitations

 *   <LI>a description of the effect.

 * </UL>

 *

 * <H3>Values</H3>

 * <UL>

 *   <LI>The values of attributes must always be immutable.

 *   <LI>Where value limitations are given, any value outside of that

 *   set is reserved for future use; the value will be treated as

 *   the default.

 *   <LI>The value {@code null} is treated the same as the

 *   default value and results in the default behavior.

 *   <li>If the value is not of the proper type, the attribute

 *   will be ignored.

 *   <li>The identity of the value does not matter, only the actual

 *   value.  For example, {@code TextAttribute.WEIGHT_BOLD} and

 *   {@code Float.valueOf(2.0f)}

 *   indicate the same {@code WEIGHT}.

 *   <li>Attribute values of type {@code Number} (used for

 *   {@code WEIGHT}, {@code WIDTH}, {@code POSTURE},

 *   {@code SIZE}, {@code JUSTIFICATION}, and

 *   {@code TRACKING}) can vary along their natural range and are

 *   not restricted to the predefined constants.

 *   {@code Number.floatValue()} is used to get the actual value

 *   from the {@code Number}.

 *   <li>The values for {@code WEIGHT}, {@code WIDTH}, and

 *   {@code POSTURE} are interpolated by the system, which

 *   can select the 'nearest available' font or use other techniques to

 *   approximate the user's request.

 *

 * </UL>

 *

 * <h4>Summary of attributes</h4>

 *

 * <table style="width:95%;margin: 0px auto" class="striped">

 * <caption>Key, value type, principal constants, and default value behavior of

 * all TextAttributes</caption>

 * <thead>

 *   <tr>

 *     <th scope="col">Key

 *     <th scope="col">Value Type

 *     <th scope="col">Principal Constants

 *     <th scope="col">Default Value

 * </thead>

 * <tbody>

 *   <tr>

 *     <th scope="row">{@link #FAMILY}

 *     <td>String

 *     <td>See Font {@link java.awt.Font#DIALOG DIALOG},

 *     {@link java.awt.Font#DIALOG_INPUT DIALOG_INPUT},

 *     <br>

 *     {@link java.awt.Font#SERIF SERIF},

 *     {@link java.awt.Font#SANS_SERIF SANS_SERIF}, and

 *     {@link java.awt.Font#MONOSPACED MONOSPACED}.

 *     <td>"Default" (use platform default)

 *   <tr>

 *     <th scope="row">{@link #WEIGHT}

 *     <td>Number

 *     <td>WEIGHT_REGULAR, WEIGHT_BOLD

 *     <td>WEIGHT_REGULAR

 *   <tr>

 *     <th scope="row">{@link #WIDTH}

 *     <td>Number

 *     <td>WIDTH_CONDENSED, WIDTH_REGULAR,<br>WIDTH_EXTENDED

 *     <td>WIDTH_REGULAR

 *   <tr>

 *     <th scope="row">{@link #POSTURE}

 *     <td>Number

 *     <td>POSTURE_REGULAR, POSTURE_OBLIQUE

 *     <td>POSTURE_REGULAR

 *   <tr>

 *     <th scope="row">{@link #SIZE}

 *     <td>Number

 *     <td>none

 *     <td>12.0

 *   <tr>

 *     <th scope="row">{@link #TRANSFORM}

 *     <td>{@link TransformAttribute}

 *     <td>See TransformAttribute {@link TransformAttribute#IDENTITY IDENTITY}

 *     <td>TransformAttribute.IDENTITY

 *   <tr>

 *     <th scope="row">{@link #SUPERSCRIPT}

 *     <td>Integer

 *     <td>SUPERSCRIPT_SUPER, SUPERSCRIPT_SUB

 *     <td>0 (use the standard glyphs and metrics)

 *   <tr>

 *     <th scope="row">{@link #FONT}

 *     <td>{@link java.awt.Font}

 *     <td>none

 *     <td>null (do not override font resolution)

 *   <tr>

 *     <th scope="row">{@link #CHAR_REPLACEMENT}

 *     <td>{@link GraphicAttribute}

 *     <td>none

 *     <td>null (draw text using font glyphs)

 *   <tr>

 *     <th scope="row">{@link #FOREGROUND}

 *     <td>{@link java.awt.Paint}

 *     <td>none

 *     <td>null (use current graphics paint)

 *   <tr>

 *     <th scope="row">{@link #BACKGROUND}

 *     <td>{@link java.awt.Paint}

 *     <td>none

 *     <td>null (do not render background)

 *   <tr>

 *     <th scope="row">{@link #UNDERLINE}

 *     <td>Integer

 *     <td>UNDERLINE_ON

 *     <td>-1 (do not render underline)

 *   <tr>

 *     <th scope="row">{@link #STRIKETHROUGH}

 *     <td>Boolean

 *     <td>STRIKETHROUGH_ON

 *     <td>false (do not render strikethrough)

 *   <tr>

 *     <th scope="row">{@link #RUN_DIRECTION}

 *     <td>Boolean

 *     <td>RUN_DIRECTION_LTR<br>RUN_DIRECTION_RTL

 *     <td>null (use {@link java.text.Bidi} standard default)

 *   <tr>

 *     <th scope="row">{@link #BIDI_EMBEDDING}

 *     <td>Integer

 *     <td>none

 *     <td>0 (use base line direction)

 *   <tr>

 *     <th scope="row">{@link #JUSTIFICATION}

 *     <td>Number

 *     <td>JUSTIFICATION_FULL

 *     <td>JUSTIFICATION_FULL

 *   <tr>

 *     <th scope="row">{@link #INPUT_METHOD_HIGHLIGHT}

 *     <td>{@link java.awt.im.InputMethodHighlight},

 *     <br>

 *     {@link java.text.Annotation}

 *     <td>(see class)

 *     <td>null (do not apply input highlighting)

 *   <tr>

 *     <th scope="row">{@link #INPUT_METHOD_UNDERLINE}

 *     <td>Integer

 *     <td>UNDERLINE_LOW_ONE_PIXEL,<br>UNDERLINE_LOW_TWO_PIXEL

 *     <td>-1 (do not render underline)

 *   <tr>

 *     <th scope="row">{@link #SWAP_COLORS}

 *     <td>Boolean

 *     <td>SWAP_COLORS_ON

 *     <td>false (do not swap colors)

 *   <tr>

 *     <th scope="row">{@link #NUMERIC_SHAPING}

 *     <td>{@link java.awt.font.NumericShaper}

 *     <td>none

 *     <td>null (do not shape digits)

 *   <tr>

 *     <th scope="row">{@link #KERNING}

 *     <td>Integer

 *     <td>KERNING_ON

 *     <td>0 (do not request kerning)

 *   <tr>

 *     <th scope="row">{@link #LIGATURES}

 *     <td>Integer

 *     <td>LIGATURES_ON

 *     <td>0 (do not form optional ligatures)

 *   <tr>

 *     <th scope="row">{@link #TRACKING}

 *     <td>Number

 *     <td>TRACKING_LOOSE, TRACKING_TIGHT

 *     <td>0 (do not add tracking)

 *   </tr>

 * </tbody>

 * </table>

 *

 * @see java.awt.Font

 * @see java.awt.font.TextLayout

 * @see java.text.AttributedCharacterIterator

 */

public final class TextAttribute extends Attribute {

    // table of all instances in this class, used by readResolve

    private static final Map<String, TextAttribute>

            instanceMap = new HashMap<String, TextAttribute>(29);

    // For access from java.text.Bidi

    static {

        if (SharedSecrets.getJavaAWTFontAccess() == null) {

            SharedSecrets.setJavaAWTFontAccess(new JavaAWTFontAccessImpl());

        }

    }

    /**

     * Constructs a {@code TextAttribute} with the specified name.

     * @param name the attribute name to assign to this

     * {@code TextAttribute}

     */

    protected TextAttribute(String name) {

        super(name);

        if (this.getClass() == TextAttribute.class) {

            instanceMap.put(name, this);

        }

    }

    /**

     * Resolves instances being deserialized to the predefined constants.

     */

    protected Object readResolve() throws InvalidObjectException {

        if (this.getClass() != TextAttribute.class) {

            throw new InvalidObjectException(

                "subclass didn't correctly implement readResolve");

        }

        TextAttribute instance = instanceMap.get(getName());

        if (instance != null) {

            return instance;

        } else {

            throw new InvalidObjectException("unknown attribute name");

        }

    }

    // Serialization compatibility with Java 2 platform v1.2.

    // 1.2 will throw an InvalidObjectException if ever asked to

    // deserialize INPUT_METHOD_UNDERLINE.

    // This shouldn't happen in real life.

    static final long serialVersionUID = 7744112784117861702L;

    //

    // For use with Font.

    //

    /**

     * Attribute key for the font name.  Values are instances of

     * <b>{@code String}</b>.  The default value is

     * {@code "Default"}, which causes the platform default font

     * family to be used.

     *

     * <p> The {@code Font} class defines constants for the logical

     * font names

     * {@link java.awt.Font#DIALOG DIALOG},

     * {@link java.awt.Font#DIALOG_INPUT DIALOG_INPUT},

     * {@link java.awt.Font#SANS_SERIF SANS_SERIF},

     * {@link java.awt.Font#SERIF SERIF}, and

     * {@link java.awt.Font#MONOSPACED MONOSPACED}.

     *

     * <p>This defines the value passed as {@code name} to the

     * {@code Font} constructor.  Both logical and physical

     * font names are allowed. If a font with the requested name

     * is not found, the default font is used.

     *

     * <p><em>Note:</em> This attribute is unfortunately misnamed, as

     * it specifies the face name and not just the family.  Thus

     * values such as "Lucida Sans Bold" will select that face if it

     * exists.  Note, though, that if the requested face does not

     * exist, the default will be used with <em>regular</em> weight.

     * The "Bold" in the name is part of the face name, not a separate

     * request that the font's weight be bold.</p>

     */

    public static final TextAttribute FAMILY =

        new TextAttribute("family");

    /**

     * Attribute key for the weight of a font.  Values are instances

     * of <b>{@code Number}</b>.  The default value is

     * {@code WEIGHT_REGULAR}.

     *

     * <p>Several constant values are provided, see {@link

     * #WEIGHT_EXTRA_LIGHT}, {@link #WEIGHT_LIGHT}, {@link

     * #WEIGHT_DEMILIGHT}, {@link #WEIGHT_REGULAR}, {@link

     * #WEIGHT_SEMIBOLD}, {@link #WEIGHT_MEDIUM}, {@link

     * #WEIGHT_DEMIBOLD}, {@link #WEIGHT_BOLD}, {@link #WEIGHT_HEAVY},

     * {@link #WEIGHT_EXTRABOLD}, and {@link #WEIGHT_ULTRABOLD}.  The

     * value {@code WEIGHT_BOLD} corresponds to the

     * style value {@code Font.BOLD} as passed to the

     * {@code Font} constructor.

     *

     * <p>The value is roughly the ratio of the stem width to that of

     * the regular weight.

     *

     * <p>The system can interpolate the provided value.

     */

    public static final TextAttribute WEIGHT =

        new TextAttribute("weight");

    /**

     * The lightest predefined weight.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_EXTRA_LIGHT =

        Float.valueOf(0.5f);

    /**

     * The standard light weight.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_LIGHT =

        Float.valueOf(0.75f);

    /**

     * An intermediate weight between {@code WEIGHT_LIGHT} and

     * {@code WEIGHT_STANDARD}.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_DEMILIGHT =

        Float.valueOf(0.875f);

    /**

     * The standard weight. This is the default value for {@code WEIGHT}.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_REGULAR =

        Float.valueOf(1.0f);

    /**

     * A moderately heavier weight than {@code WEIGHT_REGULAR}.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_SEMIBOLD =

        Float.valueOf(1.25f);

    /**

     * An intermediate weight between {@code WEIGHT_REGULAR} and

     * {@code WEIGHT_BOLD}.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_MEDIUM =

        Float.valueOf(1.5f);

    /**

     * A moderately lighter weight than {@code WEIGHT_BOLD}.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_DEMIBOLD =

        Float.valueOf(1.75f);

    /**

     * The standard bold weight.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_BOLD =

        Float.valueOf(2.0f);

    /**

     * A moderately heavier weight than {@code WEIGHT_BOLD}.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_HEAVY =

        Float.valueOf(2.25f);

    /**

     * An extra heavy weight.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_EXTRABOLD =

        Float.valueOf(2.5f);

    /**

     * The heaviest predefined weight.

     * @see #WEIGHT

     */

    public static final Float WEIGHT_ULTRABOLD =

        Float.valueOf(2.75f);

    /**

     * Attribute key for the width of a font.  Values are instances of

     * <b>{@code Number}</b>.  The default value is

     * {@code WIDTH_REGULAR}.

     *

     * <p>Several constant values are provided, see {@link

     * #WIDTH_CONDENSED}, {@link #WIDTH_SEMI_CONDENSED}, {@link

     * #WIDTH_REGULAR}, {@link #WIDTH_SEMI_EXTENDED}, {@link

     * #WIDTH_EXTENDED}.

     *

     * <p>The value is roughly the ratio of the advance width to that

     * of the regular width.

     *

     * <p>The system can interpolate the provided value.

     */

    public static final TextAttribute WIDTH =

        new TextAttribute("width");

    /**

     * The most condensed predefined width.

     * @see #WIDTH

     */

    public static final Float WIDTH_CONDENSED =

        Float.valueOf(0.75f);

    /**

     * A moderately condensed width.

     * @see #WIDTH

     */

    public static final Float WIDTH_SEMI_CONDENSED =

        Float.valueOf(0.875f);

    /**

     * The standard width. This is the default value for

     * {@code WIDTH}.

     * @see #WIDTH

     */

    public static final Float WIDTH_REGULAR =

        Float.valueOf(1.0f);

    /**

     * A moderately extended width.

     * @see #WIDTH

     */

    public static final Float WIDTH_SEMI_EXTENDED =

        Float.valueOf(1.25f);

    /**

     * The most extended predefined width.

     * @see #WIDTH

     */

    public static final Float WIDTH_EXTENDED =

        Float.valueOf(1.5f);

    /**

     * Attribute key for the posture of a font.  Values are instances

     * of <b>{@code Number}</b>. The default value is

     * {@code POSTURE_REGULAR}.

     *

     * <p>Two constant values are provided, {@link #POSTURE_REGULAR}

     * and {@link #POSTURE_OBLIQUE}. The value

     * {@code POSTURE_OBLIQUE} corresponds to the style value

     * {@code Font.ITALIC} as passed to the {@code Font}

     * constructor.

     *

     * <p>The value is roughly the slope of the stems of the font,

     * expressed as the run over the rise.  Positive values lean right.

     *

     * <p>The system can interpolate the provided value.

     *

     * <p>This will affect the font's italic angle as returned by

     * {@code Font.getItalicAngle}.

     *

     * @see java.awt.Font#getItalicAngle()

     */

    public static final TextAttribute POSTURE =

        new TextAttribute("posture");

    /**

     * The standard posture, upright.  This is the default value for

     * {@code POSTURE}.

     * @see #POSTURE

     */

    public static final Float POSTURE_REGULAR =

        Float.valueOf(0.0f);