textattribute.java

JAVA基本类源代码,大家可以学习学习!

/*
 * @(#)TextAttribute.java	1.44 03/01/23
 *
 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

/*
 * (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</code> class defines attribute keys and
 * attribute values used for text rendering. 
 * <p>
 * <code>TextAttribute</code> instances are used as attribute keys to
 * identify attributes in 
 * {@link java.text.AttributedCharacterIterator AttributedCharacterIterator}, 
 * {@link java.awt.Font Font}, and other classes handling text 
 * attributes. Other constants defined in this class are used 
 * as attribute values.
 * <p>
 * For each text attribute, the documentation describes:
 * <UL>
 *   <LI>the type of their values,
 *   <LI>the valid values if there are limitations
 *   <LI>relevant constants
 *   <LI>the default effect if the attribute is absent (or has a
 *	<code>null</code> value).
 *   <LI>a description of the effect.
 *   <LI>the fallback behavior if the exact attribute requested is not 
 *	available.
 * </UL>
 * <p>
 * <H4>Types of Values</H4>
 * <UL>
 *   <LI>The values of attributes must always be immutable.
 *   <LI>Where a list of limitations is given, any value outside of that
 *   set is reserved for future use, and ignored at present.
 *   <LI>If the value is <code>null</code> or not of the proper type
 *	then it has the default effect. The effect of a particular value
 *	can be interpolated, especially in the case of multiple master
 *	fonts. This interpolation is done based on the nearest defined
 * 	constants above and below the request:<BR>
 *      <BLOCKQUOTE><TT>
 *	interpolation = (request - below)/(above - below);
 *	</TT></BLOCKQUOTE>
 * </UL>
 * <p>
 * <H4>Interpolation</H4>
 * <UL>
 *   <LI>Fonts should interpolate values in certain circumstances. For example,
 *   when the WEIGHT value is 2.13. If the nearest surrounding values
 *   in the font are WEIGHT_BOLD = 2.0 and WEIGHT_HEAVY = 2.25 then font would
 *   then interpret the WEIGHT request as being 52% of the way between what
 *   it considers BOLD and what it considers HEAVY. If the nearest surrounding
 *   values are WEIGHT_SEMIBOLD = 1.25 and WEIGHT_ULTRABOLD = 2.75 then the
 *   WEIGHT request is interpreted as being 58.67% of the way between SEMIBOLD
 *   and ULTRABOLD.
 *   <LI>Where a font does not have enough capability to handle a given 
 *   request, such as superscript, then it should simulate it to the best of 
 *   its ability.  To determine if simulation is being performed, the client
 *   should query the font to see what actual attributes were used.
 * </UL>
 * 
 * @see java.text.AttributedCharacterIterator
 * @see java.awt.Font 
 */
public final class TextAttribute extends Attribute {

    // table of all instances in this class, used by readResolve
    private static final Map instanceMap = new HashMap(29);

    /**
     * Constructs a <code>TextAttribute</code> with the specified name.
     * @param name the attribute name to assign to this 
     * <code>TextAttribute</code>
     */
    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 = (TextAttribute) 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 unlocalized font family name.
     *
     * <P><TABLE BORDER="0" CELLSPACING="0" CELLPADDING="1" 
     *     SUMMARY="Key, Value, Constants, Default, and Description 
     *     for TextAttribute FAMILY">
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Key</TH>
     * <TD VALIGN="TOP">FAMILY</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Value</TH>
     * <TD VALIGN="TOP">String</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Constants</TH>
     * <TD VALIGN="TOP">&quot;Serif&quot;, &quot;SansSerif&quot;</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Default</TH>
     * <TD VALIGN="TOP">Host default;</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Description</TH>
     * <TD VALIGN="TOP">The name of the font family. If the family name is not 
     * found, the default font is used. The name should not be the full
     * font name or specify other attributes (such as the name
     * &quot;Helvetica Bold&quot;). Such names might result in the default
     * font if the name does not match a known
     * family name.</TD></TR>
     * </TABLE>
     */
    public static final TextAttribute FAMILY = new TextAttribute("family");

    /**
     * Attribute key for the weight of a font.
     *
     * <P><TABLE BORDER="0" CELLSPACING="0" CELLPADDING="1"
     *     SUMMARY="Key, Value, Constants, Description, Default, 
     *     and Fallback for TextAttribute WEIGHT">
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Key</TH>
     * <TD VALIGN="TOP">WEIGHT</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Value</TH>
     * <TD VALIGN="TOP">Float</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Constants</TH>
     * <TD VALIGN="TOP">
     * WEIGHT_EXTRA_LIGHT = 0.5,<BR>
     * WEIGHT_LIGHT = 0.75,<BR>
     * WEIGHT_DEMILIGHT = 0.875,<BR>
     * WEIGHT_REGULAR = 1.0,<BR>
     * WEIGHT_SEMIBOLD = 1.25,<BR>
     * WEIGHT_MEDIUM = 1.5,<BR>
     * WEIGHT_DEMIBOLD = 1.75,<BR>
     * WEIGHT_BOLD = 2.0,<BR>
     * WEIGHT_HEAVY = 2.25,<BR>
     * WEIGHT_EXTRABOLD = 2.5,<BR>
     * WEIGHT_ULTRABOLD = 2.75</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Default</TH>
     * <TD VALIGN="TOP">WEIGHT_REGULAR</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Description</TH>
     * <TD VALIGN="TOP">The value is roughly the ratio of the stem width to 
     * that of the regular weight. If the font has a different value for
     * specific constants, then the value is interpolated as described in
     * the class description.</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Fallback</TH>
     * <TD VALIGN="TOP">Currently none. However, in the future, shape 
     * manipulations might be<BR> available to simulate weight variations
     * for fonts that don't have them.</TD></TR>
     * </TABLE>
     * <BR>
     */
    public static final TextAttribute WEIGHT = new TextAttribute("weight");

    /**
     * The lightest predefined weight.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_EXTRA_LIGHT = new Float(0.5f);

    /**
     * The standard light weight.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_LIGHT = new Float(0.75f);

    /**
     * An intermediate weight between LIGHT and STANDARD.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_DEMILIGHT = new Float(0.875f);

    /**
     * The standard weight. This weight is used if WEIGHT is unspecified.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_REGULAR = new Float(1.0f);

    /**
     * A moderately heavier weight than REGULAR.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_SEMIBOLD = new Float(1.25f);

    /**
     * An intermediate weight between the REGULAR and BOLD weights.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_MEDIUM = new Float(1.5f);

    /**
     * A moderately lighter weight than BOLD.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_DEMIBOLD = new Float(1.75f);

    /**
     * The standard bold weight.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_BOLD = new Float(2.0f);

    /**
     * A moderately heavier weight than BOLD.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_HEAVY = new Float(2.25f);

    /**
     * An extra heavy weight.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_EXTRABOLD = new Float(2.5f);

    /**
     * The heaviest predefined weight.
     * @see #WEIGHT
     */
    public static final Float WEIGHT_ULTRABOLD = new Float(2.75f);

    /**
     * Attribute key for the width of a font.
     *
     * <P><TABLE BORDER="0" CELLSPACING="0" CELLPADDING="1"
     *     SUMMARY="Key, Value, Constants, Description, Default, 
     *     and Fallback for TextAttribute WIDTH">
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Key</TH>
     * <TD VALIGN="TOP">WIDTH</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Value</TH>
     * <TD VALIGN="TOP">Float</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Constants</TH>
     * <TD VALIGN="TOP">WIDTH_CONDENSED = 0.75,<BR>
     * WIDTH_SEMI_CONDENSED = 0.875,<BR>
     * WIDTH_REGULAR = 1.0,<BR>
     * WIDTH_SEMI_EXTENDED = 1.25,<BR>
     * WIDTH_EXTENDED = 1.5</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Default</TH>
     * <TD VALIGN="TOP">WIDTH_REGULAR</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Description</TH>
     * <TD VALIGN="TOP">The value is roughly the ratio of the advance width 
     * to that of the regular width. If the font has a different value for
     * specific constants, then the value is interpolated as described in
     * the class description.</TD></TR>
     * <TR>
     * <TH VALIGN="TOP" ALIGN="RIGHT"><P ALIGN=RIGHT>Fallback</TH>
     * <TD VALIGN="TOP">If a Narrow font is available and matches, use that. 
     * Otherwise scale with a transform based on the value.</TD></TR>
     * </TABLE>