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 }