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