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