Text is rendered as a graphic element similar to paths
and shapes, but with a restricted subset of rendering options. Text
elements are always rendered using a solid fill color, modified
by any opacity, blend mode, and color transformation defined by
parent elements, and clipped to any clipping content defined on
its parent elements. Text content is only filled, not stroked.
To use text in an FXG 2.0 document, use the <RichText> tag.
In FXG 1.0, use the <TextGraphic> tag.
In FXG, the <RichText> tag supports the
following child elements:
<content>
<transform>
To specify text in a <RichText> tag, you
use a single <content> child tag. The following
FXG-based example shows several methods of using text in a <RichText> tag:
The following file defines the JustifiedTextComp FXG component
used in the previous example:
<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/comps/JustifiedTextComp.fxg -->
<Graphic xmlns="http://ns.adobe.com/fxg/2008" version="2">
<RichText textAlign="justify" width="100">
<content>This is a block of text that is justified, so you can see formatting applied.</content>
</RichText>
</Graphic>
The following file defines the FormattedTextComp FXG component
used in the previous example:
<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/comps/FormattedTextComp.fxg -->
<Graphic xmlns="http://ns.adobe.com/fxg/2008" version="2">
<RichText>
<content>This text is <span fontWeight="bold">BOLD</span>,<br/>
this text is <span textDecoration="underline">UNDERLINED</span>,<br/>
and this text is <span fontStyle="italic">ITALIC</span>.
<p>This is a new paragraph.</p></content>
</RichText>
</Graphic>
The <content> child tag supports the following
child elements:
<p>
<span>
<br>
<tcy>
<a>
<img>
<tab>
<linkNormalFormat>
<linkHoverFormat>
<linkActiveFormat>
The <content> child tag can also take
raw text.
If you do not explicitly use a <p> tag
as the first tag in a <content> tag, then
it is implied.
If you apply style attributes to the <RichText> tag
(such as fontFamily="arial"), then the <span> tag
is implied on the content of the <RichText> tag.
The following example has multiple text formats, with one implied
span and one explicit span:
The contents of the <RichText> tag support
a set of style attributes that define formatting. These styles are
a subset of the MXML RichText class. Some styles are applied at
the character and paragraph level, and some are applied at the container
level. Container-level attributes (whose level is listed as including <RichText>),
affect the entire text flow when applied to the container. Paragraph-level
attributes (whose level is listed as including <p>),
affect the paragraph when applied to a <p> tag.
And character-level attributes (whose level is listed as including <span>)
affect only the current span when applied to a <span> tag.
The following table describes the formatting attributes supported
by FXG:
Attribute
Description
Level
alignmentBaseline
Specifies which of the baselines of the
line containing the element the dominantBaseline snaps
to, thus determining the vertical position of the element in the
line.
The default value is useDominantBaseline.
Valid
values are roman, ascent, descent, ideographicTop, ideographicCenter, ideographicBottom,
and useDominantBaseline.
<RichText>, <p>,
or <span>
backgroundAlpha
Alpha (transparency) value for the background.
A value of 0 is fully transparent, and a value of 1 is fully opaque.
The
default value is 1.
<RichText>, <p>,
or <span>
backgroundColor
Background color of the text. Can be either transparent,
or an integer containing three 8-bit RGB components.
The
default value is transparent.
<RichText>, <p>,
or <span>
baselineShift
Indicates the baseline shift for the element
in pixels. The element is shifted perpendicular to the baseline
by this amount. In horizontal text, a positive baseline shift moves
the element up and a negative baseline shift moves the element down.
The
default value is 0.0, indicating no shift.
A value of superscript shifts
the text up by an amount specified in the font, and applies a transform
to the fontSize also based on preferences in the
font.
A value of subscript shifts the text
down by an amount specified in the font, and also transforms the fontSize.
A
percent value shifts the text by a percentage of the fontSize attribute.
The minimum/maximum percent are -1000%/1000%.
A Number shifts
the text by that number of pixels. The minimum/maximum Number values
are -1000/1000.
<RichText>, <p>,
or <span>
blockProgression
Controls the direction in which lines are
stacked. In Latin text, this is tb, because lines
start at the top and proceed downward. In vertical Chinese or Japanese,
this is rl, because lines should start at the right
side of the container and proceed leftward.
Valid values are tb and rl.
<RichText> or <p>
breakOpportunity
Controls where a line can legally break.
Valid values are auto, any, none, or all.
A
value of auto means line breaking opportunities
are based on standard Unicode character properties, such as breaking
between words and on hyphens.
A value of any indicates
that the line may end at any character. This value is typically
used when Roman text is embedded in Asian text and it is desirable
for breaks to happen in the middle of words.
A value of none means
that no characters in the range are treated as line break opportunities.
A
value of all means that all characters in the range
are treated as mandatory line break opportunities; this results
in one character per line.
The default value is auto.
<RichText>, <p>,
or <span>
color
Sets the color of the text.
The default
value is 0x000000.
<RichText>, <p>,
or <span>
columnCount
Defines the number of columns in the RichText
element. The column number overrides the other column settings.
The
value can be an Integer, or auto if unspecified.
If it's an integer, the range of legal values is 0 to 50. If columnCount is
not specified, but columnWidth is, then columnWidth is
used to create as many columns as can fit in the container.
The
default value is auto.
<RichText>
columnGap
Defines th space between columns in pixels.
Does not include space before the first column or after the last
column. Use the padding properties to define that.
Legal
values range from 0 to 1000.
The default value is 0.
<RichText>
columnWidth
Defines the width of columns in pixels.
If you specify the width of the columns, but not the count, Flex
creates as many columns of that width as possible given the the
container width and columnGap settings. Any remainder
space is left after the last column.
Legal values are 0 to
8000.
The default value is auto.
<RichText>
digitCase
Defines the case for digits.
Valid
values are default, lining, and oldStyle.
A
value of default uses the normal digit case from
the font.
A value of lining uses the lining
digit case from the font.
A value of oldStyle uses
the old style digit case from the font.
The default value
is default.
<RichText>, <p>,
or <span>
digitWidth
Specifies how wide digits will be when the
text is set.
Valid values are proportional, tabular,
and default.
A value of proportional means
that the proportional widths from the font are used, and different
digits will have different widths.
A value of tabular means
that every digits has the same width.
A value of default means
that the normal width from the font is used.
The default
value is default.
<RichText>, <p>,
or <span>
direction
Controls the dominant writing direction
for the paragraphs (left-to-right or right-to-left), and how characters
with no implicit writing direction, such as punctuation, are treated.
Valid
values are ltr and rtl.
The
default value is ltr.
<RichText> or <p>
dominantBaseline
Specifies which of the baselines of the
element snaps to the alignmentBaseline to determine the vertical
position of the element on the line.
Valid values are auto, roman, ascent, descent, ideographicTop, ideographicCenter,
and ideographicBottom.
A value of auto gets
resolved based on the textRotation of the span and
the locale of the parent paragraph. A textRotation of rotate270 resolves
to ideographicCenter. A locale of Japanese ("ja")
or Chinese ("zh-XX", "zh_XX", etc), resolves to ideographicCenter,
whereas all others are resolved to roman.
The
default value is auto.
<RichText>, <p>,
or <span>
firstBaselineOffset
Specifies the position of the first line
of text in the container (first in each column) relative to the
top of the container. The first line may appear at the position
of the line's ascent, or below by the lineHeight of
the first line. Or it may be offset by a pixel amount.
Valid
values are auto, ascent, lineHeight,
and a Number.
The default value (auto) specifies that the
line top be aligned to the container top inset. The baseline that
this property refers to is deduced from the container's locale as
follows: ideographicBottom for Chinese and Japanese
locales, roman otherwise.
Minumum/maximum
values are 0/1000.
The default value is auto.
<RichText>
fontFamily
Defines the font family name used to render
the text.
The font depends on the glyphs that are being rendered
and the fonts that are available on the client system.
For
most platforms, the default value is Arial.
<RichText>, <p>, or <span>
fontSize
Sets the size of the glyphs that are used
to render the text, specified in point sizes.
The default
value is 12. The minimum value is 1. The maximum value is 500.
<RichText>, <p>, or <span>
fontStyle
Italicizes text. Valid values are normal and italic.
The
default value is normal.
<RichText>, <p>, or <span>
fontWeight
Bolds text. Valid values are normal and bold.
The
default value is normal.
<RichText>, <p>, or <span>
justificationRule
Defines the justifier.
A value of eastAsian enables
justification for Japanese.
The default value is auto.
A value of auto is resolved based on the locale of
the paragraph.
Values for Japanese ("ja") and Chinese ("zh-XX",
"zh_XX", etc) resolve to eastAsian, while all other
locales resolve to space.
<RichText> or <p>
justificationStyle
Defines the justification style.
A
value of auto is resolved based on the locale of
the paragraph. Currently, all locales resolve to pushInKinsoku,
however, this value is only used in conjunction with a justificationRule value
of eastAsian, so is only applicable to "ja" and
all "zh" locales.
A value of prioritizeLeastAdjustment bases
justification on either expanding or compressing the line, whichever
gives a result closest to the desired width.
A value of pushInKinsoku bases
justification on compressing kinsoku at the end of the line, or
expanding it if there is no kinsoku or if that space is insufficient.
A
value of pushOutOnly bases justification on expanding
the line.
Valid values are auto, prioritizeLeastAdjustment, pushInKinsoku,
and pushOutOnly.
The default value is auto.
<RichText> or <p>
kerning
Applies pair kerning to text.
Valid
values are on, off, and auto.
If on,
pair kerns are honored. If off, there is no font-based
kerning applied. If auto, kerning is applied to
all characters except Kanji, Hiragana or Katakana.
The default
value is auto.
<RichText>, <p>, or <span>
leadingModel
Specifies the leading basis (baseline to
which the lineHeight property refers) and the leading
direction (which determines whether the lineHeight property
refers to the distance of a line's baseline from that of the line
before it or the line after it).
The default value is auto which
is resolved based on locale. Locale values of Japanese ("ja") and
Chinese ("zh-XX", "zh_XX", etc) resolve auto to ideographicTopDown
and other locales resolve to romanUp.
Valid values are auto, romanUp, ideographicTopUp, ideographicCenterUp, ascentDescentUp, ideographicTopDown,
and ideographicCenterDown.
<RichText> or <p>
ligatureLevel
Controls which ligatures in the font will
be used.
Valid values are minimum, common, uncommon,
and exotic.
A value of minimum turns
on rlig, common is rlig + clig + liga; uncommon is
rlig + clig + liga + dlig; exotic is rlig + clig
+ liga + dlig + hlig.
You cannot turn the various ligature
features on independently.
The default value is common.
<RichText>, <p>,
or <span>
lineBreak
Determines whether the text wraps the lines
at the edge of the enclosing <RichText> element.
Set to toFit to wrap the lines. Set to explicit to
break the lines only at a Unicode line end character (such as a
newline or line separator).
Valid values are toFit and explicit.
The
default value is toFit.
<RichText>
lineHeight
Defines the leading, or the distance from
the previous line’s baseline to the current line, in points. This
can be specified in absolute pixels, or as a percentage of the point
size.
The default value is 120%. The minimum value for percent
or number is 0.
<RichText>, <p>, or <span>
lineThrough
Whether to apply a strike through to the
text. Set to true to apply a line through the text;
otherwise set to false.
The default value
is false.
<RichText>, <p>, or <span>
locale
Defines the locale of the text. This controls
case transformations and shaping. Standard locale identifiers as
described in Unicode Technical Standard #35 are used. For example
en, en_US and en-US are all English, ja is Japanese.
Locale
applied at the paragraph and higher level impacts resolution of "auto"
values for dominantBaseline, justificationRule, justificationStyle and leadingModel.
See
individual attributes for resolution values.
<RichText>, <p>,
or <span>
marginBottom
Defines the space after the paragraph. As
in CSS, adjacent vertical space collapses. No margin is necessary
if the paragraph falls at the bottom of the <RichText> tag.
The
default value is 0. The minimum value is 0.
<RichText> or <p>
marginLeft
Defines the indentation applied to the left
edge of the <RichText> tag, measured in pixels.
The
default value is 0.
<RichText> or <p>
marginRight
Defines the indentation applied to the right
edge of the <RichText> tag, measured in pixels.
The
default value is 0.
<RichText> or <p>
marginTop
Defines the space before the paragraph.
As in CSS, adjacent vertical space collapses. Given two adjoining
paragraphs (A, B), where A has marginBottom 12
and B has marginBottom 24, the total space between
the paragraphs is 24, the maximum of the two, and not 36, the sum.
If the paragraph is at the top of the column, no extra space is
left for the margin.
The default value is 0. The minimum value
is 0.
<RichText> or <p>
paddingBottom
Defines the inset from bottom edge to content
area, in pixels.
The default value is 0. The minumum/maximum
values are 0/1000.
<RichText>
paddingLeft
Defines the inset from left edge to content
area, in pixels.
The default value is 0. The minumum/maximum
values are 0/1000.
<RichText>
paddingRight
Defines the inset from right edge to content
area, in pixels.
The default value is 0. The minumum/maximum
values are 0/1000.
<RichText>
paddingTop
Defines the inset from top edge to content
area, in pixels.
The default value is 0. The minumum/maximum
values are 0/1000.
<RichText>
paragraphEndIndent
Defines the indentation applied to the end
edge of a paragraph (right edge if direction is ltr, left edge otherwise).
Measured
in pixels. Legal values range from 0 to 1000.
Default is
0.
<RichText> or <p>
paragraphSpaceAfter
Defines the amount of whitespace that appears
the paragraph. As in CSS, adjacent vertical space collapses (see
note for paragraphSpaceBefore ). No "space after" is necessary if
the paragraph falls at the bottom of the RichText.
Legal
values range from 0 to 1000.
The default value is 0. The
minimum value is 0.
<RichText> or <p>
paragraphSpaceBefore
Specifies the amount of whitespace that
appears above a paragraph. As in CSS, adjacent vertical space collapses.
For two adjoining paragraphs (A, B), where A has paragraphSpaceAfter
12 and B has paragraphSpaceBefore 24, the total space between the
paragraphs will be 24, the maximum of the two, and not 36, the sum.
If the paragraph comes at the top of the column, no extra space
is left before it.
Legal values range from 0 to 1000.
The
default value is 0. The minimum value is 0.
<RichText> or <p>
paragraphStartIndent
Defines the indentation applied to the start
edge of the paragraph (left edge if direction is ltr, right edge
otherwise).
Sets the opacity level of the text, ranging
from 0 (completely transparent) to 1 (completely opaque).
The
default value is 1.
<RichText>, <p>, or <span>
textAlign
Aligns text relative to the text box edges.
Valid values are left, right, center,
and justify.
The default value is left.
<RichText> or <p>
textAlignLast
Aligns the last line of the paragraph.
To
make a paragraph set all lines justified, set the textAlign and textAlignLast attributes
to justify.
Valid values are left, center, right,
and justify.
The default value is left.
<RichText> or <p>
textDecoration
Underlines text. Valid values are none and underline.
The
default value is none.
<RichText>, <p>, or <span>
textIndent
Indent the first line of text in a paragraph.
The indent is relative to the left margin. Measured in pixels.
The
default value is 0. This attribute can be negative.
<RichText> or <p>
textJustify
Applies when justificationRule is
space. A value of interWord spreads justification
space out to spaces in the line. A value of distribute spreads
it out to letters as well as spaces.
The default value is interWord.
Valid
values are interWord and distribute.
<RichText> or <p>
textRotation
Controls the rotation of the text, in ninety
degree increments.
Valid values are auto, rotate0, rotate90, rotate180,
and rotate270.
The default value is auto.
<RichText>, <p>,
or <span>
trackingLeft
Adds space to the left of each character.
Can be a percent value or a Number.
A Number tracks by a pixel
amount, with the minimum/maximum values -100/1000.
A percent
value is the percentage of the fontSize attribute.
Legal values for percentages are -100% to 1000%.
Negative
values bring characters closer together.
The default value
is 0.
<RichText>, <p>, or <span>
trackingRight
Adds space to the right of each character.
Can be a percent value or a Number.
A Number tracks by a pixel
amount, with the minimum/maximum values -100/1000.
A percent
value is the percentage of the fontSize attribute.
Legal values for percentages are -100% to 1000%.
Negative
values bring characters closer together.
The default value
is 0.
<RichText>, <p>, or <span>
typographicCase
Controls the case in which the text appears.
Valid
values are default, capsToSmallCaps, uppercase, lowercase,
and lowercaseToSmallCaps.
A value of default does
not apply any case changes.A value of smallCaps converts
all characters to uppercase and applies c2sc.
A value of uppercase and lowercase are
case conversions.A value of caps turns on case.A
value of lowercaseToSmallCaps converts all characters
to uppercase, and for those characters which have been converted,
applies c2sc.
The default value is default.
<RichText>, <p>,
or <span>
verticalAlign
Sets the vertical alignment of the lines
within the container.
Valid values are top, middle, bottom, justify,
and inherit.
The lines might appear at the
top of the container, centered within the container, at the bottom,
or evenly spread out across the depth of the container.
The
default value is top.
<RichText>
whiteSpaceCollapse
Determines how whitespace such as line feeds,
newlines, and tabs are treated.
Valid values are collapse and preserve.
Set
to collapse to convert line feeds, newlines, and
tabs to spaces, collapse adjacent spaces to one, and trim leading
and trailing whitespace.
Set to preserve to
maintain whitespace without changes.
<RichText>, <p>, or <span>
Not all of the properties in MXML text-based controls are supported
by the <RichText> tag in FXG, and not all
properties of FXG are supported by the MXML text-based controls.
For example, the RichText class in MXML does not have the margin-related
properties that the <RichText> tag in FXG
has.
The <RichText> tag is not optimized when
an FXG document is compiled. It is the only FXG element that is
not optimized because there are no low-level Flash Player instructions
for RichText.
If you do not specify a the width or height properties
of the <RichText> tag, or if the specified
width or height is 0, the width and height are calculated based
on the text content. This is done using the following logic for
horizontal text:
If the width is specified, but the height
is not, the container height is set to the height required to fit
the text. Text wraps to the width of the container, and the total
height of the text becomes the container height.
If the width is not specified, then the text breaks only
at line breaks and at the paragraph end. The width of the container
is then set to the width of the longest line.
If neither width nor height are specified, the width is set
as described above, and then the height is set based on the width.
If the height is specified, and the text exceeds what will
fit, then the remaining text is preserved but does not appear in
the container; it is clipped. You can choose to add scroll bars
to view the additional text, but scroll bars are not part of FXG.
