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