1 /*
   2  * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved
  28  * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved
  29  *
  30  * The original version of this source code and documentation is
  31  * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary
  32  * of IBM. These materials are provided under terms of a License
  33  * Agreement between Taligent and Sun. This technology is protected
  34  * by multiple US and International patents.
  35  *
  36  * This notice and attribution to Taligent may not be removed.
  37  * Taligent is a registered trademark of Taligent, Inc.
  38  *
  39  */
  40 
  41 package java.awt.font;
  42 
  43 import java.io.InvalidObjectException;
  44 import java.text.AttributedCharacterIterator.Attribute;
  45 import java.util.Map;
  46 import java.util.HashMap;
  47 import jdk.internal.access.SharedSecrets;
  48 
  49 /**
  50  * The {@code TextAttribute} class defines attribute keys and
  51  * attribute values used for text rendering.
  52  * <p>
  53  * {@code TextAttribute} instances are used as attribute keys to
  54  * identify attributes in
  55  * {@link java.awt.Font Font},
  56  * {@link java.awt.font.TextLayout TextLayout},
  57  * {@link java.text.AttributedCharacterIterator AttributedCharacterIterator},
  58  * and other classes handling text attributes. Other constants defined
  59  * in this class can be used as attribute values.
  60  * <p>
  61  * For each text attribute, the documentation provides:
  62  * <UL>
  63  *   <LI>the type of its value,
  64  *   <LI>the relevant predefined constants, if any
  65  *   <LI>the default effect if the attribute is absent
  66  *   <LI>the valid values if there are limitations
  67  *   <LI>a description of the effect.
  68  * </UL>
  69  *
  70  * <H3>Values</H3>
  71  * <UL>
  72  *   <LI>The values of attributes must always be immutable.
  73  *   <LI>Where value limitations are given, any value outside of that
  74  *   set is reserved for future use; the value will be treated as
  75  *   the default.
  76  *   <LI>The value {@code null} is treated the same as the
  77  *   default value and results in the default behavior.
  78  *   <li>If the value is not of the proper type, the attribute
  79  *   will be ignored.
  80  *   <li>The identity of the value does not matter, only the actual
  81  *   value.  For example, {@code TextAttribute.WEIGHT_BOLD} and
  82  *   {@code Float.valueOf(2.0f)}
  83  *   indicate the same {@code WEIGHT}.
  84  *   <li>Attribute values of type {@code Number} (used for
  85  *   {@code WEIGHT}, {@code WIDTH}, {@code POSTURE},
  86  *   {@code SIZE}, {@code JUSTIFICATION}, and
  87  *   {@code TRACKING}) can vary along their natural range and are
  88  *   not restricted to the predefined constants.
  89  *   {@code Number.floatValue()} is used to get the actual value
  90  *   from the {@code Number}.
  91  *   <li>The values for {@code WEIGHT}, {@code WIDTH}, and
  92  *   {@code POSTURE} are interpolated by the system, which
  93  *   can select the 'nearest available' font or use other techniques to
  94  *   approximate the user's request.
  95  *
  96  * </UL>
  97  *
  98  * <h4>Summary of attributes</h4>
  99  *
 100  * <table style="width:95%;margin: 0px auto" class="striped">
 101  * <caption>Key, value type, principal constants, and default value behavior of
 102  * all TextAttributes</caption>
 103  * <thead>
 104  *   <tr>
 105  *     <th scope="col">Key
 106  *     <th scope="col">Value Type
 107  *     <th scope="col">Principal Constants
 108  *     <th scope="col">Default Value
 109  * </thead>
 110  * <tbody>
 111  *   <tr>
 112  *     <th scope="row">{@link #FAMILY}
 113  *     <td>String
 114  *     <td>See Font {@link java.awt.Font#DIALOG DIALOG},
 115  *     {@link java.awt.Font#DIALOG_INPUT DIALOG_INPUT},
 116  *     <br>
 117  *     {@link java.awt.Font#SERIF SERIF},
 118  *     {@link java.awt.Font#SANS_SERIF SANS_SERIF}, and
 119  *     {@link java.awt.Font#MONOSPACED MONOSPACED}.
 120  *     <td>"Default" (use platform default)
 121  *   <tr>
 122  *     <th scope="row">{@link #WEIGHT}
 123  *     <td>Number
 124  *     <td>WEIGHT_REGULAR, WEIGHT_BOLD
 125  *     <td>WEIGHT_REGULAR
 126  *   <tr>
 127  *     <th scope="row">{@link #WIDTH}
 128  *     <td>Number
 129  *     <td>WIDTH_CONDENSED, WIDTH_REGULAR,<br>WIDTH_EXTENDED
 130  *     <td>WIDTH_REGULAR
 131  *   <tr>
 132  *     <th scope="row">{@link #POSTURE}
 133  *     <td>Number
 134  *     <td>POSTURE_REGULAR, POSTURE_OBLIQUE
 135  *     <td>POSTURE_REGULAR
 136  *   <tr>
 137  *     <th scope="row">{@link #SIZE}
 138  *     <td>Number
 139  *     <td>none
 140  *     <td>12.0
 141  *   <tr>
 142  *     <th scope="row">{@link #TRANSFORM}
 143  *     <td>{@link TransformAttribute}
 144  *     <td>See TransformAttribute {@link TransformAttribute#IDENTITY IDENTITY}
 145  *     <td>TransformAttribute.IDENTITY
 146  *   <tr>
 147  *     <th scope="row">{@link #SUPERSCRIPT}
 148  *     <td>Integer
 149  *     <td>SUPERSCRIPT_SUPER, SUPERSCRIPT_SUB
 150  *     <td>0 (use the standard glyphs and metrics)
 151  *   <tr>
 152  *     <th scope="row">{@link #FONT}
 153  *     <td>{@link java.awt.Font}
 154  *     <td>none
 155  *     <td>null (do not override font resolution)
 156  *   <tr>
 157  *     <th scope="row">{@link #CHAR_REPLACEMENT}
 158  *     <td>{@link GraphicAttribute}
 159  *     <td>none
 160  *     <td>null (draw text using font glyphs)
 161  *   <tr>
 162  *     <th scope="row">{@link #FOREGROUND}
 163  *     <td>{@link java.awt.Paint}
 164  *     <td>none
 165  *     <td>null (use current graphics paint)
 166  *   <tr>
 167  *     <th scope="row">{@link #BACKGROUND}
 168  *     <td>{@link java.awt.Paint}
 169  *     <td>none
 170  *     <td>null (do not render background)
 171  *   <tr>
 172  *     <th scope="row">{@link #UNDERLINE}
 173  *     <td>Integer
 174  *     <td>UNDERLINE_ON
 175  *     <td>-1 (do not render underline)
 176  *   <tr>
 177  *     <th scope="row">{@link #STRIKETHROUGH}
 178  *     <td>Boolean
 179  *     <td>STRIKETHROUGH_ON
 180  *     <td>false (do not render strikethrough)
 181  *   <tr>
 182  *     <th scope="row">{@link #RUN_DIRECTION}
 183  *     <td>Boolean
 184  *     <td>RUN_DIRECTION_LTR<br>RUN_DIRECTION_RTL
 185  *     <td>null (use {@link java.text.Bidi} standard default)
 186  *   <tr>
 187  *     <th scope="row">{@link #BIDI_EMBEDDING}
 188  *     <td>Integer
 189  *     <td>none
 190  *     <td>0 (use base line direction)
 191  *   <tr>
 192  *     <th scope="row">{@link #JUSTIFICATION}
 193  *     <td>Number
 194  *     <td>JUSTIFICATION_FULL
 195  *     <td>JUSTIFICATION_FULL
 196  *   <tr>
 197  *     <th scope="row">{@link #INPUT_METHOD_HIGHLIGHT}
 198  *     <td>{@link java.awt.im.InputMethodHighlight},
 199  *     <br>
 200  *     {@link java.text.Annotation}
 201  *     <td>(see class)
 202  *     <td>null (do not apply input highlighting)
 203  *   <tr>
 204  *     <th scope="row">{@link #INPUT_METHOD_UNDERLINE}
 205  *     <td>Integer
 206  *     <td>UNDERLINE_LOW_ONE_PIXEL,<br>UNDERLINE_LOW_TWO_PIXEL
 207  *     <td>-1 (do not render underline)
 208  *   <tr>
 209  *     <th scope="row">{@link #SWAP_COLORS}
 210  *     <td>Boolean
 211  *     <td>SWAP_COLORS_ON
 212  *     <td>false (do not swap colors)
 213  *   <tr>
 214  *     <th scope="row">{@link #NUMERIC_SHAPING}
 215  *     <td>{@link java.awt.font.NumericShaper}
 216  *     <td>none
 217  *     <td>null (do not shape digits)
 218  *   <tr>
 219  *     <th scope="row">{@link #KERNING}
 220  *     <td>Integer
 221  *     <td>KERNING_ON
 222  *     <td>0 (do not request kerning)
 223  *   <tr>
 224  *     <th scope="row">{@link #LIGATURES}
 225  *     <td>Integer
 226  *     <td>LIGATURES_ON
 227  *     <td>0 (do not form optional ligatures)
 228  *   <tr>
 229  *     <th scope="row">{@link #TRACKING}
 230  *     <td>Number
 231  *     <td>TRACKING_LOOSE, TRACKING_TIGHT
 232  *     <td>0 (do not add tracking)
 233  *   </tr>
 234  * </tbody>
 235  * </table>
 236  *
 237  * @see java.awt.Font
 238  * @see java.awt.font.TextLayout
 239  * @see java.text.AttributedCharacterIterator
 240  */
 241 public final class TextAttribute extends Attribute {
 242 
 243     // table of all instances in this class, used by readResolve
 244     private static final Map<String, TextAttribute>
 245             instanceMap = new HashMap<String, TextAttribute>(29);
 246 
 247     // For access from java.text.Bidi
 248     static {
 249         if (SharedSecrets.getJavaAWTFontAccess() == null) {
 250             SharedSecrets.setJavaAWTFontAccess(new JavaAWTFontAccessImpl());
 251         }
 252     }
 253 
 254     /**
 255      * Constructs a {@code TextAttribute} with the specified name.
 256      * @param name the attribute name to assign to this
 257      * {@code TextAttribute}
 258      */
 259     protected TextAttribute(String name) {
 260         super(name);
 261         if (this.getClass() == TextAttribute.class) {
 262             instanceMap.put(name, this);
 263         }
 264     }
 265 
 266     /**
 267      * Resolves instances being deserialized to the predefined constants.
 268      */
 269     protected Object readResolve() throws InvalidObjectException {
 270         if (this.getClass() != TextAttribute.class) {
 271             throw new InvalidObjectException(
 272                 "subclass didn't correctly implement readResolve");
 273         }
 274 
 275         TextAttribute instance = instanceMap.get(getName());
 276         if (instance != null) {
 277             return instance;
 278         } else {
 279             throw new InvalidObjectException("unknown attribute name");
 280         }
 281     }
 282 
 283     // Serialization compatibility with Java 2 platform v1.2.
 284     // 1.2 will throw an InvalidObjectException if ever asked to
 285     // deserialize INPUT_METHOD_UNDERLINE.
 286     // This shouldn't happen in real life.
 287     static final long serialVersionUID = 7744112784117861702L;
 288 
 289     //
 290     // For use with Font.
 291     //
 292 
 293     /**
 294      * Attribute key for the font name.  Values are instances of
 295      * <b>{@code String}</b>.  The default value is
 296      * {@code "Default"}, which causes the platform default font
 297      * family to be used.
 298      *
 299      * <p> The {@code Font} class defines constants for the logical
 300      * font names
 301      * {@link java.awt.Font#DIALOG DIALOG},
 302      * {@link java.awt.Font#DIALOG_INPUT DIALOG_INPUT},
 303      * {@link java.awt.Font#SANS_SERIF SANS_SERIF},
 304      * {@link java.awt.Font#SERIF SERIF}, and
 305      * {@link java.awt.Font#MONOSPACED MONOSPACED}.
 306      *
 307      * <p>This defines the value passed as {@code name} to the
 308      * {@code Font} constructor.  Both logical and physical
 309      * font names are allowed. If a font with the requested name
 310      * is not found, the default font is used.
 311      *
 312      * <p><em>Note:</em> This attribute is unfortunately misnamed, as
 313      * it specifies the face name and not just the family.  Thus
 314      * values such as "Lucida Sans Bold" will select that face if it
 315      * exists.  Note, though, that if the requested face does not
 316      * exist, the default will be used with <em>regular</em> weight.
 317      * The "Bold" in the name is part of the face name, not a separate
 318      * request that the font's weight be bold.</p>
 319      */
 320     public static final TextAttribute FAMILY =
 321         new TextAttribute("family");
 322 
 323     /**
 324      * Attribute key for the weight of a font.  Values are instances
 325      * of <b>{@code Number}</b>.  The default value is
 326      * {@code WEIGHT_REGULAR}.
 327      *
 328      * <p>Several constant values are provided, see {@link
 329      * #WEIGHT_EXTRA_LIGHT}, {@link #WEIGHT_LIGHT}, {@link
 330      * #WEIGHT_DEMILIGHT}, {@link #WEIGHT_REGULAR}, {@link
 331      * #WEIGHT_SEMIBOLD}, {@link #WEIGHT_MEDIUM}, {@link
 332      * #WEIGHT_DEMIBOLD}, {@link #WEIGHT_BOLD}, {@link #WEIGHT_HEAVY},
 333      * {@link #WEIGHT_EXTRABOLD}, and {@link #WEIGHT_ULTRABOLD}.  The
 334      * value {@code WEIGHT_BOLD} corresponds to the
 335      * style value {@code Font.BOLD} as passed to the
 336      * {@code Font} constructor.
 337      *
 338      * <p>The value is roughly the ratio of the stem width to that of
 339      * the regular weight.
 340      *
 341      * <p>The system can interpolate the provided value.
 342      */
 343     public static final TextAttribute WEIGHT =
 344         new TextAttribute("weight");
 345 
 346     /**
 347      * The lightest predefined weight.
 348      * @see #WEIGHT
 349      */
 350     public static final Float WEIGHT_EXTRA_LIGHT =
 351         Float.valueOf(0.5f);
 352 
 353     /**
 354      * The standard light weight.
 355      * @see #WEIGHT
 356      */
 357     public static final Float WEIGHT_LIGHT =
 358         Float.valueOf(0.75f);
 359 
 360     /**
 361      * An intermediate weight between {@code WEIGHT_LIGHT} and
 362      * {@code WEIGHT_STANDARD}.
 363      * @see #WEIGHT
 364      */
 365     public static final Float WEIGHT_DEMILIGHT =
 366         Float.valueOf(0.875f);
 367 
 368     /**
 369      * The standard weight. This is the default value for {@code WEIGHT}.
 370      * @see #WEIGHT
 371      */
 372     public static final Float WEIGHT_REGULAR =
 373         Float.valueOf(1.0f);
 374 
 375     /**
 376      * A moderately heavier weight than {@code WEIGHT_REGULAR}.
 377      * @see #WEIGHT
 378      */
 379     public static final Float WEIGHT_SEMIBOLD =
 380         Float.valueOf(1.25f);
 381 
 382     /**
 383      * An intermediate weight between {@code WEIGHT_REGULAR} and
 384      * {@code WEIGHT_BOLD}.
 385      * @see #WEIGHT
 386      */
 387     public static final Float WEIGHT_MEDIUM =
 388         Float.valueOf(1.5f);
 389 
 390     /**
 391      * A moderately lighter weight than {@code WEIGHT_BOLD}.
 392      * @see #WEIGHT
 393      */
 394     public static final Float WEIGHT_DEMIBOLD =
 395         Float.valueOf(1.75f);
 396 
 397     /**
 398      * The standard bold weight.
 399      * @see #WEIGHT
 400      */
 401     public static final Float WEIGHT_BOLD =
 402         Float.valueOf(2.0f);
 403 
 404     /**
 405      * A moderately heavier weight than {@code WEIGHT_BOLD}.
 406      * @see #WEIGHT
 407      */
 408     public static final Float WEIGHT_HEAVY =
 409         Float.valueOf(2.25f);
 410 
 411     /**
 412      * An extra heavy weight.
 413      * @see #WEIGHT
 414      */
 415     public static final Float WEIGHT_EXTRABOLD =
 416         Float.valueOf(2.5f);
 417 
 418     /**
 419      * The heaviest predefined weight.
 420      * @see #WEIGHT
 421      */
 422     public static final Float WEIGHT_ULTRABOLD =
 423         Float.valueOf(2.75f);
 424 
 425     /**
 426      * Attribute key for the width of a font.  Values are instances of
 427      * <b>{@code Number}</b>.  The default value is
 428      * {@code WIDTH_REGULAR}.
 429      *
 430      * <p>Several constant values are provided, see {@link
 431      * #WIDTH_CONDENSED}, {@link #WIDTH_SEMI_CONDENSED}, {@link
 432      * #WIDTH_REGULAR}, {@link #WIDTH_SEMI_EXTENDED}, {@link
 433      * #WIDTH_EXTENDED}.
 434      *
 435      * <p>The value is roughly the ratio of the advance width to that
 436      * of the regular width.
 437      *
 438      * <p>The system can interpolate the provided value.
 439      */
 440     public static final TextAttribute WIDTH =
 441         new TextAttribute("width");
 442 
 443     /**
 444      * The most condensed predefined width.
 445      * @see #WIDTH
 446      */
 447     public static final Float WIDTH_CONDENSED =
 448         Float.valueOf(0.75f);
 449 
 450     /**
 451      * A moderately condensed width.
 452      * @see #WIDTH
 453      */
 454     public static final Float WIDTH_SEMI_CONDENSED =
 455         Float.valueOf(0.875f);
 456 
 457     /**
 458      * The standard width. This is the default value for
 459      * {@code WIDTH}.
 460      * @see #WIDTH
 461      */
 462     public static final Float WIDTH_REGULAR =
 463         Float.valueOf(1.0f);
 464 
 465     /**
 466      * A moderately extended width.
 467      * @see #WIDTH
 468      */
 469     public static final Float WIDTH_SEMI_EXTENDED =
 470         Float.valueOf(1.25f);
 471 
 472     /**
 473      * The most extended predefined width.
 474      * @see #WIDTH
 475      */
 476     public static final Float WIDTH_EXTENDED =
 477         Float.valueOf(1.5f);
 478 
 479     /**
 480      * Attribute key for the posture of a font.  Values are instances
 481      * of <b>{@code Number}</b>. The default value is
 482      * {@code POSTURE_REGULAR}.
 483      *
 484      * <p>Two constant values are provided, {@link #POSTURE_REGULAR}
 485      * and {@link #POSTURE_OBLIQUE}. The value
 486      * {@code POSTURE_OBLIQUE} corresponds to the style value
 487      * {@code Font.ITALIC} as passed to the {@code Font}
 488      * constructor.
 489      *
 490      * <p>The value is roughly the slope of the stems of the font,
 491      * expressed as the run over the rise.  Positive values lean right.
 492      *
 493      * <p>The system can interpolate the provided value.
 494      *
 495      * <p>This will affect the font's italic angle as returned by
 496      * {@code Font.getItalicAngle}.
 497      *
 498      * @see java.awt.Font#getItalicAngle()
 499      */
 500     public static final TextAttribute POSTURE =
 501         new TextAttribute("posture");
 502 
 503     /**
 504      * The standard posture, upright.  This is the default value for
 505      * {@code POSTURE}.
 506      * @see #POSTURE
 507      */
 508     public static final Float POSTURE_REGULAR =
 509         Float.valueOf(0.0f);
 510 
 511     /**
 512      * The standard italic posture.
 513      * @see #POSTURE
 514      */
 515     public static final Float POSTURE_OBLIQUE =
 516         Float.valueOf(0.20f);
 517 
 518     /**
 519      * Attribute key for the font size.  Values are instances of
 520      * <b>{@code Number}</b>.  The default value is 12pt.
 521      *
 522      * <p>This corresponds to the {@code size} parameter to the
 523      * {@code Font} constructor.
 524      *
 525      * <p>Very large or small sizes will impact rendering performance,
 526      * and the rendering system might not render text at these sizes.
 527      * Negative sizes are illegal and result in the default size.
 528      *
 529      * <p>Note that the appearance and metrics of a 12pt font with a
 530      * 2x transform might be different than that of a 24 point font
 531      * with no transform.
 532      */
 533     public static final TextAttribute SIZE =
 534         new TextAttribute("size");
 535 
 536     /**
 537      * Attribute key for the transform of a font.  Values are
 538      * instances of <b>{@code TransformAttribute}</b>.  The
 539      * default value is {@code TransformAttribute.IDENTITY}.
 540      *
 541      * <p>The {@code TransformAttribute} class defines the
 542      * constant {@link TransformAttribute#IDENTITY IDENTITY}.
 543      *
 544      * <p>This corresponds to the transform passed to
 545      * {@code Font.deriveFont(AffineTransform)}.  Since that
 546      * transform is mutable and {@code TextAttribute} values must
 547      * not be, the {@code TransformAttribute} wrapper class is
 548      * used.
 549      *
 550      * <p>The primary intent is to support scaling and skewing, though
 551      * other effects are possible.</p>
 552      *
 553      * <p>Some transforms will cause the baseline to be rotated and/or
 554      * shifted.  The text and the baseline are transformed together so
 555      * that the text follows the new baseline.  For example, with text
 556      * on a horizontal baseline, the new baseline follows the
 557      * direction of the unit x vector passed through the
 558      * transform. Text metrics are measured against this new baseline.
 559      * So, for example, with other things being equal, text rendered
 560      * with a rotated TRANSFORM and an unrotated TRANSFORM will measure as
 561      * having the same ascent, descent, and advance.</p>
 562      *
 563      * <p>In styled text, the baselines for each such run are aligned
 564      * one after the other to potentially create a non-linear baseline
 565      * for the entire run of text. For more information, see {@link
 566      * TextLayout#getLayoutPath}.</p>
 567      *
 568      * @see TransformAttribute
 569      * @see java.awt.geom.AffineTransform
 570      */
 571      public static final TextAttribute TRANSFORM =
 572         new TextAttribute("transform");
 573 
 574     /**
 575      * Attribute key for superscripting and subscripting.  Values are
 576      * instances of <b>{@code Integer}</b>.  The default value is
 577      * 0, which means that no superscript or subscript is used.
 578      *
 579      * <p>Two constant values are provided, see {@link
 580      * #SUPERSCRIPT_SUPER} and {@link #SUPERSCRIPT_SUB}.  These have
 581      * the values 1 and -1 respectively.  Values of
 582      * greater magnitude define greater levels of superscript or
 583      * subscripting, for example, 2 corresponds to super-superscript,
 584      * 3 to super-super-superscript, and similarly for negative values
 585      * and subscript, up to a level of 7 (or -7).  Values beyond this
 586      * range are reserved; behavior is platform-dependent.
 587      *
 588      * <p>{@code SUPERSCRIPT} can
 589      * impact the ascent and descent of a font.  The ascent
 590      * and descent can never become negative, however.
 591      */
 592     public static final TextAttribute SUPERSCRIPT =
 593         new TextAttribute("superscript");
 594 
 595     /**
 596      * Standard superscript.
 597      * @see #SUPERSCRIPT
 598      */
 599     public static final Integer SUPERSCRIPT_SUPER =
 600         Integer.valueOf(1);
 601 
 602     /**
 603      * Standard subscript.
 604      * @see #SUPERSCRIPT
 605      */
 606     public static final Integer SUPERSCRIPT_SUB =
 607         Integer.valueOf(-1);
 608 
 609     /**
 610      * Attribute key used to provide the font to use to render text.
 611      * Values are instances of {@link java.awt.Font}.  The default
 612      * value is null, indicating that normal resolution of a
 613      * {@code Font} from attributes should be performed.
 614      *
 615      * <p>{@code TextLayout} and
 616      * {@code AttributedCharacterIterator} work in terms of
 617      * {@code Maps} of {@code TextAttributes}.  Normally,
 618      * all the attributes are examined and used to select and
 619      * configure a {@code Font} instance.  If a {@code FONT}
 620      * attribute is present, though, its associated {@code Font}
 621      * will be used.  This provides a way for users to override the
 622      * resolution of font attributes into a {@code Font}, or
 623      * force use of a particular {@code Font} instance.  This
 624      * also allows users to specify subclasses of {@code Font} in
 625      * cases where a {@code Font} can be subclassed.
 626      *
 627      * <p>{@code FONT} is used for special situations where
 628      * clients already have a {@code Font} instance but still
 629      * need to use {@code Map}-based APIs.  Typically, there will
 630      * be no other attributes in the {@code Map} except the
 631      * {@code FONT} attribute.  With {@code Map}-based APIs
 632      * the common case is to specify all attributes individually, so
 633      * {@code FONT} is not needed or desirable.
 634      *
 635      * <p>However, if both {@code FONT} and other attributes are
 636      * present in the {@code Map}, the rendering system will
 637      * merge the attributes defined in the {@code Font} with the
 638      * additional attributes.  This merging process classifies
 639      * {@code TextAttributes} into two groups.  One group, the
 640      * 'primary' group, is considered fundamental to the selection and
 641      * metric behavior of a font.  These attributes are
 642      * {@code FAMILY}, {@code WEIGHT}, {@code WIDTH},
 643      * {@code POSTURE}, {@code SIZE},
 644      * {@code TRANSFORM}, {@code SUPERSCRIPT}, and
 645      * {@code TRACKING}. The other group, the 'secondary' group,
 646      * consists of all other defined attributes, with the exception of
 647      * {@code FONT} itself.
 648      *
 649      * <p>To generate the new {@code Map}, first the
 650      * {@code Font} is obtained from the {@code FONT}
 651      * attribute, and <em>all</em> of its attributes extracted into a
 652      * new {@code Map}.  Then only the <em>secondary</em>
 653      * attributes from the original {@code Map} are added to
 654      * those in the new {@code Map}.  Thus the values of primary
 655      * attributes come solely from the {@code Font}, and the
 656      * values of secondary attributes originate with the
 657      * {@code Font} but can be overridden by other values in the
 658      * {@code Map}.
 659      *
 660      * <p><em>Note:</em>{@code Font's Map}-based
 661      * constructor and {@code deriveFont} methods do not process
 662      * the {@code FONT} attribute, as these are used to create
 663      * new {@code Font} objects.  Instead, {@link
 664      * java.awt.Font#getFont(Map) Font.getFont(Map)} should be used to
 665      * handle the {@code FONT} attribute.
 666      *
 667      * @see java.awt.Font
 668      */
 669     public static final TextAttribute FONT =
 670         new TextAttribute("font");
 671 
 672     /**
 673      * Attribute key for a user-defined glyph to display in lieu
 674      * of the font's standard glyph for a character.  Values are
 675      * instances of GraphicAttribute.  The default value is null,
 676      * indicating that the standard glyphs provided by the font
 677      * should be used.
 678      *
 679      * <p>This attribute is used to reserve space for a graphic or
 680      * other component embedded in a line of text.  It is required for
 681      * correct positioning of 'inline' components within a line when
 682      * bidirectional reordering (see {@link java.text.Bidi}) is
 683      * performed.  Each character (Unicode code point) will be
 684      * rendered using the provided GraphicAttribute. Typically, the
 685      * characters to which this attribute is applied should be
 686      * <code>\uFFFC</code>.
 687      *
 688      * <p>The GraphicAttribute determines the logical and visual
 689      * bounds of the text; the actual Font values are ignored.
 690      *
 691      * @see GraphicAttribute
 692      */
 693     public static final TextAttribute CHAR_REPLACEMENT =
 694         new TextAttribute("char_replacement");
 695 
 696     //
 697     // Adornments added to text.
 698     //
 699 
 700     /**
 701      * Attribute key for the paint used to render the text.  Values are
 702      * instances of <b>{@code Paint}</b>.  The default value is
 703      * null, indicating that the {@code Paint} set on the
 704      * {@code Graphics2D} at the time of rendering is used.
 705      *
 706      * <p>Glyphs will be rendered using this
 707      * {@code Paint} regardless of the {@code Paint} value
 708      * set on the {@code Graphics} (but see {@link #SWAP_COLORS}).
 709      *
 710      * @see java.awt.Paint
 711      * @see #SWAP_COLORS
 712      */
 713     public static final TextAttribute FOREGROUND =
 714         new TextAttribute("foreground");
 715 
 716     /**
 717      * Attribute key for the paint used to render the background of
 718      * the text.  Values are instances of <b>{@code Paint}</b>.
 719      * The default value is null, indicating that the background
 720      * should not be rendered.
 721      *
 722      * <p>The logical bounds of the text will be filled using this
 723      * {@code Paint}, and then the text will be rendered on top
 724      * of it (but see {@link #SWAP_COLORS}).
 725      *
 726      * <p>The visual bounds of the text is extended to include the
 727      * logical bounds, if necessary.  The outline is not affected.
 728      *
 729      * @see java.awt.Paint
 730      * @see #SWAP_COLORS
 731      */
 732     public static final TextAttribute BACKGROUND =
 733         new TextAttribute("background");
 734 
 735     /**
 736      * Attribute key for underline.  Values are instances of
 737      * <b>{@code Integer}</b>.  The default value is -1, which
 738      * means no underline.
 739      *
 740      * <p>The constant value {@link #UNDERLINE_ON} is provided.
 741      *
 742      * <p>The underline affects both the visual bounds and the outline
 743      * of the text.
 744      */
 745     public static final TextAttribute UNDERLINE =
 746         new TextAttribute("underline");
 747 
 748     /**
 749      * Standard underline.
 750      *
 751      * @see #UNDERLINE
 752      */
 753     public static final Integer UNDERLINE_ON =
 754         Integer.valueOf(0);
 755 
 756     /**
 757      * Attribute key for strikethrough.  Values are instances of
 758      * <b>{@code Boolean}</b>.  The default value is
 759      * {@code false}, which means no strikethrough.
 760      *
 761      * <p>The constant value {@link #STRIKETHROUGH_ON} is provided.
 762      *
 763      * <p>The strikethrough affects both the visual bounds and the
 764      * outline of the text.
 765      */
 766     public static final TextAttribute STRIKETHROUGH =
 767         new TextAttribute("strikethrough");
 768 
 769     /**
 770      * A single strikethrough.
 771      *
 772      * @see #STRIKETHROUGH
 773      */
 774     public static final Boolean STRIKETHROUGH_ON =
 775         Boolean.TRUE;
 776 
 777     //
 778     // Attributes use to control layout of text on a line.
 779     //
 780 
 781     /**
 782      * Attribute key for the run direction of the line.  Values are
 783      * instances of <b>{@code Boolean}</b>.  The default value is
 784      * null, which indicates that the standard Bidi algorithm for
 785      * determining run direction should be used with the value {@link
 786      * java.text.Bidi#DIRECTION_DEFAULT_LEFT_TO_RIGHT}.
 787      *
 788      * <p>The constants {@link #RUN_DIRECTION_RTL} and {@link
 789      * #RUN_DIRECTION_LTR} are provided.
 790      *
 791      * <p>This determines the value passed to the {@link
 792      * java.text.Bidi} constructor to select the primary direction of
 793      * the text in the paragraph.
 794      *
 795      * <p><em>Note:</em> This attribute should have the same value for
 796      * all the text in a paragraph, otherwise the behavior is
 797      * undetermined.
 798      *
 799      * @see java.text.Bidi
 800      */
 801     public static final TextAttribute RUN_DIRECTION =
 802         new TextAttribute("run_direction");
 803 
 804     /**
 805      * Left-to-right run direction.
 806      * @see #RUN_DIRECTION
 807      */
 808     public static final Boolean RUN_DIRECTION_LTR =
 809         Boolean.FALSE;
 810 
 811     /**
 812      * Right-to-left run direction.
 813      * @see #RUN_DIRECTION
 814      */
 815     public static final Boolean RUN_DIRECTION_RTL =
 816         Boolean.TRUE;
 817 
 818     /**
 819      * Attribute key for the embedding level of the text.  Values are
 820      * instances of <b>{@code Integer}</b>.  The default value is
 821      * {@code null}, indicating that the Bidirectional
 822      * algorithm should run without explicit embeddings.
 823      *
 824      * <p>Positive values 1 through 61 are <em>embedding</em> levels,
 825      * negative values -1 through -61 are <em>override</em> levels.
 826      * The value 0 means that the base line direction is used.  These
 827      * levels are passed in the embedding levels array to the {@link
 828      * java.text.Bidi} constructor.
 829      *
 830      * <p><em>Note:</em> When this attribute is present anywhere in
 831      * a paragraph, then any Unicode bidi control characters (RLO,
 832      * LRO, RLE, LRE, and PDF) in the paragraph are
 833      * disregarded, and runs of text where this attribute is not
 834      * present are treated as though it were present and had the value
 835      * 0.
 836      *
 837      * @see java.text.Bidi
 838      */
 839     public static final TextAttribute BIDI_EMBEDDING =
 840         new TextAttribute("bidi_embedding");
 841 
 842     /**
 843      * Attribute key for the justification of a paragraph.  Values are
 844      * instances of <b>{@code Number}</b>.  The default value is
 845      * 1, indicating that justification should use the full width
 846      * provided.  Values are pinned to the range [0..1].
 847      *
 848      * <p>The constants {@link #JUSTIFICATION_FULL} and {@link
 849      * #JUSTIFICATION_NONE} are provided.
 850      *
 851      * <p>Specifies the fraction of the extra space to use when
 852      * justification is requested on a {@code TextLayout}. For
 853      * example, if the line is 50 points wide and it is requested to
 854      * justify to 70 points, a value of 0.75 will pad to use
 855      * three-quarters of the remaining space, or 15 points, so that
 856      * the resulting line will be 65 points in length.
 857      *
 858      * <p><em>Note:</em> This should have the same value for all the
 859      * text in a paragraph, otherwise the behavior is undetermined.
 860      *
 861      * @see TextLayout#getJustifiedLayout
 862      */
 863     public static final TextAttribute JUSTIFICATION =
 864         new TextAttribute("justification");
 865 
 866     /**
 867      * Justify the line to the full requested width.  This is the
 868      * default value for {@code JUSTIFICATION}.
 869      * @see #JUSTIFICATION
 870      */
 871     public static final Float JUSTIFICATION_FULL =
 872         Float.valueOf(1.0f);
 873 
 874     /**
 875      * Do not allow the line to be justified.
 876      * @see #JUSTIFICATION
 877      */
 878     public static final Float JUSTIFICATION_NONE =
 879         Float.valueOf(0.0f);
 880 
 881     //
 882     // For use by input method.
 883     //
 884 
 885     /**
 886      * Attribute key for input method highlight styles.
 887      *
 888      * <p>Values are instances of {@link
 889      * java.awt.im.InputMethodHighlight} or {@link
 890      * java.text.Annotation}.  The default value is {@code null},
 891      * which means that input method styles should not be applied
 892      * before rendering.
 893      *
 894      * <p>If adjacent runs of text with the same
 895      * {@code InputMethodHighlight} need to be rendered
 896      * separately, the {@code InputMethodHighlights} should be
 897      * wrapped in {@code Annotation} instances.
 898      *
 899      * <p>Input method highlights are used while text is being
 900      * composed by an input method. Text editing components should
 901      * retain them even if they generally only deal with unstyled
 902      * text, and make them available to the drawing routines.
 903      *
 904      * @see java.awt.Font
 905      * @see java.awt.im.InputMethodHighlight
 906      * @see java.text.Annotation
 907      */
 908     public static final TextAttribute INPUT_METHOD_HIGHLIGHT =
 909         new TextAttribute("input method highlight");
 910 
 911     /**
 912      * Attribute key for input method underlines.  Values
 913      * are instances of <b>{@code Integer}</b>.  The default
 914      * value is {@code -1}, which means no underline.
 915      *
 916      * <p>Several constant values are provided, see {@link
 917      * #UNDERLINE_LOW_ONE_PIXEL}, {@link #UNDERLINE_LOW_TWO_PIXEL},
 918      * {@link #UNDERLINE_LOW_DOTTED}, {@link #UNDERLINE_LOW_GRAY}, and
 919      * {@link #UNDERLINE_LOW_DASHED}.
 920      *
 921      * <p>This may be used in conjunction with {@link #UNDERLINE} if
 922      * desired.  The primary purpose is for use by input methods.
 923      * Other use of these underlines for simple ornamentation might
 924      * confuse users.
 925      *
 926      * <p>The input method underline affects both the visual bounds and
 927      * the outline of the text.
 928      *
 929      * @since 1.3
 930      */
 931     public static final TextAttribute INPUT_METHOD_UNDERLINE =
 932         new TextAttribute("input method underline");
 933 
 934     /**
 935      * Single pixel solid low underline.
 936      * @see #INPUT_METHOD_UNDERLINE
 937      * @since 1.3
 938      */
 939     public static final Integer UNDERLINE_LOW_ONE_PIXEL =
 940         Integer.valueOf(1);
 941 
 942     /**
 943      * Double pixel solid low underline.
 944      * @see #INPUT_METHOD_UNDERLINE
 945      * @since 1.3
 946      */
 947     public static final Integer UNDERLINE_LOW_TWO_PIXEL =
 948         Integer.valueOf(2);
 949 
 950     /**
 951      * Single pixel dotted low underline.
 952      * @see #INPUT_METHOD_UNDERLINE
 953      * @since 1.3
 954      */
 955     public static final Integer UNDERLINE_LOW_DOTTED =
 956         Integer.valueOf(3);
 957 
 958     /**
 959      * Double pixel gray low underline.
 960      * @see #INPUT_METHOD_UNDERLINE
 961      * @since 1.3
 962      */
 963     public static final Integer UNDERLINE_LOW_GRAY =
 964         Integer.valueOf(4);
 965 
 966     /**
 967      * Single pixel dashed low underline.
 968      * @see #INPUT_METHOD_UNDERLINE
 969      * @since 1.3
 970      */
 971     public static final Integer UNDERLINE_LOW_DASHED =
 972         Integer.valueOf(5);
 973 
 974     /**
 975      * Attribute key for swapping foreground and background
 976      * {@code Paints}.  Values are instances of
 977      * <b>{@code Boolean}</b>.  The default value is
 978      * {@code false}, which means do not swap colors.
 979      *
 980      * <p>The constant value {@link #SWAP_COLORS_ON} is defined.
 981      *
 982      * <p>If the {@link #FOREGROUND} attribute is set, its
 983      * {@code Paint} will be used as the background, otherwise
 984      * the {@code Paint} currently on the {@code Graphics}
 985      * will be used.  If the {@link #BACKGROUND} attribute is set, its
 986      * {@code Paint} will be used as the foreground, otherwise
 987      * the system will find a contrasting color to the
 988      * (resolved) background so that the text will be visible.
 989      *
 990      * @see #FOREGROUND
 991      * @see #BACKGROUND
 992      */
 993     public static final TextAttribute SWAP_COLORS =
 994         new TextAttribute("swap_colors");
 995 
 996     /**
 997      * Swap foreground and background.
 998      * @see #SWAP_COLORS
 999      * @since 1.3
1000      */
1001     public static final Boolean SWAP_COLORS_ON =
1002         Boolean.TRUE;
1003 
1004     /**
1005      * Attribute key for converting ASCII decimal digits to other
1006      * decimal ranges.  Values are instances of {@link NumericShaper}.
1007      * The default is {@code null}, which means do not perform
1008      * numeric shaping.
1009      *
1010      * <p>When a numeric shaper is defined, the text is first
1011      * processed by the shaper before any other analysis of the text
1012      * is performed.
1013      *
1014      * <p><em>Note:</em> This should have the same value for all the
1015      * text in the paragraph, otherwise the behavior is undetermined.
1016      *
1017      * @see NumericShaper
1018      * @since 1.4
1019      */
1020     public static final TextAttribute NUMERIC_SHAPING =
1021         new TextAttribute("numeric_shaping");
1022 
1023     /**
1024      * Attribute key to request kerning. Values are instances of
1025      * <b>{@code Integer}</b>.  The default value is
1026      * {@code 0}, which does not request kerning.
1027      *
1028      * <p>The constant value {@link #KERNING_ON} is provided.
1029      *
1030      * <p>The default advances of single characters are not
1031      * appropriate for some character sequences, for example "To" or
1032      * "AWAY".  Without kerning the adjacent characters appear to be
1033      * separated by too much space.  Kerning causes selected sequences
1034      * of characters to be spaced differently for a more pleasing
1035      * visual appearance.
1036      *
1037      * @since 1.6
1038      */
1039     public static final TextAttribute KERNING =
1040         new TextAttribute("kerning");
1041 
1042     /**
1043      * Request standard kerning.
1044      * @see #KERNING
1045      * @since 1.6
1046      */
1047     public static final Integer KERNING_ON =
1048         Integer.valueOf(1);
1049 
1050 
1051     /**
1052      * Attribute key for enabling optional ligatures. Values are
1053      * instances of <b>{@code Integer}</b>.  The default value is
1054      * {@code 0}, which means do not use optional ligatures.
1055      *
1056      * <p>The constant value {@link #LIGATURES_ON} is defined.
1057      *
1058      * <p>Ligatures required by the writing system are always enabled.
1059      *
1060      * @since 1.6
1061      */
1062     public static final TextAttribute LIGATURES =
1063         new TextAttribute("ligatures");
1064 
1065     /**
1066      * Request standard optional ligatures.
1067      * @see #LIGATURES
1068      * @since 1.6
1069      */
1070     public static final Integer LIGATURES_ON =
1071         Integer.valueOf(1);
1072 
1073     /**
1074      * Attribute key to control tracking.  Values are instances of
1075      * <b>{@code Number}</b>.  The default value is
1076      * {@code 0}, which means no additional tracking.
1077      *
1078      * <p>The constant values {@link #TRACKING_TIGHT} and {@link
1079      * #TRACKING_LOOSE} are provided.
1080      *
1081      * <p>The tracking value is multiplied by the font point size and
1082      * passed through the font transform to determine an additional
1083      * amount to add to the advance of each glyph cluster.  Positive
1084      * tracking values will inhibit formation of optional ligatures.
1085      * Tracking values are typically between {@code -0.1} and
1086      * {@code 0.3}; values outside this range are generally not
1087      * desirable.
1088      *
1089      * @since 1.6
1090      */
1091     public static final TextAttribute TRACKING =
1092         new TextAttribute("tracking");
1093 
1094     /**
1095      * Perform tight tracking.
1096      * @see #TRACKING
1097      * @since 1.6
1098      */
1099     public static final Float TRACKING_TIGHT =
1100         Float.valueOf(-.04f);
1101 
1102     /**
1103      * Perform loose tracking.
1104      * @see #TRACKING
1105      * @since 1.6
1106      */
1107     public static final Float TRACKING_LOOSE =
1108         Float.valueOf(.04f);
1109 }