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 * <H2>Values</H2> 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 * <h3>Summary of attributes</h3> 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) { SharedSecrets.setJavaAWTFontAccess(new JavaAWTFontAccessImpl())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 */ TextAttribute(String name)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 */ readResolve()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 } 1110