Java Doc for TextAttribute.java in  » 6.0-JDK-Core » AWT » java » awt » font » Java Source Code / Java DocumentationJava Source Code and Java Documentation

TextAttribute instances are used as attribute keys to identify attributes in java.awt.Font Font , java.awt.font.TextLayout TextLayout , java.text.AttributedCharacterIterator 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.

Summary of attributes

Key	Value Type	Principal Constants	Default Value
TextAttribute.FAMILY	String	See Font java.awt.Font.DIALOG DIALOG , java.awt.Font.DIALOG_INPUT DIALOG_INPUT , java.awt.Font.SERIF SERIF , java.awt.Font.SANS_SERIF SANS_SERIF , and java.awt.Font.MONOSPACED MONOSPACED .	"Default" (use platform default)
TextAttribute.WEIGHT	Number	WEIGHT_REGULAR, WEIGHT_BOLD	WEIGHT_REGULAR
TextAttribute.WIDTH	Number	WIDTH_CONDENSED, WIDTH_REGULAR, WIDTH_EXTENDED	WIDTH_REGULAR
TextAttribute.POSTURE	Number	POSTURE_REGULAR, POSTURE_OBLIQUE	POSTURE_REGULAR
TextAttribute.SIZE	Number	none	12.0
TextAttribute.TRANSFORM	TransformAttribute	See TransformAttribute TransformAttribute.IDENTITY IDENTITY	TransformAttribute.IDENTITY
TextAttribute.SUPERSCRIPT	Integer	SUPERSCRIPT_SUPER, SUPERSCRIPT_SUB	0 (use the standard glyphs and metrics)
TextAttribute.FONT	java.awt.Font	none	null (do not override font resolution)
TextAttribute.CHAR_REPLACEMENT	GraphicAttribute	none	null (draw text using font glyphs)
TextAttribute.FOREGROUND	java.awt.Paint	none	null (use current graphics paint)
TextAttribute.BACKGROUND	java.awt.Paint	none	null (do not render background)
TextAttribute.UNDERLINE	Integer	UNDERLINE_ON	-1 (do not render underline)
TextAttribute.STRIKETHROUGH	Boolean	STRIKETHROUGH_ON	false (do not render strikethrough)
TextAttribute.RUN_DIRECTION	Boolean	RUN_DIRECTION_LTR RUN_DIRECTION_RTL	null (use java.text.Bidi standard default)
TextAttribute.BIDI_EMBEDDING	Integer	none	0 (use base line direction)
TextAttribute.JUSTIFICATION	Number	JUSTIFICATION_FULL	JUSTIFICATION_FULL
TextAttribute.INPUT_METHOD_HIGHLIGHT	java.awt.im.InputMethodHighlight , java.text.Annotation	(see class)	null (do not apply input highlighting)
TextAttribute.INPUT_METHOD_UNDERLINE	Integer	UNDERLINE_LOW_ONE_PIXEL, UNDERLINE_LOW_TWO_PIXEL	-1 (do not render underline)
TextAttribute.SWAP_COLORS	Boolean	SWAP_COLORS_ON	false (do not swap colors)
TextAttribute.NUMERIC_SHAPING	java.awt.font.NumericShaper	none	null (do not shape digits)
TextAttribute.KERNING	Integer	KERNING_ON	0 (do not request kerning)
TextAttribute.LIGATURES	Integer	LIGATURES_ON	0 (do not form optional ligatures)
TextAttribute.TRACKING	Number	TRACKING_LOOSE, TRACKING_TIGHT	0 (do not add tracking)

See Also:   java.awt.Font
See Also:   
See Also:   java.awt.font.TextLayout
See Also:   java.text.AttributedCharacterIterator
See Also:   

Values are instances of java.awt.im.InputMethodHighlight or java.text.Annotation .

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 TextAttribute.SWAP_COLORS ).

The visual bounds of the text is extended to include the logical bounds, if necessary. The outline is not affected.
See Also:   java.awt.Paint
See Also:   TextAttribute.SWAP_COLORS
See Also:   

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 java.text.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.
See Also:   java.text.Bidi
See Also:   

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 java.text.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.
See Also:   GraphicAttribute
See Also:   

The Font class defines constants for the logical font names java.awt.Font.DIALOG DIALOG , java.awt.Font.DIALOG_INPUT DIALOG_INPUT , java.awt.Font.SANS_SERIF SANS_SERIF , java.awt.Font.SERIF SERIF , and java.awt.Font.MONOSPACED 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.

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, java.awt.Font.getFont(Map) Font.getFont(Map) should be used to handle the FONT attribute.
See Also:   java.awt.Font
See Also:   

Glyphs will be rendered using this Paint regardless of the Paint value set on the Graphics (but see TextAttribute.SWAP_COLORS ).
See Also:   java.awt.Paint
See Also:   TextAttribute.SWAP_COLORS
See Also:   

Values are instances of java.awt.im.InputMethodHighlight or java.text.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.
See Also:   java.awt.Font
See Also:   java.awt.im.InputMethodHighlight
See Also:   java.text.Annotation
See Also:   

Several constant values are provided, see TextAttribute.UNDERLINE_LOW_ONE_PIXEL , TextAttribute.UNDERLINE_LOW_TWO_PIXEL , TextAttribute.UNDERLINE_LOW_DOTTED , TextAttribute.UNDERLINE_LOW_GRAY , and TextAttribute.UNDERLINE_LOW_DASHED .

This may be used in conjunction with TextAttribute.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.
since:
   1.3

The constants TextAttribute.JUSTIFICATION_FULL and TextAttribute.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.
See Also:   TextLayout.getJustifiedLayout
See Also:   

The constant value TextAttribute.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.
since:
   1.6

The constant value TextAttribute.LIGATURES_ON is defined.

Ligatures required by the writing system are always enabled.
since:
   1.6

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.
See Also:   NumericShaper
since:
   1.4

Two constant values are provided, TextAttribute.POSTURE_REGULAR and TextAttribute.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.
See Also:   java.awt.Font.getItalicAngle
See Also:   

The constants TextAttribute.RUN_DIRECTION_RTL and TextAttribute.RUN_DIRECTION_LTR are provided.

This determines the value passed to the java.text.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.
See Also:   java.text.Bidi
See Also:   

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.

The constant value TextAttribute.STRIKETHROUGH_ON is provided.

The strikethrough affects both the visual bounds and the outline of the text.

Two constant values are provided, see TextAttribute.SUPERSCRIPT_SUPER and TextAttribute.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.

The constant value TextAttribute.SWAP_COLORS_ON is defined.

If the TextAttribute.FOREGROUND attribute is set, its Paint will be used as the background, otherwise the Paint currently on the Graphics will be used. If the TextAttribute.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.
See Also:   TextAttribute.FOREGROUND
See Also:   TextAttribute.BACKGROUND
See Also:   

The constant values TextAttribute.TRACKING_TIGHT and TextAttribute.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.
since:
   1.6

The TransformAttribute class defines the constant TransformAttribute.IDENTITY 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 .

The constant value TextAttribute.UNDERLINE_ON is provided.

The underline affects both the visual bounds and the outline of the text.

Several constant values are provided, see TextAttribute.WEIGHT_EXTRA_LIGHT , TextAttribute.WEIGHT_LIGHT , TextAttribute.WEIGHT_DEMILIGHT , TextAttribute.WEIGHT_REGULAR , TextAttribute.WEIGHT_SEMIBOLD , TextAttribute.WEIGHT_MEDIUM , TextAttribute.WEIGHT_DEMIBOLD , TextAttribute.WEIGHT_BOLD , TextAttribute.WEIGHT_HEAVY , TextAttribute.WEIGHT_EXTRABOLD , and TextAttribute.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.

Several constant values are provided, see TextAttribute.WIDTH_CONDENSED , TextAttribute.WIDTH_SEMI_CONDENSED , TextAttribute.WIDTH_REGULAR , TextAttribute.WIDTH_SEMI_EXTENDED , TextAttribute.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.