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