java.lang.Objectjava.text.AttributedCharacterIterator.Attribute
java.awt.font.TextAttribute
public final class 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:
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_EXTENDED |
WIDTH_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_RTL |
null (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) |
Field Summary | |
---|---|
static TextAttribute |
BACKGROUND
Attribute key for the paint used to render the background of the text. |
static TextAttribute |
BIDI_EMBEDDING
Attribute key for the embedding level of the text. |
static TextAttribute |
CHAR_REPLACEMENT
Attribute key for a user-defined glyph to display in lieu of the font's standard glyph for a character. |
static TextAttribute |
FAMILY
Attribute key for the font name. |
static TextAttribute |
FONT
Attribute key used to provide the font to use to render text. |
static TextAttribute |
FOREGROUND
Attribute key for the paint used to render the text. |
static TextAttribute |
INPUT_METHOD_HIGHLIGHT
Attribute key for input method highlight styles. |
static TextAttribute |
INPUT_METHOD_UNDERLINE
Attribute key for input method underlines. |
static TextAttribute |
JUSTIFICATION
Attribute key for the justification of a paragraph. |
static Float |
JUSTIFICATION_FULL
Justify the line to the full requested width. |
static Float |
JUSTIFICATION_NONE
Do not allow the line to be justified. |
static TextAttribute |
KERNING
Attribute key to request kerning. |
static Integer |
KERNING_ON
Request standard kerning. |
static TextAttribute |
LIGATURES
Attribute key for enabling optional ligatures. |
static Integer |
LIGATURES_ON
Request standard optional ligatures. |
static TextAttribute |
NUMERIC_SHAPING
Attribute key for converting ASCII decimal digits to other decimal ranges. |
static TextAttribute |
POSTURE
Attribute key for the posture of a font. |
static Float |
POSTURE_OBLIQUE
The standard italic posture. |
static Float |
POSTURE_REGULAR
The standard posture, upright. |
static TextAttribute |
RUN_DIRECTION
Attribute key for the run direction of the line. |
static Boolean |
RUN_DIRECTION_LTR
Left-to-right run direction. |
static Boolean |
RUN_DIRECTION_RTL
Right-to-left run direction. |
static TextAttribute |
SIZE
Attribute key for the font size. |
static TextAttribute |
STRIKETHROUGH
Attribute key for strikethrough. |
static Boolean |
STRIKETHROUGH_ON
A single strikethrough. |
static TextAttribute |
SUPERSCRIPT
Attribute key for superscripting and subscripting. |
static Integer |
SUPERSCRIPT_SUB
Standard subscript. |
static Integer |
SUPERSCRIPT_SUPER
Standard superscript. |
static TextAttribute |
SWAP_COLORS
Attribute key for swapping foreground and background Paints. |
static Boolean |
SWAP_COLORS_ON
Swap foreground and background. |
static TextAttribute |
TRACKING
Attribute key to control tracking. |
static Float |
TRACKING_LOOSE
Perform loose tracking. |
static Float |
TRACKING_TIGHT
Perform tight tracking. |
static TextAttribute |
TRANSFORM
Attribute key for the transform of a font. |
static TextAttribute |
UNDERLINE
Attribute key for underline. |
static Integer |
UNDERLINE_LOW_DASHED
Single pixel dashed low underline. |
static Integer |
UNDERLINE_LOW_DOTTED
Single pixel dotted low underline. |
static Integer |
UNDERLINE_LOW_GRAY
Double pixel gray low underline. |
static Integer |
UNDERLINE_LOW_ONE_PIXEL
Single pixel solid low underline. |
static Integer |
UNDERLINE_LOW_TWO_PIXEL
Double pixel solid low underline. |
static Integer |
UNDERLINE_ON
Standard underline. |
static TextAttribute |
WEIGHT
Attribute key for the weight of a font. |
static Float |
WEIGHT_BOLD
The standard bold weight. |
static Float |
WEIGHT_DEMIBOLD
A moderately lighter weight than WEIGHT_BOLD. |
static Float |
WEIGHT_DEMILIGHT
An intermediate weight between WEIGHT_LIGHT and WEIGHT_STANDARD. |
static Float |
WEIGHT_EXTRA_LIGHT
The lightest predefined weight. |
static Float |
WEIGHT_EXTRABOLD
An extra heavy weight. |
static Float |
WEIGHT_HEAVY
A moderately heavier weight than WEIGHT_BOLD. |
static Float |
WEIGHT_LIGHT
The standard light weight. |
static Float |
WEIGHT_MEDIUM
An intermediate weight between WEIGHT_REGULAR and WEIGHT_BOLD. |
static Float |
WEIGHT_REGULAR
The standard weight. |
static Float |
WEIGHT_SEMIBOLD
A moderately heavier weight than WEIGHT_REGULAR. |
static Float |
WEIGHT_ULTRABOLD
The heaviest predefined weight. |
static TextAttribute |
WIDTH
Attribute key for the width of a font. |
static Float |
WIDTH_CONDENSED
The most condensed predefined width. |
static Float |
WIDTH_EXTENDED
The most extended predefined width. |
static Float |
WIDTH_REGULAR
The standard width. |
static Float |
WIDTH_SEMI_CONDENSED
A moderately condensed width. |
static Float |
WIDTH_SEMI_EXTENDED
A moderately extended width. |
Fields inherited from class java.text. AttributedCharacterIterator.Attribute |
---|
INPUT_METHOD_SEGMENT , LANGUAGE , READING |
Constructor Summary | |
---|---|
protected |
TextAttribute
(
String
name) Constructs a TextAttribute with the specified name. |
Method Summary | |
---|---|
protected Object |
readResolve
() Resolves instances being deserialized to the predefined constants. |
Methods inherited from class java.text. AttributedCharacterIterator.Attribute |
---|
equals , getName , hashCode , toString |
Methods inherited from class java.lang. Object |
---|
clone , finalize , getClass , notify , notifyAll , wait , wait , wait |
Field Detail |
---|
public static final TextAttribute FAMILY
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.
public static final
TextAttribute
WEIGHT
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.
public static final
Float
WEIGHT_EXTRA_LIGHT
public static final
Float
WEIGHT_LIGHT
public static final
Float
WEIGHT_DEMILIGHT
public static final
Float
WEIGHT_REGULAR
public static final
Float
WEIGHT_SEMIBOLD
public static final
Float
WEIGHT_MEDIUM
public static final
Float
WEIGHT_DEMIBOLD
public static final
Float
WEIGHT_BOLD
public static final
Float
WEIGHT_HEAVY
public static final
Float
WEIGHT_EXTRABOLD
public static final
Float
WEIGHT_ULTRABOLD
public static final
TextAttribute
WIDTH
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.
public static final
Float
WIDTH_CONDENSED
public static final
Float
WIDTH_SEMI_CONDENSED
public static final
Float
WIDTH_REGULAR
public static final
Float
WIDTH_SEMI_EXTENDED
public static final
Float
WIDTH_EXTENDED
public static final
TextAttribute
POSTURE
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.
public static final
Float
POSTURE_REGULAR
public static final
Float
POSTURE_OBLIQUE
public static final
TextAttribute
SIZE
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.
public static final
TextAttribute
TRANSFORM
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
TextLayout.getLayoutPath()
.
public static finalTextAttributeWEIGHT
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.
public static finalFloatWEIGHT_EXTRA_LIGHT
public static finalFloatWEIGHT_LIGHT
public static finalFloatWEIGHT_DEMILIGHT
public static finalFloatWEIGHT_REGULAR
public static finalFloatWEIGHT_SEMIBOLD
public static finalFloatWEIGHT_MEDIUM
public static finalFloatWEIGHT_DEMIBOLD
public static finalFloatWEIGHT_BOLD
public static finalFloatWEIGHT_HEAVY
public static finalFloatWEIGHT_EXTRABOLD
public static finalFloatWEIGHT_ULTRABOLD
public static finalTextAttributeWIDTH
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.
public static finalFloatWIDTH_CONDENSED
public static finalFloatWIDTH_SEMI_CONDENSED
public static finalFloatWIDTH_REGULAR
public static finalFloatWIDTH_SEMI_EXTENDED
public static finalFloatWIDTH_EXTENDED
public static finalTextAttributePOSTURE
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.
public static finalFloatPOSTURE_REGULAR
public static finalFloatPOSTURE_OBLIQUE
public static finalTextAttributeSIZE
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.
public static finalTextAttributeTRANSFORM
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, skewing, and translation. In general, large rotations do not produce very useful results. The transform modifies both the glyph and the advance. The translations in the transform are interpreted as a ratio of the point size. That is, with a point size of 12, a translation of 0.5 results in a movement of 6 points.
The advance point of the transformed glyph is the transform of the advance point projected onto the baseline. If the advance ends up to the left (top) of the glyph origin, the two points are swapped.
Example: The point size is 20, the original advance is 10.0, and the transform is a 60 degree counterclockwise rotation plus an offset up and to the right of 0.1, -0.1. The translation results in an offset of <2.0, -2.0>. The original advance point is <10.0, 0.0>; after the rotation it is <6.0, -8.0>; when adding the offset this becomes <8.0,-10.0>, when projecting on the (horizontal) baseline this becomes the new advance point: <8.0, 0.0>. The advance width is the distance from the origin to the advance point: 8.0. The rotated glyph is rendered two points up and to the right of its origin and rotated. This does not affect the baseline for subsequent glyphs.
public static final TextAttribute SUPERSCRIPT
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.
public static final Integer SUPERSCRIPT_SUPER
public static final Integer SUPERSCRIPT_SUB
public static final TextAttribute FONT
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.
public static final TextAttribute CHAR_REPLACEMENT
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.
public static final TextAttribute FOREGROUND
Glyphs will be rendered using this Paint regardless of the Paint value set on the Graphics (but see SWAP_COLORS ).
public static final TextAttribute BACKGROUND
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.
public static final TextAttribute UNDERLINE
The constant value UNDERLINE_ON is provided.
The underline affects both the visual bounds and the outline of the text.
public static final Integer UNDERLINE_ON
public static final TextAttribute STRIKETHROUGH
The constant value STRIKETHROUGH_ON is provided.
The strikethrough affects both the visual bounds and the outline of the text.
public static final Boolean STRIKETHROUGH_ON
public static final TextAttribute RUN_DIRECTION
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.
public static final Boolean RUN_DIRECTION_LTR
public static final Boolean RUN_DIRECTION_RTL
public static final TextAttribute BIDI_EMBEDDING
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.
public static final TextAttribute JUSTIFICATION
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.
public static final Float JUSTIFICATION_FULL
public static final Float JUSTIFICATION_NONE
public static final TextAttribute 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.
public static final TextAttribute INPUT_METHOD_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.
public static final Integer UNDERLINE_LOW_ONE_PIXEL
public static final Integer UNDERLINE_LOW_TWO_PIXEL
public static final Integer UNDERLINE_LOW_DOTTED
public static final Integer UNDERLINE_LOW_GRAY
public static final Integer UNDERLINE_LOW_DASHED
public static final TextAttribute 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.
public static final Boolean SWAP_COLORS_ON
public static final TextAttribute 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.
public static final TextAttribute 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.
public static final Integer KERNING_ON
public static final TextAttribute LIGATURES
The constant value LIGATURES_ON is defined.
Ligatures required by the writing system are always enabled.
public static final Integer LIGATURES_ON
public static final TextAttribute 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.
public static final Float TRACKING_TIGHT
public static final Float TRACKING_LOOSE
Constructor Detail |
---|
protected TextAttribute(String name)
Method Detail |
---|
protected Object readResolve() throws InvalidObjectException