0001 /*
0002 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 /*
0027 * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved
0028 * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved
0029 *
0030 * The original version of this source code and documentation is
0031 * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary
0032 * of IBM. These materials are provided under terms of a License
0033 * Agreement between Taligent and Sun. This technology is protected
0034 * by multiple US and International patents.
0035 *
0036 * This notice and attribution to Taligent may not be removed.
0037 * Taligent is a registered trademark of Taligent, Inc.
0038 *
0039 */
0040
0041 package java.awt.font;
0042
0043 import java.io.InvalidObjectException;
0044 import java.text.AttributedCharacterIterator.Attribute;
0045 import java.util.Map;
0046 import java.util.HashMap;
0047
0048 /**
0049 * The <code>TextAttribute</code> class defines attribute keys and
0050 * attribute values used for text rendering.
0051 * <p>
0052 * <code>TextAttribute</code> instances are used as attribute keys to
0053 * identify attributes in
0054 * {@link java.awt.Font Font},
0055 * {@link java.awt.font.TextLayout TextLayout},
0056 * {@link java.text.AttributedCharacterIterator AttributedCharacterIterator},
0057 * and other classes handling text attributes. Other constants defined
0058 * in this class can be used as attribute values.
0059 * <p>
0060 * For each text attribute, the documentation provides:
0061 * <UL>
0062 * <LI>the type of its value,
0063 * <LI>the relevant predefined constants, if any
0064 * <LI>the default effect if the attribute is absent
0065 * <LI>the valid values if there are limitations
0066 * <LI>a description of the effect.
0067 * </UL>
0068 * <p>
0069 * <H4>Values</H4>
0070 * <UL>
0071 * <LI>The values of attributes must always be immutable.
0072 * <LI>Where value limitations are given, any value outside of that
0073 * set is reserved for future use; the value will be treated as
0074 * the default.
0075 * <LI>The value <code>null</code> is treated the same as the
0076 * default value and results in the default behavior.
0077 * <li>If the value is not of the proper type, the attribute
0078 * will be ignored.
0079 * <li>The identity of the value does not matter, only the actual
0080 * value. For example, <code>TextAttribute.WEIGHT_BOLD</code> and
0081 * <code>new Float(2.0)</code>
0082 * indicate the same <code>WEIGHT</code>.
0083 * <li>Attribute values of type <code>Number</code> (used for
0084 * <code>WEIGHT</code>, <code>WIDTH</code>, <code>POSTURE</code>,
0085 * <code>SIZE</code>, <code>JUSTIFICATION</code>, and
0086 * <code>TRACKING</code>) can vary along their natural range and are
0087 * not restricted to the predefined constants.
0088 * <code>Number.floatValue()</code> is used to get the actual value
0089 * from the <code>Number</code>.
0090 * <li>The values for <code>WEIGHT</code>, <code>WIDTH</code>, and
0091 * <code>POSTURE</code> are interpolated by the system, which
0092 * can select the 'nearest available' font or use other techniques to
0093 * approximate the user's request.
0094 *
0095 * </UL>
0096 *
0097 * <h4>Summary of attributes</h4>
0098 * <p>
0099 * <font size="-1">
0100 * <table align="center" border="0" cellspacing="0" cellpadding="2" width="%95"
0101 * summary="Key, value type, principal constants, and default value
0102 * behavior of all TextAttributes">
0103 * <tr bgcolor="#ccccff">
0104 * <th valign="TOP" align="CENTER">Key</th>
0105 * <th valign="TOP" align="CENTER">Value Type</th>
0106 * <th valign="TOP" align="CENTER">Principal Constants</th>
0107 * <th valign="TOP" align="CENTER">Default Value</th>
0108 * </tr>
0109 * <tr>
0110 * <td valign="TOP">{@link #FAMILY}</td>
0111 * <td valign="TOP">String</td>
0112 * <td valign="TOP">See Font {@link java.awt.Font#DIALOG DIALOG},
0113 {@link java.awt.Font#DIALOG_INPUT DIALOG_INPUT},<br> {@link java.awt.Font#SERIF SERIF},
0114 {@link java.awt.Font#SANS_SERIF SANS_SERIF}, and {@link java.awt.Font#MONOSPACED MONOSPACED}.
0115 </td>
0116 * <td valign="TOP">"Default" (use platform default)</td>
0117 * </tr>
0118 * <tr bgcolor="#eeeeff">
0119 * <td valign="TOP">{@link #WEIGHT}</td>
0120 * <td valign="TOP">Number</td>
0121 * <td valign="TOP">WEIGHT_REGULAR, WEIGHT_BOLD</td>
0122 * <td valign="TOP">WEIGHT_REGULAR</td>
0123 * </tr>
0124 * <tr>
0125 * <td valign="TOP">{@link #WIDTH}</td>
0126 * <td valign="TOP">Number</td>
0127 * <td valign="TOP">WIDTH_CONDENSED, WIDTH_REGULAR,<br>WIDTH_EXTENDED</td>
0128 * <td valign="TOP">WIDTH_REGULAR</td>
0129 * </tr>
0130 * <tr bgcolor="#eeeeff">
0131 * <td valign="TOP">{@link #POSTURE}</td>
0132 * <td valign="TOP">Number</td>
0133 * <td valign="TOP">POSTURE_REGULAR, POSTURE_OBLIQUE</td>
0134 * <td valign="TOP">POSTURE_REGULAR</td>
0135 * </tr>
0136 * <tr>
0137 * <td valign="TOP">{@link #SIZE}</td>
0138 * <td valign="TOP">Number</td>
0139 * <td valign="TOP">none</td>
0140 * <td valign="TOP">12.0</td>
0141 * </tr>
0142 * <tr bgcolor="#eeeeff">
0143 * <td valign="TOP">{@link #TRANSFORM}</td>
0144 * <td valign="TOP">{@link TransformAttribute}</td>
0145 * <td valign="TOP">See TransformAttribute {@link TransformAttribute#IDENTITY IDENTITY}</td>
0146 * <td valign="TOP">TransformAttribute.IDENTITY</td>
0147 * </tr>
0148 * <tr>
0149 * <td valign="TOP">{@link #SUPERSCRIPT}</td>
0150 * <td valign="TOP">Integer</td>
0151 * <td valign="TOP">SUPERSCRIPT_SUPER, SUPERSCRIPT_SUB</td>
0152 * <td valign="TOP">0 (use the standard glyphs and metrics)</td>
0153 * </tr>
0154 * <tr bgcolor="#eeeeff">
0155 * <td valign="TOP">{@link #FONT}</td>
0156 * <td valign="TOP">{@link java.awt.Font}</td>
0157 * <td valign="TOP">none</td>
0158 * <td valign="TOP">null (do not override font resolution)</td>
0159 * </tr>
0160 * <tr>
0161 * <td valign="TOP">{@link #CHAR_REPLACEMENT}</td>
0162 * <td valign="TOP">{@link GraphicAttribute}</td>
0163 * <td valign="TOP">none</td>
0164 * <td valign="TOP">null (draw text using font glyphs)</td>
0165 * </tr>
0166 * <tr bgcolor="#eeeeff">
0167 * <td valign="TOP">{@link #FOREGROUND}</td>
0168 * <td valign="TOP">{@link java.awt.Paint}</td>
0169 * <td valign="TOP">none</td>
0170 * <td valign="TOP">null (use current graphics paint)</td>
0171 * </tr>
0172 * <tr>
0173 * <td valign="TOP">{@link #BACKGROUND}</td>
0174 * <td valign="TOP">{@link java.awt.Paint}</td>
0175 * <td valign="TOP">none</td>
0176 * <td valign="TOP">null (do not render background)</td>
0177 * </tr>
0178 * <tr bgcolor="#eeeeff">
0179 * <td valign="TOP">{@link #UNDERLINE}</td>
0180 * <td valign="TOP">Integer</td>
0181 * <td valign="TOP">UNDERLINE_ON</td>
0182 * <td valign="TOP">-1 (do not render underline)</td>
0183 * </tr>
0184 * <tr>
0185 * <td valign="TOP">{@link #STRIKETHROUGH}</td>
0186 * <td valign="TOP">Boolean</td>
0187 * <td valign="TOP">STRIKETHROUGH_ON</td>
0188 * <td valign="TOP">false (do not render strikethrough)</td>
0189 * </tr>
0190 * <tr bgcolor="#eeeeff">
0191 * <td valign="TOP">{@link #RUN_DIRECTION}</td>
0192 * <td valign="TOP">Boolean</td>
0193 * <td valign="TOP">RUN_DIRECTION_LTR<br>RUN_DIRECTION_RTL</td>
0194 * <td valign="TOP">null (use {@link java.text.Bidi} standard default)</td>
0195 * </tr>
0196 * <tr>
0197 * <td valign="TOP">{@link #BIDI_EMBEDDING}</td>
0198 * <td valign="TOP">Integer</td>
0199 * <td valign="TOP">none</td>
0200 * <td valign="TOP">0 (use base line direction)</td>
0201 * </tr>
0202 * <tr bgcolor="#eeeeff">
0203 * <td valign="TOP">{@link #JUSTIFICATION}</td>
0204 * <td valign="TOP">Number</td>
0205 * <td valign="TOP">JUSTIFICATION_FULL</td>
0206 * <td valign="TOP">JUSTIFICATION_FULL</td>
0207 * </tr>
0208 * <tr>
0209 * <td valign="TOP">{@link #INPUT_METHOD_HIGHLIGHT}</td>
0210 * <td valign="TOP">{@link java.awt.im.InputMethodHighlight},<br>{@link java.text.Annotation}</td>
0211 * <td valign="TOP">(see class)</td>
0212 * <td valign="TOP">null (do not apply input highlighting)</td>
0213 * </tr>
0214 * <tr bgcolor="#eeeeff">
0215 * <td valign="TOP">{@link #INPUT_METHOD_UNDERLINE}</td>
0216 * <td valign="TOP">Integer</td>
0217 * <td valign="TOP">UNDERLINE_LOW_ONE_PIXEL,<br>UNDERLINE_LOW_TWO_PIXEL</td>
0218 * <td valign="TOP">-1 (do not render underline)</td>
0219 * </tr>
0220 * <tr>
0221 * <td valign="TOP">{@link #SWAP_COLORS}</td>
0222 * <td valign="TOP">Boolean</td>
0223 * <td valign="TOP">SWAP_COLORS_ON</td>
0224 * <td valign="TOP">false (do not swap colors)</td>
0225 * </tr>
0226 * <tr bgcolor="#eeeeff">
0227 * <td valign="TOP">{@link #NUMERIC_SHAPING}</td>
0228 * <td valign="TOP">{@link java.awt.font.NumericShaper}</td>
0229 * <td valign="TOP">none</td>
0230 * <td valign="TOP">null (do not shape digits)</td>
0231 * </tr>
0232 * <tr>
0233 * <td valign="TOP">{@link #KERNING}</td>
0234 * <td valign="TOP">Integer</td>
0235 * <td valign="TOP">KERNING_ON</td>
0236 * <td valign="TOP">0 (do not request kerning)</td>
0237 * </tr>
0238 * <tr bgcolor="#eeeeff">
0239 * <td valign="TOP">{@link #LIGATURES}</td>
0240 * <td valign="TOP">Integer</td>
0241 * <td valign="TOP">LIGATURES_ON</td>
0242 * <td valign="TOP">0 (do not form optional ligatures)</td>
0243 * </tr>
0244 * <tr>
0245 * <td valign="TOP">{@link #TRACKING}</td>
0246 * <td valign="TOP">Number</td>
0247 * <td valign="TOP">TRACKING_LOOSE, TRACKING_TIGHT</td>
0248 * <td valign="TOP">0 (do not add tracking)</td>
0249 * </tr>
0250 * </table>
0251 * </font>
0252 *
0253 * @see java.awt.Font
0254 * @see java.awt.font.TextLayout
0255 * @see java.text.AttributedCharacterIterator
0256 */
0257 public final class TextAttribute extends Attribute {
0258
0259 // table of all instances in this class, used by readResolve
0260 private static final Map instanceMap = new HashMap(29);
0261
0262 /**
0263 * Constructs a <code>TextAttribute</code> with the specified name.
0264 * @param name the attribute name to assign to this
0265 * <code>TextAttribute</code>
0266 */
0267 protected TextAttribute(String name) {
0268 super (name);
0269 if (this .getClass() == TextAttribute.class) {
0270 instanceMap.put(name, this );
0271 }
0272 }
0273
0274 /**
0275 * Resolves instances being deserialized to the predefined constants.
0276 */
0277 protected Object readResolve() throws InvalidObjectException {
0278 if (this .getClass() != TextAttribute.class) {
0279 throw new InvalidObjectException(
0280 "subclass didn't correctly implement readResolve");
0281 }
0282
0283 TextAttribute instance = (TextAttribute) instanceMap
0284 .get(getName());
0285 if (instance != null) {
0286 return instance;
0287 } else {
0288 throw new InvalidObjectException("unknown attribute name");
0289 }
0290 }
0291
0292 // Serialization compatibility with Java 2 platform v1.2.
0293 // 1.2 will throw an InvalidObjectException if ever asked to
0294 // deserialize INPUT_METHOD_UNDERLINE.
0295 // This shouldn't happen in real life.
0296 static final long serialVersionUID = 7744112784117861702L;
0297
0298 //
0299 // For use with Font.
0300 //
0301
0302 /**
0303 * Attribute key for the font name. Values are instances of
0304 * <b><code>String</code></b>. The default value is
0305 * <code>"Default"</code>, which causes the platform default font
0306 * family to be used.
0307 *
0308 * <p> The <code>Font</code> class defines constants for the logical
0309 * font names
0310 * {@link java.awt.Font#DIALOG DIALOG},
0311 * {@link java.awt.Font#DIALOG_INPUT DIALOG_INPUT},
0312 * {@link java.awt.Font#SANS_SERIF SANS_SERIF},
0313 * {@link java.awt.Font#SERIF SERIF}, and
0314 * {@link java.awt.Font#MONOSPACED MONOSPACED}.
0315 *
0316 * <p>This defines the value passed as <code>name</code> to the
0317 * <code>Font</code> constructor. Both logical and physical
0318 * font names are allowed. If a font with the requested name
0319 * is not found, the default font is used.
0320 *
0321 * <p><em>Note:</em> This attribute is unfortunately misnamed, as
0322 * it specifies the face name and not just the family. Thus
0323 * values such as "Lucida Sans Bold" will select that face if it
0324 * exists. Note, though, that if the requested face does not
0325 * exist, the default will be used with <em>regular</em> weight.
0326 * The "Bold" in the name is part of the face name, not a separate
0327 * request that the font's weight be bold.</p>
0328 */
0329 public static final TextAttribute FAMILY = new TextAttribute(
0330 "family");
0331
0332 /**
0333 * Attribute key for the weight of a font. Values are instances
0334 * of <b><code>Number</code></b>. The default value is
0335 * <code>WEIGHT_REGULAR</code>.
0336 *
0337 * <p>Several constant values are provided, see {@link
0338 * #WEIGHT_EXTRA_LIGHT}, {@link #WEIGHT_LIGHT}, {@link
0339 * #WEIGHT_DEMILIGHT}, {@link #WEIGHT_REGULAR}, {@link
0340 * #WEIGHT_SEMIBOLD}, {@link #WEIGHT_MEDIUM}, {@link
0341 * #WEIGHT_DEMIBOLD}, {@link #WEIGHT_BOLD}, {@link #WEIGHT_HEAVY},
0342 * {@link #WEIGHT_EXTRABOLD}, and {@link #WEIGHT_ULTRABOLD}. The
0343 * value <code>WEIGHT_BOLD</code> corresponds to the
0344 * style value <code>Font.BOLD</code> as passed to the
0345 * <code>Font</code> constructor.
0346 *
0347 * <p>The value is roughly the ratio of the stem width to that of
0348 * the regular weight.
0349 *
0350 * <p>The system can interpolate the provided value.
0351 */
0352 public static final TextAttribute WEIGHT = new TextAttribute(
0353 "weight");
0354
0355 /**
0356 * The lightest predefined weight.
0357 * @see #WEIGHT
0358 */
0359 public static final Float WEIGHT_EXTRA_LIGHT = Float.valueOf(0.5f);
0360
0361 /**
0362 * The standard light weight.
0363 * @see #WEIGHT
0364 */
0365 public static final Float WEIGHT_LIGHT = Float.valueOf(0.75f);
0366
0367 /**
0368 * An intermediate weight between <code>WEIGHT_LIGHT</code> and
0369 * <code>WEIGHT_STANDARD</code>.
0370 * @see #WEIGHT
0371 */
0372 public static final Float WEIGHT_DEMILIGHT = Float.valueOf(0.875f);
0373
0374 /**
0375 * The standard weight. This is the default value for <code>WEIGHT</code>.
0376 * @see #WEIGHT
0377 */
0378 public static final Float WEIGHT_REGULAR = Float.valueOf(1.0f);
0379
0380 /**
0381 * A moderately heavier weight than <code>WEIGHT_REGULAR</code>.
0382 * @see #WEIGHT
0383 */
0384 public static final Float WEIGHT_SEMIBOLD = Float.valueOf(1.25f);
0385
0386 /**
0387 * An intermediate weight between <code>WEIGHT_REGULAR</code> and
0388 * <code>WEIGHT_BOLD</code>.
0389 * @see #WEIGHT
0390 */
0391 public static final Float WEIGHT_MEDIUM = Float.valueOf(1.5f);
0392
0393 /**
0394 * A moderately lighter weight than <code>WEIGHT_BOLD</code>.
0395 * @see #WEIGHT
0396 */
0397 public static final Float WEIGHT_DEMIBOLD = Float.valueOf(1.75f);
0398
0399 /**
0400 * The standard bold weight.
0401 * @see #WEIGHT
0402 */
0403 public static final Float WEIGHT_BOLD = Float.valueOf(2.0f);
0404
0405 /**
0406 * A moderately heavier weight than <code>WEIGHT_BOLD</code>.
0407 * @see #WEIGHT
0408 */
0409 public static final Float WEIGHT_HEAVY = Float.valueOf(2.25f);
0410
0411 /**
0412 * An extra heavy weight.
0413 * @see #WEIGHT
0414 */
0415 public static final Float WEIGHT_EXTRABOLD = Float.valueOf(2.5f);
0416
0417 /**
0418 * The heaviest predefined weight.
0419 * @see #WEIGHT
0420 */
0421 public static final Float WEIGHT_ULTRABOLD = Float.valueOf(2.75f);
0422
0423 /**
0424 * Attribute key for the width of a font. Values are instances of
0425 * <b><code>Number</code></b>. The default value is
0426 * <code>WIDTH_REGULAR</code>.
0427 *
0428 * <p>Several constant values are provided, see {@link
0429 * #WIDTH_CONDENSED}, {@link #WIDTH_SEMI_CONDENSED}, {@link
0430 * #WIDTH_REGULAR}, {@link #WIDTH_SEMI_EXTENDED}, {@link
0431 * #WIDTH_EXTENDED}.
0432 *
0433 * <p>The value is roughly the ratio of the advance width to that
0434 * of the regular width.
0435 *
0436 * <p>The system can interpolate the provided value.
0437 */
0438 public static final TextAttribute WIDTH = new TextAttribute("width");
0439
0440 /**
0441 * The most condensed predefined width.
0442 * @see #WIDTH
0443 */
0444 public static final Float WIDTH_CONDENSED = Float.valueOf(0.75f);
0445
0446 /**
0447 * A moderately condensed width.
0448 * @see #WIDTH
0449 */
0450 public static final Float WIDTH_SEMI_CONDENSED = Float
0451 .valueOf(0.875f);
0452
0453 /**
0454 * The standard width. This is the default value for
0455 * <code>WIDTH</code>.
0456 * @see #WIDTH
0457 */
0458 public static final Float WIDTH_REGULAR = Float.valueOf(1.0f);
0459
0460 /**
0461 * A moderately extended width.
0462 * @see #WIDTH
0463 */
0464 public static final Float WIDTH_SEMI_EXTENDED = Float
0465 .valueOf(1.25f);
0466
0467 /**
0468 * The most extended predefined width.
0469 * @see #WIDTH
0470 */
0471 public static final Float WIDTH_EXTENDED = Float.valueOf(1.5f);
0472
0473 /**
0474 * Attribute key for the posture of a font. Values are instances
0475 * of <b><code>Number</code></b>. The default value is
0476 * <code>POSTURE_REGULAR</code>.
0477 *
0478 * <p>Two constant values are provided, {@link #POSTURE_REGULAR}
0479 * and {@link #POSTURE_OBLIQUE}. The value
0480 * <code>POSTURE_OBLIQUE</code> corresponds to the style value
0481 * <code>Font.ITALIC</code> as passed to the <code>Font</code>
0482 * constructor.
0483 *
0484 * <p>The value is roughly the slope of the stems of the font,
0485 * expressed as the run over the rise. Positive values lean right.
0486 *
0487 * <p>The system can interpolate the provided value.
0488 *
0489 * <p>This will affect the font's italic angle as returned by
0490 * <code>Font.getItalicAngle</code>.
0491 *
0492 * @see java.awt.Font#getItalicAngle()
0493 */
0494 public static final TextAttribute POSTURE = new TextAttribute(
0495 "posture");
0496
0497 /**
0498 * The standard posture, upright. This is the default value for
0499 * <code>POSTURE</code>.
0500 * @see #POSTURE
0501 */
0502 public static final Float POSTURE_REGULAR = Float.valueOf(0.0f);
0503
0504 /**
0505 * The standard italic posture.
0506 * @see #POSTURE
0507 */
0508 public static final Float POSTURE_OBLIQUE = Float.valueOf(0.20f);
0509
0510 /**
0511 * Attribute key for the font size. Values are instances of
0512 * <b><code>Number</code></b>. The default value is 12pt.
0513 *
0514 * <p>This corresponds to the <code>size</code> parameter to the
0515 * <code>Font</code> constructor.
0516 *
0517 * <p>Very large or small sizes will impact rendering performance,
0518 * and the rendering system might not render text at these sizes.
0519 * Negative sizes are illegal and result in the default size.
0520 *
0521 * <p>Note that the appearance and metrics of a 12pt font with a
0522 * 2x transform might be different than that of a 24 point font
0523 * with no transform.
0524 */
0525 public static final TextAttribute SIZE = new TextAttribute("size");
0526
0527 /**
0528 * Attribute key for the transform of a font. Values are
0529 * instances of <b><code>TransformAttribute</code></b>. The
0530 * default value is <code>TransformAttribute.IDENTITY</code>.
0531 *
0532 * <p>The <code>TransformAttribute</code> class defines the
0533 * constant {@link TransformAttribute#IDENTITY IDENTITY}.
0534 *
0535 * <p>This corresponds to the transform passed to
0536 * <code>Font.deriveFont(AffineTransform)</code>. Since that
0537 * transform is mutable and <code>TextAttribute</code> values must
0538 * not be, the <code>TransformAttribute</code> wrapper class is
0539 * used.
0540 *
0541 * <p>The primary intent is to support scaling and skewing, though
0542 * other effects are possible.</p>
0543 *
0544 * <p>Some transforms will cause the baseline to be rotated and/or
0545 * shifted. The text and the baseline are transformed together so
0546 * that the text follows the new baseline. For example, with text
0547 * on a horizontal baseline, the new baseline follows the
0548 * direction of the unit x vector passed through the
0549 * transform. Text metrics are measured against this new baseline.
0550 * So, for example, with other things being equal, text rendered
0551 * with a rotated TRANSFORM and an unrotated TRANSFORM will measure as
0552 * having the same ascent, descent, and advance.</p>
0553 *
0554 * <p>In styled text, the baselines for each such run are aligned
0555 * one after the other to potentially create a non-linear baseline
0556 * for the entire run of text. For more information, see {@link
0557 * TextLayout#getLayoutPath}.</p>
0558 *
0559 * @see TransformAttribute
0560 * @see java.awt.geom.AffineTransform
0561 */
0562 public static final TextAttribute TRANSFORM = new TextAttribute(
0563 "transform");
0564
0565 /**
0566 * Attribute key for superscripting and subscripting. Values are
0567 * instances of <b><code>Integer</code></b>. The default value is
0568 * 0, which means that no superscript or subscript is used.
0569 *
0570 * <p>Two constant values are provided, see {@link
0571 * #SUPERSCRIPT_SUPER} and {@link #SUPERSCRIPT_SUB}. These have
0572 * the values 1 and -1 respectively. Values of
0573 * greater magnitude define greater levels of superscript or
0574 * subscripting, for example, 2 corresponds to super-superscript,
0575 * 3 to super-super-superscript, and similarly for negative values
0576 * and subscript, up to a level of 7 (or -7). Values beyond this
0577 * range are reserved; behavior is platform-dependent.
0578 *
0579 * <p><code>SUPERSCRIPT</code> can
0580 * impact the ascent and descent of a font. The ascent
0581 * and descent can never become negative, however.
0582 */
0583 public static final TextAttribute SUPERSCRIPT = new TextAttribute(
0584 "superscript");
0585
0586 /**
0587 * Standard superscript.
0588 * @see #SUPERSCRIPT
0589 */
0590 public static final Integer SUPERSCRIPT_SUPER = Integer.valueOf(1);
0591
0592 /**
0593 * Standard subscript.
0594 * @see #SUPERSCRIPT
0595 */
0596 public static final Integer SUPERSCRIPT_SUB = Integer.valueOf(-1);
0597
0598 /**
0599 * Attribute key used to provide the font to use to render text.
0600 * Values are instances of {@link java.awt.Font}. The default
0601 * value is null, indicating that normal resolution of a
0602 * <code>Font</code> from attributes should be performed.
0603 *
0604 * <p><code>TextLayout</code> and
0605 * <code>AttributedCharacterIterator</code> work in terms of
0606 * <code>Maps</code> of <code>TextAttributes</code>. Normally,
0607 * all the attributes are examined and used to select and
0608 * configure a <code>Font</code> instance. If a <code>FONT</code>
0609 * attribute is present, though, its associated <code>Font</code>
0610 * will be used. This provides a way for users to override the
0611 * resolution of font attributes into a <code>Font</code>, or
0612 * force use of a particular <code>Font</code> instance. This
0613 * also allows users to specify subclasses of <code>Font</code> in
0614 * cases where a <code>Font</code> can be subclassed.
0615 *
0616 * <p><code>FONT</code> is used for special situations where
0617 * clients already have a <code>Font</code> instance but still
0618 * need to use <code>Map</code>-based APIs. Typically, there will
0619 * be no other attributes in the <code>Map</code> except the
0620 * <code>FONT</code> attribute. With <code>Map</code>-based APIs
0621 * the common case is to specify all attributes individually, so
0622 * <code>FONT</code> is not needed or desireable.
0623 *
0624 * <p>However, if both <code>FONT</code> and other attributes are
0625 * present in the <code>Map</code>, the rendering system will
0626 * merge the attributes defined in the <code>Font</code> with the
0627 * additional attributes. This merging process classifies
0628 * <code>TextAttributes</code> into two groups. One group, the
0629 * 'primary' group, is considered fundamental to the selection and
0630 * metric behavior of a font. These attributes are
0631 * <code>FAMILY</code>, <code>WEIGHT</code>, <code>WIDTH</code>,
0632 * <code>POSTURE</code>, <code>SIZE</code>,
0633 * <code>TRANSFORM</code>, <code>SUPERSCRIPT</code>, and
0634 * <code>TRACKING</code>. The other group, the 'secondary' group,
0635 * consists of all other defined attributes, with the exception of
0636 * <code>FONT</code> itself.
0637 *
0638 * <p>To generate the new <code>Map</code>, first the
0639 * <code>Font</code> is obtained from the <code>FONT</code>
0640 * attribute, and <em>all</em> of its attributes extracted into a
0641 * new <code>Map</code>. Then only the <em>secondary</em>
0642 * attributes from the original <code>Map</code> are added to
0643 * those in the new <code>Map</code>. Thus the values of primary
0644 * attributes come solely from the <code>Font</code>, and the
0645 * values of secondary attributes originate with the
0646 * <code>Font</code> but can be overridden by other values in the
0647 * <code>Map</code>.
0648 *
0649 * <p><em>Note:</em><code>Font's</code> <code>Map</code>-based
0650 * constructor and <code>deriveFont</code> methods do not process
0651 * the <code>FONT</code> attribute, as these are used to create
0652 * new <code>Font</code> objects. Instead, {@link
0653 * java.awt.Font#getFont(Map) Font.getFont(Map)} should be used to
0654 * handle the <code>FONT</code> attribute.
0655 *
0656 * @see java.awt.Font
0657 */
0658 public static final TextAttribute FONT = new TextAttribute("font");
0659
0660 /**
0661 * Attribute key for a user-defined glyph to display in lieu
0662 * of the font's standard glyph for a character. Values are
0663 * intances of GraphicAttribute. The default value is null,
0664 * indicating that the standard glyphs provided by the font
0665 * should be used.
0666 *
0667 * <p>This attribute is used to reserve space for a graphic or
0668 * other component embedded in a line of text. It is required for
0669 * correct positioning of 'inline' components within a line when
0670 * bidirectional reordering (see {@link java.text.Bidi}) is
0671 * performed. Each character (Unicode code point) will be
0672 * rendered using the provided GraphicAttribute. Typically, the
0673 * characters to which this attribute is applied should be
0674 * <code>\uFFFC</code>.
0675 *
0676 * <p>The GraphicAttribute determines the logical and visual
0677 * bounds of the text; the actual Font values are ignored.
0678 *
0679 * @see GraphicAttribute
0680 */
0681 public static final TextAttribute CHAR_REPLACEMENT = new TextAttribute(
0682 "char_replacement");
0683
0684 //
0685 // Adornments added to text.
0686 //
0687
0688 /**
0689 * Attribute key for the paint used to render the text. Values are
0690 * instances of <b><code>Paint</code></b>. The default value is
0691 * null, indicating that the <code>Paint</code> set on the
0692 * <code>Graphics2D</code> at the time of rendering is used.
0693 *
0694 * <p>Glyphs will be rendered using this
0695 * <code>Paint</code> regardless of the <code>Paint</code> value
0696 * set on the <code>Graphics</code> (but see {@link #SWAP_COLORS}).
0697 *
0698 * @see java.awt.Paint
0699 * @see #SWAP_COLORS
0700 */
0701 public static final TextAttribute FOREGROUND = new TextAttribute(
0702 "foreground");
0703
0704 /**
0705 * Attribute key for the paint used to render the background of
0706 * the text. Values are instances of <b><code>Paint</code></b>.
0707 * The default value is null, indicating that the background
0708 * should not be rendered.
0709 *
0710 * <p>The logical bounds of the text will be filled using this
0711 * <code>Paint</code>, and then the text will be rendered on top
0712 * of it (but see {@link #SWAP_COLORS}).
0713 *
0714 * <p>The visual bounds of the text is extended to include the
0715 * logical bounds, if necessary. The outline is not affected.
0716 *
0717 * @see java.awt.Paint
0718 * @see #SWAP_COLORS
0719 */
0720 public static final TextAttribute BACKGROUND = new TextAttribute(
0721 "background");
0722
0723 /**
0724 * Attribute key for underline. Values are instances of
0725 * <b><code>Integer</code></b>. The default value is -1, which
0726 * means no underline.
0727 *
0728 * <p>The constant value {@link #UNDERLINE_ON} is provided.
0729 *
0730 * <p>The underline affects both the visual bounds and the outline
0731 * of the text.
0732 */
0733 public static final TextAttribute UNDERLINE = new TextAttribute(
0734 "underline");
0735
0736 /**
0737 * Standard underline.
0738 *
0739 * @see #UNDERLINE
0740 */
0741 public static final Integer UNDERLINE_ON = Integer.valueOf(0);
0742
0743 /**
0744 * Attribute key for strikethrough. Values are instances of
0745 * <b><code>Boolean</code></b>. The default value is
0746 * <code>false</code>, which means no strikethrough.
0747 *
0748 * <p>The constant value {@link #STRIKETHROUGH_ON} is provided.
0749 *
0750 * <p>The strikethrough affects both the visual bounds and the
0751 * outline of the text.
0752 */
0753 public static final TextAttribute STRIKETHROUGH = new TextAttribute(
0754 "strikethrough");
0755
0756 /**
0757 * A single strikethrough.
0758 *
0759 * @see #STRIKETHROUGH
0760 */
0761 public static final Boolean STRIKETHROUGH_ON = Boolean.TRUE;
0762
0763 //
0764 // Attributes use to control layout of text on a line.
0765 //
0766
0767 /**
0768 * Attribute key for the run direction of the line. Values are
0769 * instances of <b><code>Boolean</code></b>. The default value is
0770 * null, which indicates that the standard Bidi algorithm for
0771 * determining run direction should be used with the value {@link
0772 * java.text.Bidi#DIRECTION_DEFAULT_LEFT_TO_RIGHT}.
0773 *
0774 * <p>The constants {@link #RUN_DIRECTION_RTL} and {@link
0775 * #RUN_DIRECTION_LTR} are provided.
0776 *
0777 * <p>This determines the value passed to the {@link
0778 * java.text.Bidi} constructor to select the primary direction of
0779 * the text in the paragraph.
0780 *
0781 * <p><em>Note:</em> This attribute should have the same value for
0782 * all the text in a paragraph, otherwise the behavior is
0783 * undetermined.
0784 *
0785 * @see java.text.Bidi
0786 */
0787 public static final TextAttribute RUN_DIRECTION = new TextAttribute(
0788 "run_direction");
0789
0790 /**
0791 * Left-to-right run direction.
0792 * @see #RUN_DIRECTION
0793 */
0794 public static final Boolean RUN_DIRECTION_LTR = Boolean.FALSE;
0795
0796 /**
0797 * Right-to-left run direction.
0798 * @see #RUN_DIRECTION
0799 */
0800 public static final Boolean RUN_DIRECTION_RTL = Boolean.TRUE;
0801
0802 /**
0803 * Attribute key for the embedding level of the text. Values are
0804 * instances of <b><code>Integer</code></b>. The default value is
0805 * <code>null</code>, indicating that the the Bidirectional
0806 * algorithm should run without explicit embeddings.
0807 *
0808 * <p>Positive values 1 through 61 are <em>embedding</em> levels,
0809 * negative values -1 through -61 are <em>override</em> levels.
0810 * The value 0 means that the base line direction is used. These
0811 * levels are passed in the embedding levels array to the {@link
0812 * java.text.Bidi} constructor.
0813 *
0814 * <p><em>Note:</em> When this attribute is present anywhere in
0815 * a paragraph, then any Unicode bidi control characters (RLO,
0816 * LRO, RLE, LRE, and PDF) in the paragraph are
0817 * disregarded, and runs of text where this attribute is not
0818 * present are treated as though it were present and had the value
0819 * 0.
0820 *
0821 * @see java.text.Bidi
0822 */
0823 public static final TextAttribute BIDI_EMBEDDING = new TextAttribute(
0824 "bidi_embedding");
0825
0826 /**
0827 * Attribute key for the justification of a paragraph. Values are
0828 * instances of <b><code>Number</code></b>. The default value is
0829 * 1, indicating that justification should use the full width
0830 * provided. Values are pinned to the range [0..1].
0831 *
0832 * <p>The constants {@link #JUSTIFICATION_FULL} and {@link
0833 * #JUSTIFICATION_NONE} are provided.
0834 *
0835 * <p>Specifies the fraction of the extra space to use when
0836 * justification is requested on a <code>TextLayout</code>. For
0837 * example, if the line is 50 points wide and it is requested to
0838 * justify to 70 points, a value of 0.75 will pad to use
0839 * three-quarters of the remaining space, or 15 points, so that
0840 * the resulting line will be 65 points in length.
0841 *
0842 * <p><em>Note:</em> This should have the same value for all the
0843 * text in a paragraph, otherwise the behavior is undetermined.
0844 *
0845 * @see TextLayout#getJustifiedLayout
0846 */
0847 public static final TextAttribute JUSTIFICATION = new TextAttribute(
0848 "justification");
0849
0850 /**
0851 * Justify the line to the full requested width. This is the
0852 * default value for <code>JUSTIFICATION</code>.
0853 * @see #JUSTIFICATION
0854 */
0855 public static final Float JUSTIFICATION_FULL = Float.valueOf(1.0f);
0856
0857 /**
0858 * Do not allow the line to be justified.
0859 * @see #JUSTIFICATION
0860 */
0861 public static final Float JUSTIFICATION_NONE = Float.valueOf(0.0f);
0862
0863 //
0864 // For use by input method.
0865 //
0866
0867 /**
0868 * Attribute key for input method highlight styles.
0869 *
0870 * <p>Values are instances of {@link
0871 * java.awt.im.InputMethodHighlight} or {@link
0872 * java.text.Annotation}. The default value is <code>null</code>,
0873 * which means that input method styles should not be applied
0874 * before rendering.
0875 *
0876 * <p>If adjacent runs of text with the same
0877 * <code>InputMethodHighlight</code> need to be rendered
0878 * separately, the <code>InputMethodHighlights</code> should be
0879 * wrapped in <code>Annotation</code> instances.
0880 *
0881 * <p>Input method highlights are used while text is being
0882 * composed by an input method. Text editing components should
0883 * retain them even if they generally only deal with unstyled
0884 * text, and make them available to the drawing routines.
0885 *
0886 * @see java.awt.Font
0887 * @see java.awt.im.InputMethodHighlight
0888 * @see java.text.Annotation
0889 */
0890 public static final TextAttribute INPUT_METHOD_HIGHLIGHT = new TextAttribute(
0891 "input method highlight");
0892
0893 /**
0894 * Attribute key for input method underlines. Values
0895 * are instances of <b><code>Integer</code></b>. The default
0896 * value is <code>-1</code>, which means no underline.
0897 *
0898 * <p>Several constant values are provided, see {@link
0899 * #UNDERLINE_LOW_ONE_PIXEL}, {@link #UNDERLINE_LOW_TWO_PIXEL},
0900 * {@link #UNDERLINE_LOW_DOTTED}, {@link #UNDERLINE_LOW_GRAY}, and
0901 * {@link #UNDERLINE_LOW_DASHED}.
0902 *
0903 * <p>This may be used in conjunction with {@link #UNDERLINE} if
0904 * desired. The primary purpose is for use by input methods.
0905 * Other use of these underlines for simple ornamentation might
0906 * confuse users.
0907 *
0908 * <p>The input method underline affects both the visual bounds and
0909 * the outline of the text.
0910 *
0911 * @since 1.3
0912 */
0913 public static final TextAttribute INPUT_METHOD_UNDERLINE = new TextAttribute(
0914 "input method underline");
0915
0916 /**
0917 * Single pixel solid low underline.
0918 * @see #INPUT_METHOD_UNDERLINE
0919 * @since 1.3
0920 */
0921 public static final Integer UNDERLINE_LOW_ONE_PIXEL = Integer
0922 .valueOf(1);
0923
0924 /**
0925 * Double pixel solid low underline.
0926 * @see #INPUT_METHOD_UNDERLINE
0927 * @since 1.3
0928 */
0929 public static final Integer UNDERLINE_LOW_TWO_PIXEL = Integer
0930 .valueOf(2);
0931
0932 /**
0933 * Single pixel dotted low underline.
0934 * @see #INPUT_METHOD_UNDERLINE
0935 * @since 1.3
0936 */
0937 public static final Integer UNDERLINE_LOW_DOTTED = Integer
0938 .valueOf(3);
0939
0940 /**
0941 * Double pixel gray low underline.
0942 * @see #INPUT_METHOD_UNDERLINE
0943 * @since 1.3
0944 */
0945 public static final Integer UNDERLINE_LOW_GRAY = Integer.valueOf(4);
0946
0947 /**
0948 * Single pixel dashed low underline.
0949 * @see #INPUT_METHOD_UNDERLINE
0950 * @since 1.3
0951 */
0952 public static final Integer UNDERLINE_LOW_DASHED = Integer
0953 .valueOf(5);
0954
0955 /**
0956 * Attribute key for swapping foreground and background
0957 * <code>Paints</code>. Values are instances of
0958 * <b><code>Boolean</code></b>. The default value is
0959 * <code>false</code>, which means do not swap colors.
0960 *
0961 * <p>The constant value {@link #SWAP_COLORS_ON} is defined.
0962 *
0963 * <p>If the {@link #FOREGROUND} attribute is set, its
0964 * <code>Paint</code> will be used as the background, otherwise
0965 * the <code>Paint</code> currently on the <code>Graphics</code>
0966 * will be used. If the {@link #BACKGROUND} attribute is set, its
0967 * <code>Paint</code> will be used as the foreground, otherwise
0968 * the system will find a contrasting color to the
0969 * (resolved) background so that the text will be visible.
0970 *
0971 * @see #FOREGROUND
0972 * @see #BACKGROUND
0973 */
0974 public static final TextAttribute SWAP_COLORS = new TextAttribute(
0975 "swap_colors");
0976
0977 /**
0978 * Swap foreground and background.
0979 * @see #SWAP_COLORS
0980 * @since 1.3
0981 */
0982 public static final Boolean SWAP_COLORS_ON = Boolean.TRUE;
0983
0984 /**
0985 * Attribute key for converting ASCII decimal digits to other
0986 * decimal ranges. Values are instances of {@link NumericShaper}.
0987 * The default is <code>null</code>, which means do not perform
0988 * numeric shaping.
0989 *
0990 * <p>When a numeric shaper is defined, the text is first
0991 * processed by the shaper before any other analysis of the text
0992 * is performed.
0993 *
0994 * <p><em>Note:</em> This should have the same value for all the
0995 * text in the paragraph, otherwise the behavior is undetermined.
0996 *
0997 * @see NumericShaper
0998 * @since 1.4
0999 */
1000 public static final TextAttribute NUMERIC_SHAPING = new TextAttribute(
1001 "numeric_shaping");
1002
1003 /**
1004 * Attribute key to request kerning. Values are instances of
1005 * <b><code>Integer</code></b>. The default value is
1006 * <code>0</code>, which does not request kerning.
1007 *
1008 * <p>The constant value {@link #KERNING_ON} is provided.
1009 *
1010 * <p>The default advances of single characters are not
1011 * appropriate for some character sequences, for example "To" or
1012 * "AWAY". Without kerning the adjacent characters appear to be
1013 * separated by too much space. Kerning causes selected sequences
1014 * of characters to be spaced differently for a more pleasing
1015 * visual appearance.
1016 *
1017 * @since 1.6
1018 */
1019 public static final TextAttribute KERNING = new TextAttribute(
1020 "kerning");
1021
1022 /**
1023 * Request standard kerning.
1024 * @see #KERNING
1025 * @since 1.6
1026 */
1027 public static final Integer KERNING_ON = Integer.valueOf(1);
1028
1029 /**
1030 * Attribute key for enabling optional ligatures. Values are
1031 * instances of <b><code>Integer</code></b>. The default value is
1032 * <code>0</code>, which means do not use optional ligatures.
1033 *
1034 * <p>The constant value {@link #LIGATURES_ON} is defined.
1035 *
1036 * <p>Ligatures required by the writing system are always enabled.
1037 *
1038 * @since 1.6
1039 */
1040 public static final TextAttribute LIGATURES = new TextAttribute(
1041 "ligatures");
1042
1043 /**
1044 * Request standard optional ligatures.
1045 * @see #LIGATURES
1046 * @since 1.6
1047 */
1048 public static final Integer LIGATURES_ON = Integer.valueOf(1);
1049
1050 /**
1051 * Attribute key to control tracking. Values are instances of
1052 * <b><code>Number</code></b>. The default value is
1053 * <code>0</code>, which means no additional tracking.
1054 *
1055 * <p>The constant values {@link #TRACKING_TIGHT} and {@link
1056 * #TRACKING_LOOSE} are provided.
1057 *
1058 * <p>The tracking value is multiplied by the font point size and
1059 * passed through the font transform to determine an additional
1060 * amount to add to the advance of each glyph cluster. Positive
1061 * tracking values will inhibit formation of optional ligatures.
1062 * Tracking values are typically between <code>-0.1</code> and
1063 * <code>0.3</code>; values outside this range are generally not
1064 * desireable.
1065 *
1066 * @since 1.6
1067 */
1068 public static final TextAttribute TRACKING = new TextAttribute(
1069 "tracking");
1070
1071 /**
1072 * Perform tight tracking.
1073 * @see #TRACKING
1074 * @since 1.6
1075 */
1076 public static final Float TRACKING_TIGHT = Float.valueOf(-.04f);
1077
1078 /**
1079 * Perform loose tracking.
1080 * @see #TRACKING
1081 * @since 1.6
1082 */
1083 public static final Float TRACKING_LOOSE = Float.valueOf(.04f);
1084 }
|