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