java.lang.Object | ||
↳ | java.text.AttributedCharacterIterator.Attribute | |
↳ | java.awt.font.TextAttribute |
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:
null
is treated the same as the
default value and results in the default behavior.
TextAttribute.WEIGHT_BOLD
and
new Float(2.0)
indicate the same WEIGHT
.
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
.
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.
Key
Value Type
Principal Constants
Default Value
FAMILY
String
See Font
DIALOG
,
DIALOG_INPUT
,
SERIF
,
SANS_SERIF
, and MONOSPACED
.
"Default" (use platform default)
WEIGHT
Number
WEIGHT_REGULAR, WEIGHT_BOLD
WEIGHT_REGULAR
WIDTH
Number
WIDTH_CONDENSED, WIDTH_REGULAR,
WIDTH_EXTENDEDWIDTH_REGULAR
POSTURE
Number
POSTURE_REGULAR, POSTURE_OBLIQUE
POSTURE_REGULAR
SIZE
Number
none
12.0
TRANSFORM
TransformAttribute
See TransformAttribute
IDENTITY
TransformAttribute.IDENTITY
SUPERSCRIPT
Integer
SUPERSCRIPT_SUPER, SUPERSCRIPT_SUB
0 (use the standard glyphs and metrics)
FONT
Font
none
null (do not override font resolution)
CHAR_REPLACEMENT
GraphicAttribute
none
null (draw text using font glyphs)
FOREGROUND
Paint
none
null (use current graphics paint)
BACKGROUND
Paint
none
null (do not render background)
UNDERLINE
Integer
UNDERLINE_ON
-1 (do not render underline)
STRIKETHROUGH
Boolean
STRIKETHROUGH_ON
false (do not render strikethrough)
RUN_DIRECTION
Boolean
RUN_DIRECTION_LTR
RUN_DIRECTION_RTLnull (use
Bidi
standard default)
BIDI_EMBEDDING
Integer
none
0 (use base line direction)
JUSTIFICATION
Number
JUSTIFICATION_FULL
JUSTIFICATION_FULL
INPUT_METHOD_HIGHLIGHT
InputMethodHighlight
,Annotation
(see class)
null (do not apply input highlighting)
INPUT_METHOD_UNDERLINE
Integer
UNDERLINE_LOW_ONE_PIXEL,
UNDERLINE_LOW_TWO_PIXEL-1 (do not render underline)
SWAP_COLORS
Boolean
SWAP_COLORS_ON
false (do not swap colors)
NUMERIC_SHAPING
NumericShaper
none
null (do not shape digits)
KERNING
Integer
KERNING_ON
0 (do not request kerning)
LIGATURES
Integer
LIGATURES_ON
0 (do not form optional ligatures)
TRACKING
Number
TRACKING_LOOSE, TRACKING_TIGHT
0 (do not add tracking)
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
BACKGROUND | Attribute key for the paint used to render the background of the text. | ||||||||||
BIDI_EMBEDDING | Attribute key for the embedding level of the text. | ||||||||||
CHAR_REPLACEMENT | Attribute key for a user-defined glyph to display in lieu of the font's standard glyph for a character. | ||||||||||
FAMILY | Attribute key for the font name. | ||||||||||
FONT | Attribute key used to provide the font to use to render text. | ||||||||||
FOREGROUND | Attribute key for the paint used to render the text. | ||||||||||
INPUT_METHOD_HIGHLIGHT | Attribute key for input method highlight styles. | ||||||||||
INPUT_METHOD_UNDERLINE | Attribute key for input method underlines. | ||||||||||
JUSTIFICATION | Attribute key for the justification of a paragraph. | ||||||||||
JUSTIFICATION_FULL | Justify the line to the full requested width. | ||||||||||
JUSTIFICATION_NONE | Do not allow the line to be justified. | ||||||||||
KERNING | Attribute key to request kerning. | ||||||||||
KERNING_ON | Request standard kerning. | ||||||||||
LIGATURES | Attribute key for enabling optional ligatures. | ||||||||||
LIGATURES_ON | Request standard optional ligatures. | ||||||||||
NUMERIC_SHAPING | Attribute key for converting ASCII decimal digits to other decimal ranges. | ||||||||||
POSTURE | Attribute key for the posture of a font. | ||||||||||
POSTURE_OBLIQUE | The standard italic posture. | ||||||||||
POSTURE_REGULAR | The standard posture, upright. | ||||||||||
RUN_DIRECTION | Attribute key for the run direction of the line. | ||||||||||
RUN_DIRECTION_LTR | Left-to-right run direction. | ||||||||||
RUN_DIRECTION_RTL | Right-to-left run direction. | ||||||||||
SIZE | Attribute key for the font size. | ||||||||||
STRIKETHROUGH | Attribute key for strikethrough. | ||||||||||
STRIKETHROUGH_ON | A single strikethrough. | ||||||||||
SUPERSCRIPT | Attribute key for superscripting and subscripting. | ||||||||||
SUPERSCRIPT_SUB | Standard subscript. | ||||||||||
SUPERSCRIPT_SUPER | Standard superscript. | ||||||||||
SWAP_COLORS | Attribute key for swapping foreground and background
Paints . |
||||||||||
SWAP_COLORS_ON | Swap foreground and background. | ||||||||||
TRACKING | Attribute key to control tracking. | ||||||||||
TRACKING_LOOSE | Perform loose tracking. | ||||||||||
TRACKING_TIGHT | Perform tight tracking. | ||||||||||
TRANSFORM | Attribute key for the transform of a font. | ||||||||||
UNDERLINE | Attribute key for underline. | ||||||||||
UNDERLINE_LOW_DASHED | Single pixel dashed low underline. | ||||||||||
UNDERLINE_LOW_DOTTED | Single pixel dotted low underline. | ||||||||||
UNDERLINE_LOW_GRAY | Double pixel gray low underline. | ||||||||||
UNDERLINE_LOW_ONE_PIXEL | Single pixel solid low underline. | ||||||||||
UNDERLINE_LOW_TWO_PIXEL | Double pixel solid low underline. | ||||||||||
UNDERLINE_ON | Standard underline. | ||||||||||
WEIGHT | Attribute key for the weight of a font. | ||||||||||
WEIGHT_BOLD | The standard bold weight. | ||||||||||
WEIGHT_DEMIBOLD | A moderately lighter weight than WEIGHT_BOLD . |
||||||||||
WEIGHT_DEMILIGHT | An intermediate weight between WEIGHT_LIGHT and
WEIGHT_STANDARD . |
||||||||||
WEIGHT_EXTRABOLD | An extra heavy weight. | ||||||||||
WEIGHT_EXTRA_LIGHT | The lightest predefined weight. | ||||||||||
WEIGHT_HEAVY | A moderately heavier weight than WEIGHT_BOLD . |
||||||||||
WEIGHT_LIGHT | The standard light weight. | ||||||||||
WEIGHT_MEDIUM | An intermediate weight between WEIGHT_REGULAR and
WEIGHT_BOLD . |
||||||||||
WEIGHT_REGULAR | The standard weight. | ||||||||||
WEIGHT_SEMIBOLD | A moderately heavier weight than WEIGHT_REGULAR . |
||||||||||
WEIGHT_ULTRABOLD | The heaviest predefined weight. | ||||||||||
WIDTH | Attribute key for the width of a font. | ||||||||||
WIDTH_CONDENSED | The most condensed predefined width. | ||||||||||
WIDTH_EXTENDED | The most extended predefined width. | ||||||||||
WIDTH_REGULAR | The standard width. | ||||||||||
WIDTH_SEMI_CONDENSED | A moderately condensed width. | ||||||||||
WIDTH_SEMI_EXTENDED | A moderately extended width. |
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.text.AttributedCharacterIterator.Attribute
|
Protected Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a
TextAttribute with the specified name. |
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Resolves instances being deserialized to the predefined constants.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.text.AttributedCharacterIterator.Attribute
| |||||||||||
From class
java.lang.Object
|
Attribute key for the paint used to render the background of
the text. Values are instances of Paint
.
The default value is null, indicating that the background
should not be rendered.
The logical bounds of the text will be filled using this
Paint
, and then the text will be rendered on top
of it (but see SWAP_COLORS
).
The visual bounds of the text is extended to include the logical bounds, if necessary. The outline is not affected.
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.
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.
Attribute key for the font name. Values are instances of
String
. The default value is
"Default"
, which causes the platform default font
family to be used.
The Font
class defines constants for the logical
font names
DIALOG
,
DIALOG_INPUT
,
SANS_SERIF
,
SERIF
, and
MONOSPACED
.
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.
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's
Map
-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.
Attribute key for the paint used to render the text. Values are
instances of Paint
. The default value is
null, indicating that the Paint
set on the
Graphics2D
at the time of rendering is used.
Glyphs will be rendered using this
Paint
regardless of the Paint
value
set on the Graphics
(but see SWAP_COLORS
).
Attribute key for input method highlight styles.
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.
Attribute key for input method underlines. Values
are instances of Integer
. The default
value is -1
, which means no underline.
Several constant values are provided, see UNDERLINE_LOW_ONE_PIXEL
, UNDERLINE_LOW_TWO_PIXEL
,
UNDERLINE_LOW_DOTTED
, UNDERLINE_LOW_GRAY
, and
UNDERLINE_LOW_DASHED
.
This may be used in conjunction with UNDERLINE
if
desired. The primary purpose is for use by input methods.
Other use of these underlines for simple ornamentation might
confuse users.
The input method underline affects both the visual bounds and the outline of the text.
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].
The constants JUSTIFICATION_FULL
and JUSTIFICATION_NONE
are provided.
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.
Justify the line to the full requested width. This is the
default value for JUSTIFICATION
.
Attribute key to request kerning. Values are instances of
Integer
. The default value is
0
, which does not request kerning.
The constant value KERNING_ON
is provided.
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.
Attribute key for enabling optional ligatures. Values are
instances of Integer
. The default value is
0
, which means do not use optional ligatures.
The constant value LIGATURES_ON
is defined.
Ligatures required by the writing system are always enabled.
Attribute key for converting ASCII decimal digits to other
decimal ranges. Values are instances of NumericShaper
.
The default is null
, which means do not perform
numeric shaping.
When a numeric shaper is defined, the text is first processed by the shaper before any other analysis of the text is performed.
Note: This should have the same value for all the text in the paragraph, otherwise the behavior is undetermined.
Attribute key for the posture of a font. Values are instances
of Number
. The default value is
POSTURE_REGULAR
.
Two constant values are provided, POSTURE_REGULAR
and POSTURE_OBLIQUE
. The value
POSTURE_OBLIQUE
corresponds to the style value
Font.ITALIC
as passed to the Font
constructor.
The value is roughly the slope of the stems of the font, expressed as the run over the rise. Positive values lean right.
The system can interpolate the provided value.
This will affect the font's italic angle as returned by
Font.getItalicAngle
.
The standard posture, upright. This is the default value for
POSTURE
.
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 DIRECTION_DEFAULT_LEFT_TO_RIGHT
.
The constants RUN_DIRECTION_RTL
and RUN_DIRECTION_LTR
are provided.
This determines the value passed to the Bidi
constructor to select the primary direction of
the text in the paragraph.
Note: This attribute should have the same value for all the text in a paragraph, otherwise the behavior is undetermined.
Attribute key for the font size. Values are instances of
Number
. The default value is 12pt.
This corresponds to the size
parameter to the
Font
constructor.
Very large or small sizes will impact rendering performance, and the rendering system might not render text at these sizes. Negative sizes are illegal and result in the default size.
Note that the appearance and metrics of a 12pt font with a 2x transform might be different than that of a 24 point font with no transform.
Attribute key for strikethrough. Values are instances of
Boolean
. The default value is
false
, which means no strikethrough.
The constant value STRIKETHROUGH_ON
is provided.
The strikethrough affects both the visual bounds and the outline of the text.
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.
Attribute key for swapping foreground and background
Paints
. Values are instances of
Boolean
. The default value is
false
, which means do not swap colors.
The constant value SWAP_COLORS_ON
is defined.
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.
Attribute key to control tracking. Values are instances of
Number
. The default value is
0
, which means no additional tracking.
The constant values TRACKING_TIGHT
and TRACKING_LOOSE
are provided.
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.
Attribute key for the transform of a font. Values are
instances of TransformAttribute
. The
default value is TransformAttribute.IDENTITY
.
The TransformAttribute
class defines the
constant IDENTITY
.
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 getLayoutPath()
.
Attribute key for underline. Values are instances of
Integer
. The default value is -1, which
means no underline.
The constant value UNDERLINE_ON
is provided.
The underline affects both the visual bounds and the outline of the text.
Attribute key for the weight of a font. Values are instances
of Number
. The default value is
WEIGHT_REGULAR
.
Several constant values are provided, see WEIGHT_EXTRA_LIGHT
, WEIGHT_LIGHT
, WEIGHT_DEMILIGHT
, WEIGHT_REGULAR
, WEIGHT_SEMIBOLD
, WEIGHT_MEDIUM
, WEIGHT_DEMIBOLD
, WEIGHT_BOLD
, WEIGHT_HEAVY
,
WEIGHT_EXTRABOLD
, and WEIGHT_ULTRABOLD
. The
value WEIGHT_BOLD
corresponds to the
style value Font.BOLD
as passed to the
Font
constructor.
The value is roughly the ratio of the stem width to that of the regular weight.
The system can interpolate the provided value.
An intermediate weight between WEIGHT_LIGHT
and
WEIGHT_STANDARD
.
An intermediate weight between WEIGHT_REGULAR
and
WEIGHT_BOLD
.
The standard weight. This is the default value for WEIGHT
.
Attribute key for the width of a font. Values are instances of
Number
. The default value is
WIDTH_REGULAR
.
Several constant values are provided, see WIDTH_CONDENSED
, WIDTH_SEMI_CONDENSED
, WIDTH_REGULAR
, WIDTH_SEMI_EXTENDED
, WIDTH_EXTENDED
.
The value is roughly the ratio of the advance width to that of the regular width.
The system can interpolate the provided value.
The standard width. This is the default value for
WIDTH
.
Constructs a TextAttribute
with the specified name.
name | the attribute name to assign to this
TextAttribute
|
---|
Resolves instances being deserialized to the predefined constants.
InvalidObjectException |
---|