The TextAttribute class defines attribute keys and
attribute values used for text rendering.

TextAttribute instances are used as attribute keys to
identify attributes in
Font,
TextLayout,
AttributedCharacterIterator,
and other classes handling text attributes. Other constants defined
in this class can be used as attribute values.

For each text attribute, the documentation provides:

the type of its value,

the relevant predefined constants, if any

the default effect if the attribute is absent

the valid values if there are limitations

a description of the effect.

Values

The values of attributes must always be immutable.

Where value limitations are given, any value outside of that
set is reserved for future use; the value will be treated as
the default.

The value null is treated the same as the
default value and results in the default behavior.

If the value is not of the proper type, the attribute
will be ignored.

The identity of the value does not matter, only the actual
value. For example, TextAttribute.WEIGHT_BOLD and
new Float(2.0)
indicate the same WEIGHT.

Attribute values of type Number (used for
WEIGHT, WIDTH, POSTURE,
SIZE, JUSTIFICATION, and
TRACKING) can vary along their natural range and are
not restricted to the predefined constants.
Number.floatValue() is used to get the actual value
from the Number.

The values for WEIGHT, WIDTH, and
POSTURE are interpolated by the system, which
can select the 'nearest available' font or use other techniques to
approximate the user's request.

This defines the value passed as name to the
Font constructor. Both logical and physical
font names are allowed. If a font with the requested name
is not found, the default font is used.

Note: This attribute is unfortunately misnamed, as
it specifies the face name and not just the family. Thus
values such as "Lucida Sans Bold" will select that face if it
exists. Note, though, that if the requested face does not
exist, the default will be used with regular weight.
The "Bold" in the name is part of the face name, not a separate
request that the font's weight be bold.

This corresponds to the transform passed to
Font.deriveFont(AffineTransform). Since that
transform is mutable and TextAttribute values must
not be, the TransformAttribute wrapper class is
used.

The primary intent is to support scaling and skewing, though
other effects are possible.

Some transforms will cause the baseline to be rotated and/or
shifted. The text and the baseline are transformed together so
that the text follows the new baseline. For example, with text
on a horizontal baseline, the new baseline follows the
direction of the unit x vector passed through the
transform. Text metrics are measured against this new baseline.
So, for example, with other things being equal, text rendered
with a rotated TRANSFORM and an unrotated TRANSFORM will measure as
having the same ascent, descent, and advance.

In styled text, the baselines for each such run are aligned
one after the other to potentially create a non-linear baseline
for the entire run of text. For more information, see TextLayout.getLayoutPath().

SUPERSCRIPT

Attribute key for superscripting and subscripting. Values are
instances of Integer. The default value is
0, which means that no superscript or subscript is used.

Two constant values are provided, see SUPERSCRIPT_SUPER and SUPERSCRIPT_SUB. These have
the values 1 and -1 respectively. Values of
greater magnitude define greater levels of superscript or
subscripting, for example, 2 corresponds to super-superscript,
3 to super-super-superscript, and similarly for negative values
and subscript, up to a level of 7 (or -7). Values beyond this
range are reserved; behavior is platform-dependent.

SUPERSCRIPT can
impact the ascent and descent of a font. The ascent
and descent can never become negative, however.

SUPERSCRIPT_SUB

FONT

Attribute key used to provide the font to use to render text.
Values are instances of Font. The default
value is null, indicating that normal resolution of a
Font from attributes should be performed.

TextLayout and
AttributedCharacterIterator work in terms of
Maps of TextAttributes. Normally,
all the attributes are examined and used to select and
configure a Font instance. If a FONT
attribute is present, though, its associated Font
will be used. This provides a way for users to override the
resolution of font attributes into a Font, or
force use of a particular Font instance. This
also allows users to specify subclasses of Font in
cases where a Font can be subclassed.

FONT is used for special situations where
clients already have a Font instance but still
need to use Map-based APIs. Typically, there will
be no other attributes in the Map except the
FONT attribute. With Map-based APIs
the common case is to specify all attributes individually, so
FONT is not needed or desireable.

However, if both FONT and other attributes are
present in the Map, the rendering system will
merge the attributes defined in the Font with the
additional attributes. This merging process classifies
TextAttributes into two groups. One group, the
'primary' group, is considered fundamental to the selection and
metric behavior of a font. These attributes are
FAMILY, WEIGHT, WIDTH,
POSTURE, SIZE,
TRANSFORM, SUPERSCRIPT, and
TRACKING. The other group, the 'secondary' group,
consists of all other defined attributes, with the exception of
FONT itself.

To generate the new Map, first the
Font is obtained from the FONT
attribute, and all of its attributes extracted into a
new Map. Then only the secondary
attributes from the original Map are added to
those in the new Map. Thus the values of primary
attributes come solely from the Font, and the
values of secondary attributes originate with the
Font but can be overridden by other values in the
Map.

Note:Font'sMap-based
constructor and deriveFont methods do not process
the FONT attribute, as these are used to create
new Font objects. Instead, Font.getFont(Map) should be used to
handle the FONT attribute.

CHAR_REPLACEMENT

Attribute key for a user-defined glyph to display in lieu
of the font's standard glyph for a character. Values are
intances of GraphicAttribute. The default value is null,
indicating that the standard glyphs provided by the font
should be used.

This attribute is used to reserve space for a graphic or
other component embedded in a line of text. It is required for
correct positioning of 'inline' components within a line when
bidirectional reordering (see Bidi) is
performed. Each character (Unicode code point) will be
rendered using the provided GraphicAttribute. Typically, the
characters to which this attribute is applied should be
\uFFFC.

The GraphicAttribute determines the logical and visual
bounds of the text; the actual Font values are ignored.

STRIKETHROUGH_ON

RUN_DIRECTION

Attribute key for the run direction of the line. Values are
instances of Boolean. The default value is
null, which indicates that the standard Bidi algorithm for
determining run direction should be used with the value Bidi.DIRECTION_DEFAULT_LEFT_TO_RIGHT.

RUN_DIRECTION_RTL

BIDI_EMBEDDING

Attribute key for the embedding level of the text. Values are
instances of Integer. The default value is
null, indicating that the the Bidirectional
algorithm should run without explicit embeddings.

Positive values 1 through 61 are embedding levels,
negative values -1 through -61 are override levels.
The value 0 means that the base line direction is used. These
levels are passed in the embedding levels array to the Bidi constructor.

Note: When this attribute is present anywhere in
a paragraph, then any Unicode bidi control characters (RLO,
LRO, RLE, LRE, and PDF) in the paragraph are
disregarded, and runs of text where this attribute is not
present are treated as though it were present and had the value
0.

JUSTIFICATION

Attribute key for the justification of a paragraph. Values are
instances of Number. The default value is
1, indicating that justification should use the full width
provided. Values are pinned to the range [0..1].

Specifies the fraction of the extra space to use when
justification is requested on a TextLayout. For
example, if the line is 50 points wide and it is requested to
justify to 70 points, a value of 0.75 will pad to use
three-quarters of the remaining space, or 15 points, so that
the resulting line will be 65 points in length.

Note: This should have the same value for all the
text in a paragraph, otherwise the behavior is undetermined.

INPUT_METHOD_HIGHLIGHT

Values are instances of InputMethodHighlight or Annotation. The default value is null,
which means that input method styles should not be applied
before rendering.

If adjacent runs of text with the same
InputMethodHighlight need to be rendered
separately, the InputMethodHighlights should be
wrapped in Annotation instances.

Input method highlights are used while text is being
composed by an input method. Text editing components should
retain them even if they generally only deal with unstyled
text, and make them available to the drawing routines.

If the FOREGROUND attribute is set, its
Paint will be used as the background, otherwise
the Paint currently on the Graphics
will be used. If the BACKGROUND attribute is set, its
Paint will be used as the foreground, otherwise
the system will find a contrasting color to the
(resolved) background so that the text will be visible.

The default advances of single characters are not
appropriate for some character sequences, for example "To" or
"AWAY". Without kerning the adjacent characters appear to be
separated by too much space. Kerning causes selected sequences
of characters to be spaced differently for a more pleasing
visual appearance.

The tracking value is multiplied by the font point size and
passed through the font transform to determine an additional
amount to add to the advance of each glyph cluster. Positive
tracking values will inhibit formation of optional ligatures.
Tracking values are typically between -0.1 and
0.3; values outside this range are generally not
desireable.