has at least one that can be implied. Character sequences that are direct children of

are in an implied .

Allowed children are <tcy>, , , ,
, <tab>, <linknormalformat>, <linkhoverformat>, <linkactiveformat>, and raw text.</linkactiveformat></linkhoverformat></linknormalformat></tab></tcy>

An element represents a link, for associating a uri with text in a paragraph. A link element may have a uri (attribute), a set of rollover formats (child tags), and a set of attributes used for indicating a link that has been activated.

Allowed children: <tcy>, , ,
, <tab>, <linknormalformat>, <linkhoverformat>, <linkactiveformat>, and raw text. Note that links do not nest, so this is not legal:
</linkactiveformat></linkhoverformat></linknormalformat></tab></tcy>My <tcy>TCY </tcy>NESTEDLINKLINK
The link format tags (see below) must be the first children in the containing element. Link formats must be defined before the anchor text spans.

The following attributes are specific to the element:

Link format elements contain one and only one TextLayoutFormat child that specifies the formatting attributes that will be applied to any links within the parent element, depending on the link state.

Below is an example of a link specified in this way:

<a href="http://www.4literature.net/Nathaniel_Hawthorne/Ethan_Brand/"                                  target="_self">
<linkHoverFormat><TextLayoutFormat color="#ff0000"/></linkHoverFormat>
<linkActiveFormat><TextLayoutFormat color="#00ff00" textDecoration="underline"/></linkActiveFormat>
<linkNormalFormat><TextLayoutFormat color="#0000ff"/></linkNormalFormat>
<span>Ethan Brand</span>
</a>

If these link format elements are children of an ancestor element (for instance, the TextFlow) instead of the link element itself, they will be inherited by all links in the ancestor.

Link formats may contain TextLayoutFormat children.

TextLayoutFormat Element

A TextLayoutFormat may appear in a link format element (linkNormalFormat, linkActiveFormat, or linkHoverFormat), and is used to hold the formatting attributes for the link format. A TextLayoutFormat may have any formatting attribute and only the Character-level Attributes are applied to link format elements. TextLayoutFormats have no children.

tcy Element

This is used for holding text that is tate-chu-yoko; horizontal text within a vertical text flow. A tcy element may appear in a horizontal text flow, but it will not appear rotated relative to the text flow. Traditionally, it is used to make small blocks of non-Japanese text or numbers, such as dates, more readable. tcy can be applied to horizontal text, but has no effect on drawing style unless and until it is turned vertically.

Allowed children: , , ,
, <tab>, <linknormalformat>, <linkhoverformat>, <linkactiveformat>, and raw text. TCY elements may not be nested, so the following is illegal:
<tcy>TCY</tcy></linkactiveformat></linkhoverformat></linknormalformat></tab>LINK<tcy>NESTED TCY</tcy>

img Element

An element is used for specifying a graphic that appears in the text. The images will appear inline in the text, as if they were a special character. An image may appear as the content of a paragraph, a link, or a tcy element.

Allowed children: none

The following attributes are specific to the element:

* width<number,percent or="" "auto"=""> - How wide the image will be considered to be. This affects how much space is left for it in the text. If a Percent, its a percentage of the measured or default width.
* height<number,percent or="" "auto"=""> - How wide the image will be considered to be. This affects how much space is left for it in the text. If a Percent, its a percentage of the measured or default height.
* source<string> - image source. Usually a string containing the uri to the image. When compiling, it is possible for this to be an embed directive. Paths to images are either absolute or relative to the SWF and not the markup content file. The source attribute is optional. </string></number,percent></number,percent>

Suggest changing the description of the source attribute to say that interpretation is up to the client, but the intended usage is as a uri that specifies the location of the image.

span Element

All character sequences in the <content> value are contained in one or more elements. Explicit span elements can be used for formatting runs of characters within a paragraph. A may appear in a </content>

or implied paragraph, and within a <tcy> or . A element can be empty.</tcy>

<RichText fontSize="14" textIndent="15" paddingTop="4" paddingLeft="4">
  <format name="english" locale="en" fontFamily="Minion Pro"/>
  <content>
    <p paragraphSpaceAfter="15"><span>This is supposed to use the default font</span></p>

    <p paragraphSpaceAfter="15"><span format="english">This is supposed to be in Minion Pro via a named format</span></p>

    <p><span fontFamily="Minion Pro">This is supposed to be in Minion Pro via a fontFamily attribute</span></p>
  </content>
</RichText>

A RichText element defines a text box, specified in the parent Group element's coordinate space, to contain the provided text. The text box is specified using the x/y and width/height attributes on the RichText element.

When you measure the text, it has a logical extent that is calculated using the font metrics. When you draw, it inks pixels. The pixels that are inked don't exactly correspond to the logical bounds because characters can hang over the left or right edge. Hanging over the left edge can happen, for instance, for a capital "J" where the hook on the J typically extends leftwards. Hanging over the right edge can also happen, notably if the text is italic. Calculations of the text box dimensions are done based on the logical extent and not the inked bounds.

The a href="RichText">RichText element automatically clips the text rendering to the bounds of the text box.
[[ note title=u'Implementation Note' ]]
Text is clipped in TLF clients if the logical bounds of the text, as calculated based on font metrics, exceeds the bounds of the text box. If the logical bounds falls within the text box, no clipping is applied. This is an optimization because clipping is expensive in the Flash Player. This means that you may have text whose logical bounds falls within the text box, but whose ink bounds falls outside. In these cases, for example characters with a left side bearing like "J" or italic characters that draw to the right, will not be clipped. If the logical bounds exceeds the text box, for instance, because all the lines don't fit, that's the situation where clipping is applied.
[[ /note ]]
If no width/height is specified on the RichText element, or if the specified width or height is 0, a width and height is 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 (i.e., 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. Note that the client can choose to add scroll bars to view the additional text, but scroll bars are not part of FXG.

For vertical text, all the logic remains the same, but switch width and height in the preceding description.

You should note the following: - This is not an optimal fit case where the width is calculated to fit a specified height. - There are some cases where width and/or height are not specified and a large amount of incoming text is supplied. In this case, the client must determine a reasonable break off point for how much of the text to compose before setting the width and height in order to avoid slowdowns.

Fidelity

It is a non-goal to preserve appearance or layout between clients. The meaning of the text is preserved, and the attributes that are understood by the client are preserved, but the text will re-layout for each client. The lines breaks are likely to be different, what glyphs are used to render the text can be different, the fonts used can be different. The clients preserve the meaning of the text, and the logical settings, and use them to drive the layout according to their own rules. Hence a text snippet that can be five lines in one client, could be three in a different client, and seven in still another one.

Text Rendering

Text is rendered as a graphic element similar to paths and shapes, but with a restricted subset of rendering options. RichText 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. RichText content is only filled, not stroked.

With Flash Player 10, previous problems rendering text in device fonts with containers that have been rotated or skewed are fixed, and alpha with device text also works.

Font References

FXG documents refer to fonts via their family name in the fontFamily attribute of the RichText tag. It is the processor's job to resolve font family names to font implementations, typically using the local machine's installed font list. FXG 1.0 does not support the ability to refer directly to a font definition file on disk. Fonts in FXG are always by name; fonts cannot be embedded or linked to FXG. All applications using FXG should have consistent mechanisms for mapping from the font reference to a font installed in the host OS or editing application.

Units of Measurement 

FXG has based its text functionality as that which is defined within TLF. TLF processes text-related units as pixel values, as opposed to points. Attribute values like fontSize, lineHeight and trackingRight/trackingLeft are all calculated based on pixel values. It is up to the FXG processor to do any point-to-pixel conversions such that the values written out are accurate based on pixels.

Text Character Set

The full Unicode 5.0 character set is supported, including surrogate characters and Unicode control characters. Support for characters is, however, dependent on the font that is being used for rendering. Please consult the Unicode spec for more information (http://unicode.org/versions/Unicode5.0.0/). For info specifically on the Unicode control characters, see http://www.unicode.org/versions/Unicode5.0.0/ch16.pdf.

Entity support applies to all of FXG. The following standard XML entities are supported: lt, gt, quot, apos, and amp.

Whitespace Handling

The problem here is how to tell which characters in the text are there for pretty-printing the XML, and which should really be considered as part of the text content. Flex counts all characters that appear in the text content as actual desired text content. XHTML takes a different approach and assumes that users can add newlines, tabs, and spaces that are really only there for viewing and editing the file in XML, and they don't want to see the characters in the actual text when displayed in the document. This is controlled with the whiteSpaceCollapse property.

For example, these two snippets are equivalent:

<RichText fontFamily="Verdana" fontWeight="bold" whiteSpaceCollapse="collapse">
    <content>
        <p>First para,
        separated into
        several lines in the XML.</p>
        <p>Second para.</p>
    </content>
</RichText>

The whitespace (indenting and newlines) inside the

...

<RichText fontFamily="Verdana" fontWeight="bold" whiteSpaceCollapse="preserve">
    <content><p><span>First para, separated into several lines in the XML.</span><p><span>Second para.</span></p></content>
</RichText>

Note that the newlines in the original XML snippet turned into single spaces.

The
tag is used most often in collapse mode, to ensure that linebreaks happen where intended. For example, suppose you started with this snippet:

<RichText fontFamily="Verdana" fontWeight="bold">
<content>
    <p>First line.

    Second line.</p>
</content>
</RichText>

The intention is to have a line separated by two linebreaks, followed by a second line. However, because the default value of the whiteSpaceCollapse attribute on RichText is 'collapse', the newlines are replaced by a single space. The following is an equivalent snippet:

<RichText fontFamily="Verdana" fontWeight="bold" whiteSpaceCollapse="preserve">
<content>
    <p><span>First line. Second line.</span></p>
</content>
</RichText>

To get the desired results, you must use explicit
tags.

<RichText fontFamily="Verdana" fontWeight="bold">
<content>
    <p>First line.<br/>
    <br/>
    Second line.</p>
</content>
</RichText>

If a Unicode line separator character appears as a character in the paragraph, it is treated exactly the same as a
.
[[ note ]] DELETE THIS PARA: Note that FXG has no support for tab settings. It is up to the client to determine how to display tabs that come in text where collapseWhitespace is false.
[[ /note ]]

Text Formatting

Formatting properties are set directly on the element as XML attributes. Properties can be inherited from the parent, but they are not applied in styles as in CSS. Any formatting attribute can be applied to any text element (RichText, div, p, span, a, tcy).

Inheritance Model

Most attributes inherit by default, so if an element does not explicitly define an attribute, its value will be inherited from its parent. Attributes that do not inherit are marked as non-inheriting in the attribute's description. In order to get inheritance of a non-inheriting attribute, you can set its value to explicitly to "inherit". The value of "inherit" is ignored when used in a RichText attribute; the attribute gets its schema-defined default value (equivalent to omitting the attribute). The value of "inherit" is ignored when used with an inheriting attribute; the attribute gets its inherited default value (equivalent to omitting the attribute).

Formatting Attributes

Character-level Attributes

The following attributes can be applied to any text element and affect the lowest level (span level) of the text, except where noted.

• fontFamily <string>: The font family name used to render the text. The font family name may also be a comma-delimited list of font families, in which case the client should evaluate them in order. If no font is supplied, the client will pick one that is a variant of the Arial family, dependent on platform. Which font is used for rendering the text is up to the client and also depends on the glyphs that are being rendered and the fonts that are available. Default value is Arial.</string>
• fontSize <number>: The size of the glyphs that is used to render the text, specified in pixels. Default is 12. Minimum 1 pixel. Maximum 720 pixels.</number>
• fontStyle <string> (normal, italic): The style of the glyphs that is used to render the text. Legal values are 'normal' and 'italic'. Default is normal.</string>
• fontWeight <string>(normal, bold): The boldness or lightness of the glyphs that is used to render the text. Default is normal.</string>
• lineHeight <percent> | <number>: The distance from the baseline of the previous or the next line to the baseline of the current line is equal to the maximum amount of the leading applied to any character in the line. This is either a number or a percent. This can be specified in absolute pixels, or as a percentage. Default is 120%. Minimum/maximum value for number is -720/720, Minimum/maximum value percent is -1000%/1000%.</number></percent>
• textDecoration <string> (none, underline): The decoration to apply to the text. Default is none.</string>
• lineThrough <boolean>: true if text has strikethrough applied, false otherwise. Default is false.</boolean>
• color <color>: The color of the text. Default is #000000.</color>
• textAlpha <alpha>: The alpha value applied to the text. Default is 1.0.</alpha>
• whiteSpaceCollapse <string> (preserve, collapse): This is an enumerated value. A value of "collapse" converts line feeds, newlines, and tabs to spaces and collapses adjacent spaces to one. See Text collapse examples for details on collapse handling. Updated:-Leading and trailing whitespace is trimmed. A value of "preserve" passes whitespace through unchanged,except as noted earlier, when the whitespace would result in an implied

  and that is all whitespace, in which case the whitespace is removed. Default is collapse.

  </string>
• kerning <string> (on, off, 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 is auto. Otherwise characters are drawn with no pair kerning adjustments.</string>
• backgroundAlpha<alpha>. Alpha (transparency) value for the background. A value of 0 is fully transparent, and a value of 1 is fully opaque. Default value is 1. backgroundAlpha is non-inheriting.</alpha>
• backgroundColor<color, transparent="">. Background color of the text. Can be either transparent, or an integer containing three 8-bit RGB components. Default is transparent. backgroundColor is non-inheriting.</color,>
• baselineShift<number, percent,="" superscript,="" subscript="">. 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. Percent shifts the text by a percentage of the fontSize. Minimum/maximum are -1000/1000, min/max percentage values are -1000%/1000%.</number,>
• breakOpportunity<auto, any,="" none,="" all="">. Controls where a line can legally break. Auto means line breaking opportunities are based on standard Unicode character properties, such as breaking between words and on hyphens. 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. None means that no characters in the range are treated as line break opportunities. All means that all characters in the range are treated as mandatory line break opportunities, so you get one character per line. Useful for creating effects like text on a path. Default is auto.</auto,>
• digitCase<string>(default, lining, oldStyle). Default uses the normal digit case from the font. Lining uses the lining digit case from the font. oldStyle uses the old style digit case from the font. Default is "default".</string>
• digitWidth<string>(default, proportional, tabular). Specifies how wide digits will be when the text is set. Proportional means that the proportional widths from the font are used, and different digits will have different widths. Tabular means that every digits has the same width. Default means that the normal width from the font is used. Default is "default".</string>
• dominantBaseline<auto, roman,="" ascent,="" descent,="" ideographictop,="" ideographiccenter,="" ideographicbottom="">. Specifies which of the baselines of the element snaps to the alignmentBaseline to determine the vertical position of the element on the line. 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. Default is auto.</auto,>
• alignmentBaseline<roman, ascent,="" descent,="" ideographictop,="" ideographiccenter,="" ideographicbottom,="" usedominantbaseline="">. 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. Default is useDominantBaseline.</roman,>
• ligatureLevel<minimum, common,="" uncommon,="" exotic="">. The ligature level used for this text. Controls which ligatures in the font will be used. Minimum turns on rlig, common is rlig + clig + liga, uncommon is rlig + clig + liga + dlig, exotic is rlig + clig + liga + dlig + hlig. There is no way to turn the various ligature features on independently. Default is common.</minimum,>
• locale<string>. The locale of the text. 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.</string>
• typographicCase<default, capstosmallcaps,="" uppercase,="" lowercase,="" lowercasetosmallcaps="">. Controls the case in which the text will appear.
  • default is "normal" for the font that's chosen - i.e., its what you get without applying any features or case changes.
  • smallCaps converts all characters to uppercase and applies c2sc.
  • uppercase and lowercase are case conversions.
  • caps turns on case.
  • lowercaseToSmallCaps converts all characters to uppercase, and for those characters which have been converted, applies c2sc.
  </default,>

Default is default.

• textRotation<auto, rotate0,="" rotate90,="" rotate180,="" rotate270="">. The rotation of the text, in ninety degree increments. Default is auto.</auto,>
• trackingLeft <number, percent="">: space added to the left of each character. A Number tracks by a pixel amount, minimum/maximum values -100/1000. Percent is a percent of the current fontSize, and may be negative, to bring characters closer together. Legal values for percentages are -100% to 1000%. Default is 0.</number,>
• trackingRight <number, percent="">: space added to the right of each character. A Number tracks by a pixel amount, minimum/maximum values -100/1000. Percent is a percent of the current fontSize, and may be negative, to bring characters closer together. Legal values for percentages are -100% to 1000%. Default is 0.</number,>

Paragraph-level Attributes

The following formatting attributes can be applied to any element, and affect the formatting of paragraphs, except where noted. Applying these attributes to elements contained within the paragraph (a, tcy, span) is legal but will not affect the text, since the appearance of the paragraphs is driven by the value of these attributes on the paragraph element itself (note that the values may have been applied via inheritance from a parent element). An FXG 2.0 processor MAY ignore attributes applied to non-paragraph level tags (a, tcy, span) and MAY discard those attributes in round-tripping scenarios.

• textAlign <string> (start, end, left, center, right, justify): The alignment of the text relative to the text box edges. "start" is the edge specified by the direction property - left for direction="ltr", right for direction="rtl". Likewise "end" will be the right edge if direction="ltr", and the left edge if direction="rtl". Default is start.</string>
• textAlignLast <string> (start, end, left, center, right, justify): The alignment of the last line of the paragraph, applies if textAlign is justify. To make a paragraph set all lines justified, set textAlign and textAlignLast to justify. Default is start.</string>
• textIndent <number>: The indentation of the first line of text in a paragraph. The indent is relative to the start edge. Measured in pixels. Default is 0. Can be negative. Minimum/maximum values are -1000/1000.</number>
• paragraphStartIndent <number \|="" inherit="">: The indentation applied to the start edge (left edge if direction is ltr, right edge otherwise). Measured in pixels. Legal values range from 0 to 1000. Default is 0.</number>
• paragraphEndIndent <number \|="" inherit="">: The indentation applied to the end edge (right edge if direction is ltr, left edge otherwise). Measured in pixels. Legal values range from 0 to 1000. Default is 0.</number>
• paragraphSpaceBefore <number \|="" inherit="">. This is the "space before" the 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; I think this is different than CSS. Legal values range from 0 to 1000. Default is 0. Minimum is 0.</number>
• paragraphSpaceAfter <number \|="" inherit="">: This is the "space after" 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. Default is 0. Minimum is 0.</number>
• justificationRule<auto, space,="" eastasian="">. Set up the justifier. EastAsian will turn on justification for Japanese. Default is auto. An 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.</auto,>
• justificationStyle<auto, prioritizeleastadjustment,="" pushinkinsoku,="" pushoutonly="">. An 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. PrioritizeLeastAdjustment bases justification on either expanding or compressing the line, whichever gives a result closest to the desired width. 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. PushOutOnly bases justification on expanding the line. Default is auto.</auto,>
• textJustify<interword, distribute="">. Default is interWord. Applies when justificationRule is space. interWord spreads justification space out to spaces in the line. distribute spreads it out to letters as well as spaces.</interword,>

The algorithm in the Player for how the adjustments are divided between spaces and letters when textJustify is set to distribute is to apply as much as possible to the spaces, where the optimal width of a justifying space is the width of the space glyph in the font, and it can go down to 1/2 that width and up to 2x that width.

• leadingModel<auto, romanup,="" ideographictopup,="" ideographiccenterup,="" ascentdescentup,="" ideographictopdown,="" ideographiccenterdown="">. Specifies the leading basis (baseline to which the lineHeight property refers) and the leading direction (which determines whether lineHeight property refers to the distance of a line's baseline from that of the line before it or the line after it). Default 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.</auto,>
• tabStops <array>. Array of tab stops. By default there are no tabs. Each tab stop has a:
  • position in pixels, relative to the start of the line;
  • alignment<start, center,="" end,="" decimal="">.</start,>
  • decimalAlignmentToken<string>. Used when you want to align the text with a particular character or substring within it (for instance, to a decimal point).</string>
  </array>

In TLF markup, tabStops take the following condensed string-based form: A sequence of tab stops, where each tab stop is delimited by one or more spaces. Tab stops may appear in any order (do not need to be sorted by position). A tab stop takes the following string-based form: <alignment type=""><alignment position="">|<alignment token="">. The alignment type is a single character, and can be S, E, C, or D (or lower-case equivalents): S/s for start, E/e for end, C/c for center, D/d for decimal. The alignment type is optional, and if it is not specified will default to S. The alignment position is a Number, and is specified according to FXG spec for Numbers (decimal or scientific notation). The alignment position is required. The vertical bar is used to separate the alignment position from the alignment token, and should only be present if the alignment token is present. The alignment token is optional if the alignment type is D, and should not be present if the alignment type is anything other than D. The alignment token may be any sequence of characters terminated by the space that ends the tab stop (for the last tab stop, the terminating space is optional; end of alignment token is implied). A space may be part of the alignment token is it escaped with a backslash. A backslash may be part of the alignment token if it is escaped with another backslash. If the alignment type is D, and the alignment token is not specified, it will take on the default value of '.'.\
[[ note title=u'Implementation Note' ]]When using <tab>, <tabstop> should be assigned a value. If not, results are undefined in the current implementation of some products.
[[ /note ]]blockProgression has been moved from Paragraph Attributes to RichText Attributes.\</tabstop></tab></alignment></alignment></alignment>

* direction <string> (ltr, rtl): Controls the dominant writing direction for the paragraph (left-to-right or right-to-left), and how characters with no implicit writing direction, such as punctuation, are treated. Also controls the direction of the columns, which are set according to the value of the direction attribute of the RichText element. Default is left-to-right.</string>

Container-level attributes

These attributes can be applied to any text element, but when applied to the RichText element they affect the entire text flow. They are expected on RichText and div tags. Applying them to other text elements has no effect. An FXG 2.0 processor MAY ignore attributes applied to other text elements and MAY discard those attributes in round-tripping scenarios.

• blockProgression <string> (tb, rl): 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. (Note, post FXG 1.0 lockdown, the 'lr' value was removed. Some FXG processors may still reference the lr value).</string>

* paddingLeft <number>: Inset from left edge to content area. Units in pixels, defaults to 0. Minumum/maximum values 0/1000. Non-inheriting.
* paddingRight <number>: Inset from right edge to content area. Units in pixels, defaults to 0. Minumum/maximum values 0/1000. Non-inheriting.
* paddingTop <number>: Inset from top edge to content area. Units in pixels, defaults to 0. Minumum/maximum values 0/1000. Non-inheriting.
* paddingBottom <number>: Inset from bottom edge to content area. Units in pixels, defaults to 0. Minumum/maximum values 0/1000. Non-inheriting.
* columnGap<number>. Space between columns in pixels. Does not include space before the first column or after the last column - that is padding. Legal values range from 0 to 1000. Default value is 0. columnGap is non-inheriting. </number></number></number></number></number>

• columnCount<auto, integer="">. Number of columns. The column number overrides the other column settings. Value is 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. columnCount is non-inheriting. Default is auto.</auto,>
• columnWidth<auto, number="">. Width of columns in pixels. If you specify the width of the columns, but not the count, TextLayout will create 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. Default is auto. columnWidth is non-inheriting.</auto,>
• firstBaselineOffset<auto, ascent,="" lineheight,="" number="">. 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. 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 0/1000. Default is auto.</auto,>
• verticalAlign<top, middle,="" bottom,="" justify,="" inherit="">. Vertical alignment of the lines within the container. The lines may appear at the top of the container, centered within the container, at the bottom, or evenly spread out across the depth of the container. Default is top. verticalAlign is non-inheriting.</top,>
• lineBreak <string> (toFit, explicit): This is an enumeration. A value of "toFit" wraps the lines at the edge of the enclosing RichText. A value of "explicit" breaks the lines only at a Unicode line end character (such as a newline or line separator). toFit is the default. lineBreak is a non-inheriting attribute.</string>

RichText Attributes

This section moved to Rich element

Bitmaps

FXG uses bitmap images in two ways---either as the source data to fill a shape or path, or as a graphic element in its own right via the BitmapImage element.  

Source Formats

FXG supports the following image file formats as sources for BitmapImage or BitmapFill elements:

• GIF
• PNG
• JPG

Specifying a Source File

For both BitmapImage and BitmapFill elements, the source image data is defined using the source attribute. The source attribute is a required attribute.

The source attribute is specified using an @Embed directive. The format is:

source="@Embed('<imagefilename>')"</imagefilename>

The image filename can be either a fully qualified file, url, or a relative path rooted in the same location as the FXG file. The '/' is the only legal directory separator.

FXG bitmap data is always assumed to be 32bit RGBA.  If the source data doesn't contain an alpha channel, the bitmap is assumed to be completely opaque.

BitmapImage Element

A BitmapImage element defines a rectangular region in its parent element's coordinate space, filled with bitmap data drawn from a source file.

Rendering 

The BitmapImage element renders its source image into a rectangle defined in its parent coordinate system.  The default image rectangle has its top/left at the origin, with its width/height defaulting to the size of the source image. The image rectangle can be modified by setting the width/height attributes on the BitmapImage element.

A BitmapImage is identical to a Rectangle element with the same width and height, with no stroke and a BitmapFill applied.  \

Filling

The fillMode attribute controls how it fills the rectangle defined by the width and height of the BitmapImage. Legal values are: 

• scale (default):  the source image is scaled horizontally and vertically to fill the rectange.
• clip:  the source image is clipped to the bounds of the rectangle.  Pixels outside the natural bounds of the source image are left transparent.
• repeat:  the source image is tiled to fill the rectangle.

As with other shape fills, the image is further modified by any transforms defined on the BitmapImage or its parents.\
\

Attributes

• x <number>: The left edge of the image rectangle, in the parent coordinate system. Defaults to 0.</number>
• y <number>: The top edge of the image rectangle, in the parent coordinate system. Defaults to 0.</number>
• width <number>: The width of the image rectangle, in the parent coordinate system. Defaults to the width of the source image data.</number>
• height <number>: The height of the image rectangle, in the parent coordinate system. Defaults to the height of the source image data.</number>
• rotation <number>: Defaults to 0</number>
• scaleX <number>: Defaults to 1</number>
• scaleY <number>: Defaults to 1</number>
• fillMode <string> (scale, clip, repeat): Defaults to scale</string>
• source <embed reference="">: An embedded reference to the file defining the image data to render. Must be a PNG, JPG, or GIF file.  Required attribute, no default.
• visible <boolean>: Whether or not the BitmapImage is visible. Defaults to true.</boolean>
• alpha <number>: Defaults to 1</number>
• blendMode <string> (add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, overlay, screen, shader, subtract, colordodge, colorburn, exclusion, softlight, hue, saturation, color, luminosity, auto): Defaults to auto</string>

Children

FXG Fills, Strokes, Visibility and Blend Modes

Paths and basic shapes can be filled (which means painting the interior of the object) and stroked (which means painting along the outline of the object). Filling and stroking both can be thought of in more general terms as painting operations.

With FXG, you can fill a path or shape with:

• a solid color
• a solid color with opacity
• a gradient (linear or radial)
• a bitmap image (possibly tiled)

You can stroke a path or shape with:

• a solid color
• a solid color with opacity
• a gradient (linear or radial)

Fills

Paths and shapes are by default left unfilled. To create a filled shape, the element must have a child element of type fill. The fill element must have a single child element that must be one of the fill types listed below.  The following example specifies a solid red color fill for a rectangle:

<Rect x="20" y="20" width="300" height="300">
    <fill>
        <SolidColor color="#FF0000" />
    </fill>
</Rect>

FXG shapes and paths are always filled with an even-odd fill rule. This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and counting the number of path segments from the given shape that the ray crosses. If this number is odd, the point is inside and is filled; if even, the point is outside.

Fills, Strokes, and Transforms 

Fills and strokes generally define a default bounding area that they fill, clipped by the path they are filling.  Fills and strokes can define their own user coordinate space, which defaults to the coordinate space of the object they are filling.  A fill or stroke can modify its coordinate space with transform attributes and child elements, similar to a Group, that is concatenated with its parent element's transforms to define a fill region in document coordinates.

Applying a scale-9 effect to a fill complicates the way in which the fill is transformed. See the Scale 9 section for more details. 

SolidColor Element

The SolidColor element fills a path or shape with a single solid color or solid color with opacity.

Children

None.

Attributes

• alpha <number>: A real number value ranging from 0 to 1 specifying the opacity of the fill, with 1 being opaque. Defaults to 1.</number>
• color <color>: An RGB value (in the form #RRGGBB) that defines the single color value to fill the shape with. Defaults to #000000.</color>

LinearGradient

The LinearGradient element fills a path or shape with a continuously smooth color transition between a list of colors along a vector. 

The gradient vector is the vector stretching from (0,0) to (1, 1), in the coordinate space of the shape's parent grouping element's coordinate system, transformed by any matrix transformation defined on the LinearGradient.

LinearGradient Transform

The gradient vector can be modified using either discreet transform attributes on the LinearGradient element, or by providing an explicit 2D matrix transform as a child element. discreet transform attributes are useful for hand authoring, or for runtime manipulation of the gradient.  The child matrix element is useful for tools, and for more complex transforms than can be expressed by the discreet attributes.

The discreet transform attributes x, y, scaleX, and rotation are combined at runtime, if specified, to create a transform matrix that is applied to the vector stretching from (0,0) to (0,1). The vector is first scaled in the X direction by scaleX, rotated by rotation, and translated by x/y. 

Alternatively, the LinearGradient can optionally have a child element of type matrix. If this child element exists, it must have a single child element of type Matrix.  If the fill defines discreet transform attributes, they replace only that component of the default transform matrix. For example, if only the scaleX is defined, only the scaleX portion of the default transform matrix is replaced. If the x is defined, the tx portion of the default transform matrix is replaced.

It is illegal to define both discreet transform attributes and child matrix element on the same LinearGradient. 

The Default Transform

By default, a LinearGradient is transformed to fill the bounding box of the shape being filled. The gradient vector is first scaled by the width of the bounding box, rotating it around the z axis by 0, then translating it in the horizontal/vertical by the centerpoint of the bounding box.  This lets FXG define gradient fills on shapes that are dynamically modified at runtime, without requiring the runtime code to know how the shape is filled.

Any discreet transform attribute specified on the gradient overrides only that portion of the default transform.  For example, consider the following gradient:

<Rect width="200" height="100">
    <fill>
        <LinearGradient scaleX="100"/>
    <fill>
</Rect>

This example renders a rectangle whose center 100 pixels are filled with the gradient (the translation still takes place).

spreadMethod

LinearGradient elements support three methods for determining the fill colors for pixels that lay outside the gradient vector:

• pad: Pixels take on the color of the closest point on the gradient vector.
• reflect: The gradient is repeated infinitely, reversing its direction with each repeat.
• repeat: The gradient is repeated infinitely.

Gradient Entries

The colors, opacities, and their positions used in the gradient vector are defined by the GradientElement children of the LinearGradient element. These children must appear in positional order; namely, for any child GradientEntry element, its ratio attribute must be higher than the ratio attribute of the previous GradientEntry sibling.

See the GradientEntry section for more details.

Children

• GradientEntry
• matrix

Attributes

• x <number>: The horizontal translation of the gradient transform that defines the horizontal center of the gradient.</number>
• y <number>: The vertical translation of the gradient transform that defines the vertical center of the gradient.</number>
• scaleX <number>: The horizontal scale of the gradient transform that defines the width of the (unrotated) gradient.</number>
• rotation <number> (<angle>): The rotation of the gradient transform.</angle></number>
• spreadMethod <string> (pad, reflect, repeat): How to choose the fill of pixels outside the gradient vector.</string>
• interpolationMethod <string> (rgb, linearRGB): How to interpolate between entries of the gradient.</string>

RadialGradient

The RadialGradient element fills a path or shape with a continuously smooth color transition between a list of colors along the radius of a circle.

The circle used is the circle bounded by the box stretching from (-0.5, -0.5) to (0.5,0.5). Like LinearGradient, it is transformed by the matrix transform defined on the gradient.

RadialGradient supports all the same transform attributes and child elements that LinearGradient does. Additionally, because its rendering is defined by a box and not just a horizontal vector, it supports a scaleY attribute that is used along with scaleX to scale the bounding box before the other transform attributes are applied.

RadialGradient elements also define the attribute focalPointRatio. This defines where along the horizontal axis (of the untransformed box) the focal point of the radial gradient lies. A value of 1 places it at the right hand edge of the box (at 0.5,0). A value of -1 places it at the left hand edge of the box (at -0.5,0).

RadialGradient elements use child GradientEntry elements the same way LinearGradient elements do.

Children

• GradientEntry
• matrix

Attributes

• x <number>: The horizontal translation of the gradient transform that defines the horizontal center of the gradient.</number>
• y <number>: The vertical translation of the gradient transform that defines the vertical center of the gradient.</number>
• scaleX <number>: The horizontal scale of the gradient transform that defines the width of the (unrotated) gradient.</number>
• scaleY <number>: The vertical scale of the gradient transform that defines the width of the (unrotated) gradient.</number>
• rotation <number> (<angle>): The rotation of the gradient transform.</angle></number>
• spreadMethod <string> (pad, reflect, repeat): How to choose the fill of pixels outside the gradient vector.</string>
• interpolationMethod <string> (rgb, linearRGB): How to interpolate between entries of the gradient.</string>
• focalPointRatio <number>: The placement of the focal point of the radial gradient along the horizontal center axis of the gradient bounding box. A value of 1 lies against the right edge of the box; a value of -1 lies against the left edge. The default value of 0 places it in the middle of the box.</number>

BitmapFill

The BitmapFill element fills a path or shape with an optionally scaled, clipped or repeated bitmap image. By default, the bitmap image is scaled to fill the bounding box of the shape or path being filled.

Filling

The fillMode attribute controls how the image data is applied to the fill rectangle. Legal values are:

• scale (default): the default fillMode transform is modified so the source image data fills the untransformed fill rectangle. scaleX = bounding rectangle width / source image width, and scaleY = bounding rectangle height / source image height. These default values can be explicitly overridden by applying an explicit transform (see below).
• clip: the source image is clipped to the path being filled. Pixels outside the natural bounds of the source image are left unpainted.
• repeat: the source image is tiled to fill the element's bounding rectangle.

Transform

The fill rectangle can be modified using either discrete transform attributes on the BitmapFill element, or by providing an explicit 2D matrix transform as a child element. Discrete transform attributes are useful for hand authoring, or for runtime manipulation of the fill rectangle. The child matrix element is useful for tools, and for more complex transforms that cannot be expressed by the discrete attributes.
The discrete transform attributes x, y, scaleX, scaleY, and rotation are combined at runtime, if specified, to create a transform matrix that is applied to the default fill rectangle. The attributes are combined into a transform by:

• Scale by scaleX, scaleY
• Rotate by rotation
• Translate by x,y

Alternatively, the BitmapFill can optionally have a child element of type matrix. If this child element exists, it must have a single child element of type Matrix.  If the matrix child element is defined, it replaces the entire default transform applied to the fill rectangle. 

It is illegal to define both discreet transform attributes and child matrix element on the same BitmapFill.  \ The fill rectangle extends from 0, 0 to width, height of the image bounds.
The default transform applied to the fill rectangle depends on the fillMode used:

• scale: the default transform is constructed so the bitmap fills the bounding box of the path or shape being filled. This is equivalent to setting the scaleX and scaleY parameters to shape width/image width, shape height/image height.
• clip: the default transform is the identity.
• repeat: the default transform is the identity.

Any discrete transform attribute specified on the gradient overrides only that portion of the default transform.

Scaled BitmapFill renders any pixels outside the transformed bounds of the source image as transparent.

Setting the Source Data

The Image data for a bitmap fill is specified by setting the source attribute of the element to point to an external bitmap file. The source attribute is a required attribute. The bitmap file must be in one of the supported bitmap formats for FXG, and must be specified using Embed() syntax. See the Bitmap section for more details on supported formats. TheEmbed() syntax is described in the basic types section.

Children

• matrix

Attributes

• x <number>: The horizontal translation of the transform that defines the horizontal center of the gradient.</number>
• y <number>: The vertical translation of the transform that defines the vertical center of the gradient.</number>
• scaleX <number>: The horizontal scale of the transform that defines the width of the (unrotated) gradient.</number>
• scaleY <number>: The vertical scale of the transform that defines the width of the (unrotated) gradient.</number>
• rotation <number> (<angle>): The rotation of the transform.</angle></number>
• source <embedded bitmap="">: A reference to the file containing the image data to use as fill. }Required attribute.</embedded>
• fillMode <string> (scale, clip, repeat): Default is scale</string>

Strokes

Paths and shapes are by default left unstroked. To create a stroked shape, the element must have a child element of type 'stroke'. The stroke element must have a single child element that must be one of the stroke types listed below.  To specify a solid red color stroke for a rectangle, for example:

<Rect x="20" y="20" width="300" height="300">
    <stroke>
        <SolidColorStroke color="#FF0000" />
    </stroke>
</Rect>

General Stroke Properties

Weight

A stroke applied to a shape or path paints a filled region along the screen whose midpoint lies directly on the on the path. The width of the stroke is defined in pixels by the weight property. Strokes with a transformed weight less than 1 are always rounded up to a single pixel weight when rendered.

The paint of the stroke is defined to be at a higher depth than the paint of any fill applied to the shape. This means that if the stroke is painted with a non-opaque value, the fill is seen beneath the half of the stroke that overlaps the shape.

The stroke is painted as though it were a filled shape itself, defined by the silhouette of the stroke region. This means that where the stroke overlaps itself, it is only painted a single time. Specifically, if the stroke is painted with a non-opaque value, the overlapping region will appear the same as a non-overlapping region rather than as a region painted twice with semi-transparent paint.

The default weight of any stroke is 1 pixel. A stroke weight of 0 pixels is treated as a "hairline" stroke. Rendering a 0-weight stroke is device dependant, however in Flash, a "hairline" stroke is drawn as a 1 pixel stroke that never scales regardless if the path or shape is scaled.

Additionally, anti-aliasing of strokes is device dependent. However, in Flash, vertical and horizontal strokes are always pixel snapped, which results in no anti-aliasing. Strokes following a non-vertical or non-horizontal orientation will be anti-aliased.  

Scale Mode

A stroke is extrapolated from a path or shape after the points have been converted into document coordinate space.  Generally, the local transform of the shape isn't applied to the stroke. However, during painting, the weight of the paint applied to the transformed shape is adjusted to match the scale factor in the shape's transform matrix. How the scale factor affects the weight of the stroke is controlled by the stroke's scale mode. Strokes support the following scale modes:

• normal: Scale the stroke outline using the scale component of the current coordinate transformation.
• none: No scale is applied to the stroke weight.
• vertical: The weight of the stroke is scaled by the vertical scale component of the transform applied to the shape. The horizontal scale component has no effect on the stroke weight.
• horizontal: The weight of the stroke is scaled by the horizontal scale component of the transform applied to the shape. The vertical scale component has no effect on the stroke weight.

When the weight is scaled, a processor first extracts the x and y scale factor from the stroke's user space composite matrix (sx,sy) and transforms the weight w, as the following example shows:

t = sqrt(((wsx)^2 + (wsy)^2) / 2)
weight_in_document_space = Max(1,t);

When the scaleMode attribute is set to horizontal, the sy value in the above equation is constant at 1.  When the scaleMode attribute is set to vertical, the sx value is held constant at 1.

End Caps

FXG strokes support three types of end caps when painting strokes, specified with the caps attribute. Legal values are:

• none: The stroke ends exactly where the path ends.
• round: The stroke end is capped with a half circle whose diameter matches the weight of the stroke.
• square: The stroke end is capped with a half square whose side-length matches the weight of the stroke.

Joint Style

FXG strokes support three ways of rendering the joints between path segments, specified with the joints attribute. Legal values are:

• bevel: The joint is capped by the line running through the joint perpendicular to the line bisecting the joint angle.
• miter: The joint is rendered by slicing the stroke of the two joining segments with the outer edge of the opposite segment's stroke.
• round: The joint is rendered with a circle whose diameter matches the weight of the stroke centered on the joint.

FXG strokes also support the miterLimit attribute. This is a numeric value that imposes a limit on the ratio between the miter length and the stroke weight. When the limit is exceeded, the join is clipped at the miterLimit. Valid values range from 0 to 255 where the default value is 3.

SolidColorStroke

The SolidColorStroke element represents a stroke painted with a solid color, or a solid color with opacity. It is similar to the SolidColor fill type.

Children

None.

Attributes

• alpha <number>: A real number value ranging from 0 to 1 specifying the opacity of the stroke, with 1 being opaque. Defaults to 1.</number>
• caps <string> (round, square, none): Specifies the type of caps at the end of lines. Defaults to round.</string>
• color <color>: An RGB value (in the form #rrggbb) that defines the single color value to stroke the shape with. Defaults to #000000.</color>
• joints <string> (round, miter, bevel): Specifies the type of joint appearance used at angles. Defaults to round.</string>
• miterLimit <number>: Indicates the limit at which a miter is cut off. Valid values range from 1 to 255. Defaults to 3.</number>
• pixelHinting <boolean>: Specifies whether to hint strokes to full pixels. This value affects both the position of anchors of a curve and the line stroke size itself. Defaults to false.</boolean>
• scaleMode <string> (normal, none, horizontal, vertical): A value that specifies which scale mode to use. Defaults to "normal".</string>
• weight <number>: The line weight, in pixels. Defaults to 1.</number>

LinearGradientStroke

The LinearGradientStroke paints a stroke along a path or shape with a continuously smooth color transition between a list of colors along a vector. 

The LinearGradientStroke operates almost identically to the LinearGradient fill type. As with the fill, by default, a LinearGradientStroke is transformed to fill the bounding box of the path being stroked.

Otherwise its rendering behavior is identical to that of the LinearGradientFill.

Children

• matrix
• GradientEntry

Attributes

• x <number>: The horizontal translation of the gradient transform that defines the horizontal center of the gradient.</number>
• y <number>: The vertical translation of the gradient transform that defines the vertical center of the gradient.</number>
• scaleX <number>: The horizontal scale of the gradient transform that defines the width of the (unrotated) gradient.</number>
• rotation <number> (<angle>): The rotation of the gradient transform.</angle></number>
• spreadMethod <string> (pad, reflect, repeat): How to choose the fill of pixels outside the gradient vector. Defaults to pad.</string>
• interpolationMethod <string> (rgb, linearRGB): How to interpolate between entries of the gradient. Defaults to rgb.</string>
• scaleMode <string> (normal, none, vertical, horizontal): A value that specifies which scale mode to use. Defaults to "normal".</string>
• caps <string> (none, round, square): A value that specifies the type of caps at the end of lines. Defaults to "none".</string>
• joints <string> (bevel, miter, round): A value that specifies the type of joint appearance used at angles. Defaults to "round".</string>
• miterLimit <number>: A number that indicates the limit at which a miter is cut off. Valid values range from 1 to 255. Default value is 3.</number>
• caps <string> (round, square, none): Specifies the type of caps at the end of lines.</string>
• weight <number>: The line weight, in pixels. Defaults to 1.</number>
• pixelHinting <boolean>: Specifies whether to hint strokes to full pixels. This value affects both the position of anchors of a curve and the line stroke size itself. Defaults to false.</boolean>

RadialGradientStroke

The RadialGradientStroke element paints a stroke along a path or shape with a continuously smooth color transition between a list of colors along the radius of a circle.

The RadialGradientStroke operates almost identically to the RadialGradient fill type. As with the fill, by default a RadialGradientStroke is transformed to fill the bounding box of the path being stroked. The bounding box is computed by computing the bounding box of the anchor points of the path, and expanding its borders outward in each direction by half the weight of the stroke.

Otherwise its rendering behavior is identical to that of the RadialGradientFill.

Children

• matrix
• GradientEntry

Attributes

• x <number>: The horizontal translation of the gradient transform that defines the horizontal center of the gradient.</number>
• y <number>: The vertical translation of the gradient transform that defines the vertical center of the gradient.</number>
• scaleX <number>: The horizontal scale of the gradient transform that defines the width of the (unrotated) gradient.</number>
• scaleY <number>: The vertical scale of the gradient transform that defines the width of the (unrotated) gradient.</number>
• rotation <number> (<angle>): The rotation of the gradient transform.</angle></number>
• spreadMethod <string> (pad, reflect, repeat): How to choose the fill of pixels outside the gradient vector. Defaults to pad.</string>
• interpolationMethod <string> (rgb, linearRGB): How to interpolate between entries of the gradient. Defaults to rgb. </string>
• focalPointRatio <number>: The placement of the focal point of the radial gradient along the horizontal center axis of the gradient bounding box. A value of 1 lies against. Defaults to 0.</number>
• scaleMode <string> (normal, none, vertical, horizontal): A value that specifies which scale mode to use. Defaults to "normal".</string>
• caps <string> (none, round, square): A value that specifies the type of caps at the end of lines. Defaults to "round".</string>
• joints <string> (bevel, miter, round): A value that specifies the type of caps at the end of lines. Defaults to "round".</string>
• miterLimit <number>: A number that indicates the limit at which a miter is cut off. Valid values range from 1 to 255. Default value is 3.</number>
• weight <number>: The line weight, in pixels. Defaults to 1.</number>
• pixelHinting <boolean>: Specifies whether to hint strokes to full pixels. This value affects both the position of anchors of a curve and the line stroke size itself. Defaults to false.</boolean>

GradientEntry

The GradientEntry element defines a stop in the list of colors used to render a gradient in a fill or stroke. A GradientEntry element must appear as a direct child of one of the four gradient fill or stroke types.

Each entry defines three values used in the gradient rendering: an RGB color value, an opacity value, and a position along the gradient vector (defined by the ratio attribute). When rendering the gradient, the entry specifies that the rendering at its ratio must exactly match its color and opacity. The gradient uses its assigned interpolation method to transition the color between the entry and its nearest neighbors.

GradientEntry elements can leave their ratio unspecified. If no ratio is assigned, the Gradient will automatically determine an appropriate value when rendering. If the first entry in a gradient has no specified ratio, it is assumed to be 0. If the last entry has no ratio, it assumed to be 1. If the gradient contains other entries with no ratio specified, they are distributed evenly between the ratios of the most immediate entries before and after that have definite values.

In the following example, there are two gradient entries with no specified ratio. Their nearest left and right neighbors with ratios specified define a range from 0.1 to 0.7. The two unspecified gradients would be distributed across this range, placing them at 0.3 and 0.5:

<LinearGradient ... >
    <GradientEntry ratio="0" />
    <GradientEntry ratio="0.1" />
    <GradientEntry />
    <GradientEntry />
    <GradientEntry ratio="0.7" />
</LinearGradient>

In the following example, none of the entries have specified ratios. The first entry is automatically placed at ratio 0, and the last at ratio 1. That leaves three unspecified ratios to be distributed across the defined range 0-1, placing them at 0.25, 0.50, and 0.75:

<LinearGradient ... >
    <GradientEntry />
    <GradientEntry />
    <GradientEntry />
    <GradientEntry />
    <GradientEntry />
</LinearGradient>

Each GradientEntry must either have no defined ratio or have a ratio larger than that specified by any of its previous sibling GradientEntry elements.

A gradient in FXG cannot have more than 16 GradientEntry elements in its definition.

Children

None.

Attributes

• color <color>: An RGB value specifying the color that should be used at that point in the gradient. Defaults to #000000.</color>
• alpha <number>: A number from 0-1 specifying the opacity that should be used at that point in the gradient. Defaults to 1.</number>
• ratio <number>: A value from 0-1 specifying where on the gradient the entry should be pinned.</number>

Visibility

FXG elements can control whether or not they are visible by specifying a visible attribute, which defaults to true. The visibility of a graphical element is defined by the visible attribute of the element and all of its parent elements. That is, if any parent of the element is hidden, that element is not rendered. Non-visible graphical elements still exist and are considered for any bounding box calculations necessary to render the document.

For example, if the size of the root Graphic element is left unspecified, it is calculated as the bounding box of all of the content in the document, including any non-visible content. To prevent non-visible elements from affecting the bounding box calculations, the global bounding box can be specified explicitly.

Blend Modes and Opacity

FXG elements can control how their content is composited with the background by specifying a blendMode attribute.

Grouping elements are rendered in one of two different ways, depending on their blend mode. A grouping element with a blend mode of 'normal' acts only as a transformation on the elements contained within. Its 2D transform, color transform, and opacity are multiplied down into its child elements, where they are combined with any local values to render the child element into the current surface. This has a visible effect on the use of opacity in an FXG document, as the following example shows:

<Group blendMode="normal" opacity="0.5">
    <Rect x="100" y="100" width="100" height="100">
        <fill>
            <SolidColor color="#FF0000" />
        </fill>
    </Rect>
    <Rect x="0" y="0" width="200" height="200">
        <fill>
            <SolidColor color="#0000FF" />
        </fill>
    </Rect>
</Group>

The opacity of the group would multiply down into the two child rectangles. The larger, frontmost blue rectangle would render with a 50% opacity, revealing the smaller red rectangle underneath.

All other blend modes force the group to act as a temporary compositing surface onto which its child elements are rendered. The surface is initialized to transparent black, and the child elements are composited in. The temporary surface is then composited into the grouping element's parent's surface, applying the grouping element's opacity, color transform, and 2D transform in the process.

When alpha is set on a grouping element whose blend mode is "normal", it acts as if the children of the group had their alphas individually set. This is different from the standard behavior of the CS tools, in which the alpha applies to the entire group, not to the individual children. Because of this somewhat nonstandard behavior, we define a special blendMode, "auto", for groups, which acts as blendMode="normal" when the alpha of the group is 0 or 1, and blendMode="layer" when the alpha of the group is strictly between 0 and 1. When a group does not have a specific blendMode, and its static appearance would be the same whether the blendMode is "normal" or "layer" (e.g. because no children have blendModes that require blending against items outside the group), we recommend using blendMode="auto".

Shape elements are affected similarly by their blendMode setting. A shape with a blendMode of normal composite transforms into the fill and stroke of the shape, which are rendered into the current surface. Any other blendmode type will effectively render its fill and stroke into a temporary compositing surface, which is then composited into the parent surface using the shape's color transform.

On a shape element, blendMode="auto" acts the same as blendMode="normal".

The default blendMode of an element is "auto".

FXG supports the following blend modes:

Blend Mode
Description

auto
For grouping elements, acts the same as blendMode="normal" when the alpha of the group is 0 or 1, and blendMode="layer" when the alpha of the group is strictly between 0 and 1. For shape elements, acts the same as blendMode="normal".

normal
The element content appears in front of the background. Pixel values of the element override those of the background. Where the element is transparent, the background is visible.

layer
The element content is pre-composed in a temporary buffer before it is processed further.

multiply
Multiplies the values of the element's constituent colors by the colors of the background color, and then normalizes by dividing by 0xFF, resulting in darker colors. \

screen
Multiplies the complement (inverse) of the display object color by the complement of the background color, resulting in a bleaching effect. This setting is commonly used for highlights or to remove black areas of the display object.

lighten
Selects the lighter of the constituent colors of the element and the color of the background (the colors with the larger values). 

darken
Selects the darker of the constituent colors of the element and the colors of the background (the colors with the smaller values). \

difference
Compares the constituent colors of the element with the colors of its background, and subtracts the darker of the values of the two constituent colors from the lighter value. \

add
Adds the values of the constituent colors of the element to the colors of its background, applying a ceiling of 0xFF. \

subtract
Subtracts the values of the constituent colors in the element from the values of the background color, applying a floor of 0. \

invert
Inverts the background.

alpha
Applies the alpha value of each pixel of the element to the background.

erase
Erases the background based on the alpha value of the element. 

overlay
Adjusts the color of each pixel based on the darkness of the background. If the background is lighter than 50% gray, the element and background colors are screened, which results in a lighter color. If the background is darker than 50% gray, the colors are multiplied, which results in a darker color.  \

hardlight
Adjusts the color of each pixel based on the darkness of the element. If the element is lighter than 50% gray, the element and background colors are screened, which results in a lighter color. If the element is darker than 50% gray, the colors are multiplied, which results in a darker color. This setting is commonly used for shading effects.

Color Transformations

Color Transformations are a high performance way to modify the color of an FXG group or shape element. A color transform can be used, for example, to tint a group, adjust its brightness, or modify its opacity.

Rendering

Color transforms are applied to the rendering of a group or shape element after any bitmap filters are applied; color transforms will affect the output of a filter (such as tinting the drop shadow). They are applied before the group element is composited with its background;  blend modes use the transformed color value when combining the group with the background content.

A ColorTransform element can specify multipliers and offsets for each individual channel of the RGBA rendering of a group element.  It is similar to a 5×5 matrix where only the diagonal (scale) values and right column (translation) are exposed---all other coefficients are set to zero.

Color Attributes vs. Color Transforms

Group and shape elements support both color transform child elements, as well as convenient color transform attributes (specifically, alpha).  As with the geometry transform, an individual element can use either attributes or child elements to define its color transform, but not both.  The alpha attribute corresponds to the alpha multiplier in the ColorTransform; there are no convenience attributes for defining the other coefficients of the matrix.

ColorTransform elements are only legal on shapes and Group instances---either an in-place group or a PlaceObject tag. They can not be placed in a group whose direct parent is in a definition element.

Defining a Color Transform

The following example shows how a group defines a color transform:

<Group>
    <transform>
        <Transform>
            <colorTransform>
                <ColorTransform redMultiplier="0.5" redOffset="20" />
            </colorTransform>
        </Transform>
    </transform>
</Group>

An element can optionally have a single child element of type transform. If present, the transform element must have a single child element of type Transform. The Transform element can optionally have a single child element of type colorTransform. The colorTransform element must have a single child element of type ColorTransform.

Attributes

• alphaMultiplier <number>: A decimal value that is multiplied with the alpha transparency channel value. Defaults to 1.  </number>
• alphaOffset <number>: A number from -255 to 255 that is added to the alpha transparency channel value after it has been multiplied by the alphaMultiplier value. Defaults to 0.</number>
• blueMultiplier <number>: A decimal value that is multiplied with the blue transparency channel value. Defaults to 1.</number>
• blueOffset <number>: A number from -255 to 255 that is added to the blue transparency channel value after it has been multiplied by the blueMultiplier value. Defaults to 0.</number>
• greenMultiplier <number>: A decimal value that is multiplied with the green transparency channel value. Defaults to 1.</number>
• greenOffset <number>: A number from -255 to 255 that is added to the green transparency channel value after it has been multiplied by the greenMultiplier value. Defaults to 0.</number>
• redMultiplier <number>: A decimal value that is multiplied with the red transparency channel value. Defaults to 1.</number>
• redOffset <number>: A number from -255 to 255 that is added to the red transparency channel value after it has been multiplied by the redMultiplier value. Defaults to 0.</number>

Children

None.

Masking

FXG supports applying a clipping mask to any instance group element.  A clipping mask is a subtree of graphical FXG, contained in a Group tag, and defines the region in which the group's content is rendered.

Clipping vs. Alpha vs Luminosity

FXG supports three different forms of masking: clipping, alpha and luminosity

Clip Masking

When masking in clip mode, a clipping mask is reduced to 1-bit.  This means that a mask will not affect the opacity of a pixel in the source content; it either leaves the value unmodified, if the corresponding pixel in the mask is has a non-zero alpha value, or makes it fully transparent, if the mask pixel value has an alpha value of zero.

When clip masking is used, only the actual path, shape vectors, and fills defined by the mask are used to determine the effect on the source content. Strokes and bitmap filters defined on the mask are ignored. Any filled region in the mask is considered filled, and renders the source content.  The type and parameters of the fill is irrelevant;  a solid color fill, gradient fill, or bitmap fill in a mask will all render the underlying source content, regardless of the alpha values of the mask fill.

BitmapImage elements are treated as bitmap filled rectangles when used in a clipping mask.  As a result, the alpha channel of the source bitmap is irrelevant when part of a mask---the bitmap affects the mask in the same manner as solid filled rectangle of equivalent dimensions.

RichText elements are not supported as part of a clip mask. Text must either be rasterized, or the mask must be converted to an alpha or luminosity mask.

Alpha Masking 

In alpha mode, the opacity of each pixel in the source content is multiplied by the opacity of the corresponding region of the mask. For example, a pixel in the source content with an opacity of 1 that is masked by a region of opacity of 0.5 will have a resulting opacity of 0.5. A source pixel with an opacity of 0.8 masked by a region with opacity of 0.5 will have a resulting opacity of 0.4.

Conceptually, alpha masking is equivalent to rendering the transformed mask and source content into separate RGBA surfaces, and multiplying the alpha channel of the mask content into the alpha channel of the source content.  All of the mask content is rendered into its surface before compositing into the source content's surface. As a result, all FXG features, such as strokes, bitmap filters, and fill opacity will affect the final composited content.

When in alpha mode, the alpha channel of any bitmap data is composited normally into the mask alpha channel, and will affect the final rendered content. This holds true for both BitmapImage elements and bitmap filled shapes and paths.

Luminosity Masking

Luminosity masking is very similar to alpha masking in that all of the mask artwork is rendered into a separate mask layer and a new alpha value is calculated and applied. Alpha masks simply use the alpha value of the rendered Alpha & RGB color values for blending. But luminosity masks convert the Alpha & RGB pixels using a filter which calculates a modified alpha and sets that value back as the alpha value of the masked element. After that the normal alpha soft masking processing can be done. The basic formula for calculating the luminosity alpha is:

luminosity = alpha * (.3red + .59green + .11*blue)

Optionally, luminosity masks have two boolean parameters to control the polarity of the mask as well as how values outside of the mask bounds are evaluated.

• luminosityInvert: <asboolean> Determines whether the polarity of the luminosity mask is inverted or not. Defaults to false.</asboolean>
• luminosityClip: <asboolean> Determines whether the values outside of the mask bounds are opaque or transparent. Defaults to false. </asboolean>

A luminosity mask is defined by setting maskType="luminosity". When this option exists, the luminosityClip and luminosityInvert attributes are settable to control the luminosity mask. luminosityClip/luminosityInvert do not have any bearing when set on clip or alpha masks.

Specifying a Mask

A Group, Graphic Path or shape object can support masks by defining a single child element of type 'mask'. If the mask child element exists, it must contain a single child element---either a Group instance element or a PlaceObject element.

The path data of the specified mask defines the clipping mask.   

The masking element inherits the target group's coordinate space, as though it were a direct child element.  It can be further modified with the standard group transform attributes or child elements.  The masking element is not rendered in the output.

Determining the type of mask

The type of masking used is determined via the maskType attribute. Legal values are 'clip', 'alpha' and 'luminosity'. The default value is clip.

<Group maskType="clip">
    <mask>
        <Group x="10" y="10" scaleX="3" scaleY="3">
            <Ellipse x="20" y="20" width="30" height="10">
                <fill>
                    <SolidColor color="#000000" />
                </fill>
            </Ellipse>
        </Group>
    </mask>

    <Rect width="150" height="150">
        <fill>
            <SolidColor color="#FF0000" />
        </fill>
    </Rect>
</Group>

Filter Effects

Bitmap Filters

FXG supports bitmap filter effects to be defined on shapes and grouping elements. A filter effect consists of a series of graphic operations applied to the rendered graphic of a grouping element and its children before compositing it into the background.

Filter effects are operations performed on a bitmap, and hence require an element to be pre-rendered into a temporary surface before being composited into the background.  This has an effect on how blend modes and opacity are treated on the group and its contents.  Adding a filter to an element with a blend mode of normal forces it to render as though it had a blend mode of 'layer.'

Filters are applied to an element after its content is rendered, but before it is composited into the background. This means that opacity, blend modes, and color transforms defined on the group are all applied to the output content of the filter.

Filters can only be defined on shapes and group instances, not group definitions. That means they can be defined on a Group tag placed as an immediate child of a Graphic or other Group tag, or as a child of a PlaceObject tag referencing a defined group.

Filters are defined on an element by defining a filters element as an immediate child.  The filters element must contain one or more of the pre-defined bitmap filter types.  Bitmap filters are applied to the rendered content of the element in the order they appear in the document---the first filter modifies the rendered content, the second filter modifies the output of the first filter, etc.

The following sections contain an overview of each of the bitmap filters defined by FXG.

 Bitmap Filters and Transforms

Bitmap filters are applied to the group content after it has been transformed into the document coordinate system by applying the composite transform of the group instance and all of its parent elements.  Scale, Rotation, and Skew transforms on content affect the input bitmap the group's filter list is applied to, but not the output bitmap.  Take the following three groups as an example:

<Group>
   <Group>
      <filters>
         <BlurFilter  />
      </filters>
      <Group scaleY="3">
         <Rect>
            ...
         </Rect>
      </Group>
   </Group>
</Group>

<Group>
   <Group scaleY="3">
      <filters>
         <BlurFilter  />
      </filters>
      <Group>
         <Rect>
            ...
         </Rect>
      </Group>
   </Group>
</Group>

<Group scaleY="3">
   <Group>
      <filters>
         <BlurFilter  />
      </filters>
      <Group>
         <Rect>
            ...
         </Rect>
      </Group>
   </Group>
</Group>

In all three examples, the final size of the transformed, rendered 'blurred' group is the same. Because the blur filter is applied after the group is transformed, the final rendered filtered output is the same, regardless of where the scale factor is applied.

Filter Rendering

For filters which apply a blur, the blurX and blurY values correspond to the diameter (not the radius) of the box filter used to create the blur. For a box filter with the size of 5 the convolution matrix used looks like this:

[ 1 1 1 1 1 ]
[ 1 1 1 1 1 ]
[ 1 1 1 1 1 ]
[ 1 1 1 1 1 ]
[ 1 1 1 1 1 ]

Quality relates to the number of passes of the filter on the same image. That means if you apply 3 flash blur filters with quality=1 you get the same result as 1 flash blur filter with quality=3. This also means that higher qualities can lead to a decrease in rendering performance. Quality values can be any value of 1, 2 or 3. 3 is the maximum quality achievable.

The size of the blur is not the radius but the diameter. To obtain the size of a blur in quality 2 or 3, simply multiply the diameter by the number of passes. Note that this is the mathematically correct size, not the perceived size. The blurred edges fade quickly reaching values below 1.0 meaning they will be clipped to an alpha of 0.0 and therefore will decrease the visual bounds.

We recommend that tools exporting filters in FXG target quality=2, since quality=1 produces undesirable artifacts, and set the blurX/Y values in FXG accordingly to match the size of the blur in the source tool.

Filter Types

The following sections contain an overview of each of the bitmap filters defined by FXG.

BlurFilter

Applies a blur effect to the input element.

Attributes

• blurX <number>: The amount of blur applied to the rendered content in the horizontal. Defaults to 4.</number>
• blurY <number>: The amount of blur applied to the rendered content in the vertical. Defaults to 4.</number>
• quality <number>: The quality of the rendered effect. Defaults to 1.</number>

DropShadowFilter

Applies a drop shadow to the input element.

Attributes 

• alpha <number>: The transparency of the generated effect. Defaults to 1.</number>
• angle <number>: The angle of the generated drop shadow. This angle is expressed in document coordinate space. Defaults to 45.</number>
• blurX <number>: The amount of blur applied to the rendered content in the horizontal. Defaults to 4.</number>
• blurY <number>: The amount of blur applied to the rendered content in the vertical. Defaults to 4.</number>
• color <color>: The color of the rendered drop shadow. Defaults to #000000.</color>
• distance <number>: The distance between each pixel in the source and its corresponding shadow in the output. Defaults to 4.</number>
• inner <boolean>: If true, drop shadow values are rendered above the original source content, and masked by the original content. If false, it is rendered below the original content. Defaults to false.</boolean>
• hideObject <boolean>: If true, the original content is not copied into the final output. Defaults to false.</boolean>
• knockout <boolean>: Renders the effect only where the value in the original content was 100% transparent. All other pixels are 100% transparent. Defaults to false.</boolean>
• quality <number>: The quality of the rendered effect. Defaults to 1.</number>
• strength <number>: The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the shadow and the background. Valid values are from 0 to 255.0. The default is 1.0.</number>

BevelFilter

Applies a Bevel effect to the input element.

Attributes 

• angle <number>: The angle of the generated bevel. This angle is expressed in document coordinate space. Defaults to 45.</number>
• blurX <number>: The amount of blur applied to the rendered content in the horizontal. Defaults to 4.</number>
• blurY <number>: The amount of blur applied to the rendered content in the vertical. Defaults to 4.</number>
• highlightAlpha <number>: The transparency of the generated highlight color. Defaults to 1.</number>
• highlightColor <color>: The color of the generated highlight color. Defaults to #FFFFFF.</color>
• distance <number>: The height of the bevel. Defaults to 4.</number>
• knockout <boolean> Renders the effect only where the value in the original content was 100% transparent. All other pixels are 100% transparent. Defaults to false.</boolean>
• quality <number>: The quality of the rendered effect. Defaults to 1.</number>
• shadowAlpha <number>: The transparency of the generated shadow of the bevel. Defaults to 1.</number>
• shadowColor <color>: The color of the generated shadow of the bevel. Defaults to #000000.</color>
• strength <number>: The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the bevel and the background. Valid values are from 0 to 255.0. The default is 1.0.</number>
• type <string> (inner, outer, full): The placement of the bevel on the object. Defaults to "inner".</string>

GlowFilter

Applies a Glow effect to the input element.

Attributes 

• alpha <number>: The transparency of the generated effect.</number>
• blurX <number>: The amount of blur applied to the rendered content in the horizontal.</number>
• blurY <number>: The amount of blur applied to the rendered content in the vertical.</number>
• color <color>: The color of the glow.</color>
• inner <boolean>: Specifies whether the glow is an inner glow.</boolean>
• knockout <boolean> Specifies whether the object has a knockout effect.</boolean>
• quality <number>: The quality of the rendered effect.</number>
• strength <number>: The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the bevel and the background. Valid values are from 0 to 255.0. The default is 1.0.</number>

GradientGlowFilter

Applies a Glow effect to the input element, using a specified gradient to fill the glow rather than a single color.

The gradient used in a GradientGlow is specified using child GradientEntry elements. See the section on gradient fills for more details.

Attributes 

• angle <number>: The angle of the generated glow. This angle is expressed in document coordinate space. Defaults to 45.</number>
• blurX <number>: The amount of blur applied to the rendered content in the horizontal. Defaults to 4.</number>
• blurY <number>: The amount of blur applied to the rendered content in the horizontal. Defaults to 4.</number>
• distance <number>: The offset between the element content and the rendered glow in the output. Defaults to 4.</number>
• inner <boolean>: If true, glow values are rendered above the original source content, and masked by the original content. If false, it is rendered below the original content. Defaults to false.</boolean>
• knockout <boolean>: Renders the effect only where the value in the original content was 100% transparent. All other pixels are 100% transparent. Defaults to false.</boolean>
• quality <number>: The quality of the rendered effect. Defaults to 1.</number>
• strength <number>: The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the glow and the background. Valid values are 0 to 255. The default is 1.</number>

Children

• GradientEntry

GradientBevelFilter

Applies a Bevel effect to the input element, using a specified gradient to fill the bevel rather than a highlight and shadow color.

The gradient used in a GradientBevel is specified using child GradientEntry elements. See the section on gradient fills for more details.

Attributes 

• angle <number>: The angle of the generated bevel. This angle is expressed in document coordinate space. Defaults to 45.</number>
• blurX <number>: The amount of blur applied to the rendered content in the horizontal. Defaults to 4.</number>
• blurY <number>: The amount of blur applied to the rendered content in the horizontal. Defaults to 4.</number>
• distance <number>: The height of the bevel. Defaults to 4.</number>
• knockout <boolean> Renders the effect only where the value in the original content was 100% transparent. All other pixels are 100% transparent. Defaults to false.</boolean>
• quality <number> The quality of the rendered effect. Defaults to 1.</number>
• strength <number> The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the bevel and the background. Valid values are from 0 to 255.0. The default is 1.0.</number>
• type <string> (inner, outer, full): The placement of the bevel on the object. Defaults to "inner".</string>

Children

• GradientEntry

ColorMatrixFilter

The ColorMatrixFilter class lets you apply a 4×5 matrix transformation on the RGBA color and alpha values of every pixel in the input image to produce a result with a new set of RGBA color and alpha values. It allows saturation changes, hue rotation, luminance to alpha, and various other effects.
\

Attributes 

• matrix: A comma-delimited list of 20 doubles that comprise a 4×5 matrix applied to the rendered element.  The matrix is in row major order---that is, the first five elements are multiplied by the vector [srcR,srcG,srcB,srcA,1] to determine the output red value, the second five determine the output green value, etc.

Scale-9

As a language targeted at describing rich interactive graphics, one major use of FXG is to describe the appearance of user interface controls.  Most applications define a single look for common elements of their user interface that can grow dynamically to be used at different sizes in different contexts.  The resizing process for these elements is such a common design pattern in interactive graphics that FXG has a specific feature to support it.

Imagine a designer creating a graphic to be used as a resizable panel control.  As the panel resizes, the four corners of the design typically would maintain a constant size, moving out to stay aligned into the corners of the panel's region on screen. The four edges of the panel would maintain a constant size in one direction, and  stretch in the other to fill the space between the aligned corners.  The center region of the panel would stretch in both directions to fill the remained of the panel's region on screen.

Using FXG, a designer can specify this exact behavior on a Group or Graphic element.  The designer specifies a scale-9 grid that defines how the group content is sliced up at rendering time into corners, edges, and center content; the FXG processor uses the scale grid to apply the scale-9 algorithm when resizing the content. There are significant limitations with the Flash Player's application of scale-9 grids on Display Objects and their children. Those limitations are described in the next section. FXG Processors and renderers are not required to workaround these limitations; instead we have chosen to document the Flash Player limitations and live with that behavior. 

ScaleGrid Implementation Limitations

Flash Player has several limitations when applying and rendering scaleGrids to Display Objects. These include:

1. Full inheritance of a scaleGrid is not yet supported at the Flash Player level. For example, given a Display Object with a scaleGrid defined on it, the Player will apply the scaleGrid transforms on that Display Object's visual content. However, it does not apply the scaleGrid transforms to the Display List children of that Display Object. 
2. Given a Display Object with a skew or rotation applied to it, the Player will not apply the scaleGrid transform correctly.
3. Nesting of scaleGrids is not supported at the Flash Player level. If a scaleGrid is applied to a Display Object, and that Display Object has a Display List child with its own scaleGrid applied, the scaleGrid is not applied correctly. No nesting of scaleGrids is allowed on individual Display Objects and their Display List children.
4. Bitmap slicing (slice-9) is not applied properly to Display Objects with bitmap content. As such, slice-9 is left out of the FXG 2.0 specification. 
5. A Display Object whose scaleGrid is defined such that it bleeds outside of the bounding box of its visual children.

6. If the scaleGrid attribute values are invalid, the scaleGrid is not defined properly. These scaleGrid error conditions include:

7. scaleGridLeft/scaleGridRight values cannot intersect (the left value must always be to the left of the right value in the element's coordinate system)

8. scaleGridTop/scaleGridBottom values cannot intersect (the top value must always be to the top of the bottom value in the element's coordinate system).
9. scaleGridLeft and scaleGridRight cannot equal each other such that the delimiter of the left scale grid and right scale grid are equal.
10. scaleGridTop and scaleGridBottom cannot equal each other such that the delimiter of the top scale grid and bottom scale grid are equal.
11. scaleGridLeft/Right/Top/Bottom must be inset by at least 1 pixel.

Given these limitations, we have kept the scale-9 support in FXG minimal. As such, any FXG output that results in scaleGrid constructs that produce any of the above stated "error conditions" will be considered illegal. It is up to the individual FXG processors to determine how this illegality is noted. These illegal scaleGrid constructs include:

1. A Group or Graphic with a scaleGrid applied to it which has other Groups as children [NOTE: It is illegal to nest grouping instance elements with defined scaleGrids.  This means that any element in the FXG document can have at most one ancestor with a scaleGrid defined.  This rule applies to the derived document oncePlaceObjectelements elements are replaced by their corresponding definitions.  For example, if a definition contains a Group with a scaleGrid, it cannot be placed inside of another Group with a scaleGrid via a PlaceObjecttag]. 
2. A Group or Graphic with a scaleGrid applied that also defines a rotation
3. A Group or Graphic with a scaleGrid applied that also defines a skew
4. A Group with invalid scaleGrid attributes (such that the scaleGrid is not defined properly) as described above
5. A Group whose scaleGrid is defined outside the bounding box of its visual children. \

[[ note title=u'Implementation Note' ]]The Flex implementation of scaleGrid has further limitations. Because of a Display Object optimization scheme in place in the Flex graphics library, the Flex SDK does not support scaleGrids applied to a Group which contains any children that are RichText elements or children that are graphic elements that have any of the following non-default attributes values applied to them: blendMode, filter, rotation. In these situations a runtime error is emitted. We may have to live with this inconsistency between the spec and the Flex implementation of FXG for this release. (We can chose to fail silently if people would prefer that).
[[ /note ]]

Specifying a Scale Grid

Scale Grids are specified via attributes on Grouping definition elements.  They are not instance attributes -- they can only appear on Group and Graphic tags, not on PlaceObject tags.

The Scale Grid Attributes are:

• scaleGridLeft <number>: the distance from the origin of the left edge of the scale grid, in the group's own coordinate system.</number>
• scaleGridRight <number>: the distance from the origin of the right edge of the scale grid, in the group's own coordinate system.</number>
• scaleGridTop <number>: the distance from the origin of the top edge of the scale grid, in the group's own coordinate system.</number>
• scaleGridBottom <number>: the distance from the origin of the top edge of the scale grid, in the group's own coordinate system.</number>

Naming

When a developer writes code to manipulate an FXG document in an interactive environment, they want to limit the amount that their code depends on the structure of the document to function. While some structure can be dictated by how the developer will code against it, portions of the FXG are irrelevant to the task the code is trying to accomplish. 

Forcing the code to traverse irrelevant structure to reach the portion it does care about it a recipe for fragile brittle code. 

Defining Contracts 

Instead, FXG allows a document author to identify specific elements in the document by name. 

An interactive environment supporting FXG (such as Flex) can provide APIs for the developer to reference specifically named elements, insulating them from changes in the overall structure of the document. A designer and developer will typically agree upon a set of required elements names (and potentially types).

This agreement defines a contract between the design and the logic.

Setting the id Attribute

Defines its own naming attribute, the 'id' attribute.

An id attribute on an element assigns a well defined name to that element. The value of an id attribute must be unique within the definition scope in which it appears. The FXG document creates its own definition scope. Each definition tag within the FXG library create a new definition scope.  ids are never visible across definitions scopes. The same id value can appear in the main document structure as well as within a library definition.

The value of the id attribute must be a valid ActionScript identifier. An id value should not contain spaces, start with a number, be a single number, or be a reserved ActionScript keyword.

Where id Attributes Can Appear 

The elements defined by FXG fall into three broad categories:

• content elements: Elements such as <group>, <rect>, <SolidColor> define actual content that typically appear in or directly affect the rendering of an FXG document.  These are the bulk of the elements defined.</rect></group>
• relationship elements: Elements such as <fill>, <stroke>, and <transform> exist to define a relationship between a parent element and a child element.  <fill>, for example, indicates that the <SolidColor> element it contains is used as the fill for the <rect> it is contained by. </rect></fill></transform></stroke></fill>
• control elements: Elements such as <mxml>, <library>, <definition> control how a section of the document are processed, and don't directly define content.</definition></library></mxml>

FXG processors are generally meant to expose FXG as content, necessarily as a document model.  When exposing FXG as content, relationships and control structure generally are exposed as context, rather than as objects that can be named (unlike a document model, where each element is exposed as an element, independent of its function).  As a result, id names are only allowed on content elements.
\

Symbol (Definition) names

See: FXG Name Mangling

Versioning

The FXG format includes a version number for identifying what revision of this specification the document conforms to.  The version number is specified as a required 'version' attribute on the root Graphics tag of any FXG file.

The version number must be read as a decimal value.  The integer portion of the version represents the major version of the document, while the fractional portion corresponds to the minor version.

The values of versions should be compared as real values, not an integer values.  Thus, a version attribute of "5.200" represents a major version 5, with a minor version of 2.  "5.200" and "5.2" represent equivalent version numbers. "5.2" is a newer version number than "5.100".

Responding to version numbers 

Each FXG processor implements/conforms to one or more versions (major.minor). An FXG processor should treat unknown major and minor versions as follows:

• An unknown major version number represents a change to the FXG syntax such that a parser based on an earlier major version number could not be expected to reasonably understand and represent the file. Alternatively, a different major version number might represent such a significant change to the content that can appear in an FXG file that a parser based on an earlier major version would fail to understand a significant portion of the content in the file. Processors discovering an later major version number SHOULD report the version mismatch to the user. Processors MAY offer to attempt to process the file regardless.
• An unknown minor version number represents a small change to the FXG format.  The change can be one of syntax or content.  A processor based on an earlier minor version number should be able to render the file with little or no loss of fidelity.

Processors discovering a later minor version number MUST ignore unknown attributes and elements for rendering and SHOULD preserve them in round-tripping use cases. Known elements that are descendents of an unknown element MUST be ignored for rendering and SHOULD be preserved for round-tripping.

Processors that discover attribute values that are out of range or have unexpected values (e.g., an enum value that does not match the enumeration constraint for the version the processor conforms to) SHOULD ignore those values and/or substitute default values for rendering and MUST preserve the original values for round-tripping use cases.

Processors discovering a later minor version MAY report the version mismatch and MAY report unknown elements, unknown attributes, or known attributes with unexpected values, to the user after processing. Recommended best practice is to avoid sending the user too many notifications; you should keep the reporting of unknowns to a minimum.

Processors MUST preserve and write (export) the original version number when round-tripping unknown elements or attributes. For example, a user imports/opens a 1.1 file with a 1.0 processor. The 1.1 file contains a <foo> tag, which is unknown to 1.0 processors. The 1.0 processor shows the contents of the file, ignoring the <foo> tag and all of its children. The user adds some text to the file in a way that does not disturb the <foo> tag or its contents (as far as the 1.0 processor can tell). The user then saves the FXG file again. If the saved file includes the <foo> tag, it MUST have the original version number also, which is 1.1</foo></foo></foo></foo>