History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/awt/font/TextAttribute.java (1 of 18352 files). Show all

Unified · Split

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