Using FXG

FXG syntax
- FXG data types
- Tags not supported by FXG
Using FXG in applications built with Flex
- Generating FXG
- Converting FXG elements to MXML graphics
Coordinate systems
Sizing FXG components

FXG is a declarative XML syntax for defining vector graphics in applications built with Flex. FXG can also be used as an interchange format with other Adobe tools such as Illustrator or Photoshop. FXG closely follows the Flash Player 10 rendering model.

Designers can create vector images using tools such as Photoshop, Illustrator and Fireworks and export them as an FXG document. You can then use that FXG document as a component in your applications.

The following example is an FXG document that draws a filled rectangle:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/comps/GraphicComp.fxg -->
<Graphic xmlns="http://ns.adobe.com/fxg/2008" version="2">    
     <Rect id="rect1" width="200" height="200">
          <fill>
             <SolidColor color="#FFFFCC"/>
          </fill>
          <stroke>
             <SolidColorStroke color="#660099" weight="2"/>
          </stroke>
     </Rect>
</Graphic>

When using FXG documents as components, you specify the tag to be the name of the FXG file, just as you would do with an ActionScript or MXML component.

The following application uses the GraphicComp.fxg file as a component:

<?xml version="1.0" encoding="utf-8"?>
<!-- FXG/GraphicCompMain.mxml -->
<s:Application backgroundColor="0xFFFFFF" 
     xmlns:fx="http://ns.adobe.com/mxml/2009" 
     xmlns:mx="library://ns.adobe.com/flex/halo" 
     xmlns:s="library://ns.adobe.com/flex/spark"
     xmlns:comps="comps.*"
>

     <comps:GraphicComp id="graphic1"/>

</s:Application>

FXG documents encapsulate nearly all of their functionality in a single document. FXG documents cannot reference other FXG documents or MXML documents. However, they can reference the following external resources:

External bitmap files. For an example that embeds an external image, see Bitmap graphics.
Platform fonts by family name and style name.

Like MXML graphics, FXG tags have an implicit depth order. The order in which elements are defined defines their depth. Each tag is effectively drawn above its previous sibling. Children are drawn on top of their parents.

Adobe Creative Suite tools can be used to convert SVG to FXG. To do this, open the SVG file in the tool and export it as an FXG file.

FXG syntax

The root of an FXG document file is a <Graphic> tag. An FXG document can include zero or more containers (such as Group) and graphic elements, as well as a single library that can include any number of definitions.

The <Graphic> tag can only appear once in an FXG document. While the document cannot contain other <Graphic> elements, it can contain other elements such as <Rect>, <Ellipse>, <Path>, and <BitmapImage>. The <Graphic> tag can also optionally contain a single child <Library> tag and/or a single <mask> tag. These elements must appear before any other tag. If both are present, then the <Library> tag must come first.

You cannot specify an ID for the root <Graphic> tag in an FXG document.

FXG documents use the following language namespace:

http://ns.adobe.com/fxg/2008

When you create an FXG document, you must also add the version attribute to the <Graphic> root tag. The currently supported version is 2. For example:

:Graphic xmlns="http://ns.adobe.com/fxg/2008" version="2">

To use an FXG document in an application, you treat is as any other component. In your application, you define a namespace that matches the location of the FXG document. This namespace definition includes a prefix. For example:

<s:Application 
    ... 
    xmlns:comps="comps.*">

You then use that prefix to reference the FXG document as a component; for example:

<comps:MyGraphicComp id="graphic1"/>

FXG data types

The following table describes the basic data types that you can use in an FXG document:

Data Type	Description
angle	An arbitrary number specified as degrees. Angles are clockwise.
color	A numerical RGB specification in hexadecimal notation. You specify a color by using a pound sign (#) immediately followed by six hexadecimal characters. You cannot use the 0x notation that is supported in MXML graphics.
coordinate	Represents a length in the local coordinate system that is the given distance from the origin of the local coordinate system along the relevant axis (the x-axis for x coordinates, the y-axis for y coordinates).
identifier	A text string that matches the regular expression [A-Za-z][A-Za-z0-9_]*.
integer	An optional sign character (+ or -) followed by one or more digits 0 through 9. If the sign character is not present, the number is non-negative. Unless stated otherwise for a particular attribute or property, the range for an integer ranges from -2147483648 to 2147483647.
length	A distance measurement. The format of a length is a number.
number	Specified either in decimal notation, or in scientific notation. Decimal notation consists of either an integer or an optional sign character, followed by zero or more digits, followed by a dot (.), followed by one or more digits. Scientific notation consists of a decimal-number immediately followed by the letter "e" or "E" immediately followed by an integer. Unless stated otherwise for a particular attribute or property, a number has the capacity for at least a single-precision floating point number and has a range of -3.4e+38F to +3.4e+38F.
percentage	A number immediately followed by a percentage sign (%). Percentage values are always relative to another value; for example, a length. Attributes or properties that allow percentage values also define the reference distance measurement to which the percentage refers.

Tags not supported by FXG

While FXG is syntactically very similar to MXML, FXG does not define equivalents for all the MXML language tags. It does, however, include the <Definition>, <Library> and <Private> elements, which are equivalent to the MXML language tags of the same names. FXG does not define any other MXML language tags. The MXML language tags not defined by FXG include the following tags:

<fx:Binding>
<fx:Component>
<fx:Declaration>
<fx:Metadata>
<fx:Model>
<fx:Reparent>
<fx:Repeater>
<fx:Script>
<fx:State>
<fx:states>
<fx:Style>

FXG syntax also does not include any ActionScript 3.0 built-in primitive tags. The list of built-in tags that are not defined by FXG includes the following:

<fx:Array>
<fx:Boolean>
<fx:Class>
<fx:Date>
<fx:Function>
<fx:int>
<fx:Number>
<fx:Object>
<fx:String>
<fx:uint>
<fx:XML>
<fx:XMLList>

FXG does not support data binding. If you try to use the data binding short-hand syntax in an FXG document, the compiler treats it as a literal String value.

Using FXG in applications built with Flex

When you use an FXG document as a component in your application, the compiler optimizes the document into a subclass of the spark.core.SpriteVisualElement class. Specifically, the compiler maps the FXG elements to SWF graphics primitive tags and links only a light-weight, Sprite-based class into your application.

The SpriteVisualElement class extends the Sprite class. It adds support for sizing, positioning, and alpha when used in an application built with Flex.

To use FXG as a component in your applications:

Store the FXG document in a location where the compiler can find it. This can be in the same directory as the application, or in a separate location. If you store the FXG document in a separate location, you must add the location to the compiler’s source path.
Declare a namespace for the component. For example, if the FXG file is in the same directory as the main application that uses it, you can declare a namespace of “*”. If the FXG file is in a directory called comps, you can declare a namespace of “comps.*”.
Add a tag in your application that declares the component inside a Spark container. (You cannot use a MX container as a direct parent of an FXG component.) You can set DisplayObject properties on the tag, such as x and y, alpha, height and width. You can also add event handlers that are supported by the SpriteVisualElement class on the tag.

The following example creates multiple instances of the star.fxg component, and sets properties on each of those instances:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/OptimizedFXGExample.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:comps="*"
    width="500" height="300">

    <s:Group>
        <comps:star height="100" width="100" x="50" y="50"/>
        <comps:star rotationX="20" height="70" width="70" x="150" y="50" alpha=".75"/>
        <comps:star rotationX="40" height="50" width="50" x="220" y="50" alpha=".5"/>
        <comps:star rotationX="60" height="30" width="30" x="270" y="50" alpha=".3"/>
        <comps:star rotationX="80" height="10" width="10" x="300" y="50" alpha=".1"/>
    </s:Group>

</s:Application> The executing SWF file for the previous example is shown below:

The following is the FXG component that is used by the previous example:

<?xml version='1.0' encoding='UTF-8'?>
<!-- fxg/star.fxg -->
<fxg:Graphic xmlns:fxg="http://ns.adobe.com/fxg/2008" version="2">    
    <fxg:Path x="9.399" y="10.049" data="M 82.016 78.257 L 51.895 69.533 L 27.617 89.351 L 26.621 58.058 L 0.231 41.132 L 29.749 30.52 L 37.714 0.241 L 56.944 24.978 L 88.261 23.181 L 70.631 49.083 Z">
        <fxg:fill>
            <fxg:SolidColor color="#FFFFFF"/>
        </fxg:fill>
        <fxg:stroke>
            <fxg:SolidColorStroke 
                caps="none" 
                color="#4769C4" 
                joints="miter" 
                miterLimit="4" 
                weight="20"/>
        </fxg:stroke>
    </fxg:Path>
</fxg:Graphic>

FXG documents use only the *.fxg filename suffix. You cannot have another file of the same name with an *.mxml or *.as suffix in the same directory.

You can use ActionScript to instantiate an FXG component. When you do this, you declare the FXG tag to be of type SpriteVisualElement. You then add the component to the display list by calling the addElement() method, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/OptimizedFXGActionScriptExample.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    width="500" height="300" 
    creationComplete="drawStar()">

    <fx:Script>
        <![CDATA[                    
        import spark.core.SpriteVisualElement;

        private var myStar:SpriteVisualElement;

        private function drawStar():void {
            // Create new instances of star.fxg as if it were a local component.
            for (var i:int = 0; i<4; i++) {
                myStar = new star();

                myStar.x = 50 + (i*75);
                myStar.y = 50;
                myStar.height = 100 - (i*30);
                myStar.width = 100 - (i*30);
                myStar.alpha = 1 - (i*.2);
                myStar.rotationX = 20 + (i*20);

                addElement(myStar);
            }
        }
        ]]>
    </fx:Script>
</s:Application> The executing SWF file for the previous example is shown below:

Generating FXG

When you export a graphic file from a tool such as Adobe Illustrator in the FXG format, the tool writes a *.fxg file with a <Graphic> root tag.

If you are given the option to select a version of FXG, select version 2.

You can ignore the information in the <Private> code block, as long as you also leave the its namespace declaration. The contents of the <Private> block must be well-formed and valid XML but is not rendered.

You can optionally remove the <Private> tag and its contents from the FXG document. Some tools export FXG with additional syntax so that the file can be re-edited. An FXG document exported from Illustrator, for example, includes a <Private> block of code that is used by Illustrator if you want to edit the file again. If you do not expect to edit the file in Illustrator again, then you can remove the <Private> block.

Converting FXG elements to MXML graphics

In general, you should use an FXG document as a standalone component in your applications. This gives you the greatest amount of memory optimization, and lets you reuse your FXG files in other parts of the same application, or in other applications. In addition, by keeping the FXG document separate from the application, you can edit and export the FXG again from a graphics tool.

One disadvantage to using an FXG file as a standalone component is that you cannot get a reference to individual elements in it. The FXG component itself is a “black box”; you cannot interact with individual elements from your application or other components. You can, however, still apply effects, resize, position, and trigger events from interaction with the FXG component itself.

In some cases, you might want to add the FXG output directly into your application. You can do this, but you must convert the FXG syntax to MXML graphics.

After converting FXG elements to MXML graphics, you can get a reference to the various graphic elements, just as you can with any other MXML tags. This is useful if you want to apply special effects or events to what were previously FXG elements. After you convert the FXG file to MXML graphics, you cannot re-edit the FXG file in a graphics tool. It is now part of MXML.

To convert an FXG document to MXML graphics:

Start by copying and pasting the FXG code into your MXML document.
Update the namespaces:
1. Change the FXG namespace (http://ns.adobe.com/fxg/2008) to the Spark component namespace (library://ns.adobe.com/flex/spark). There can be only one language namespace per document.
2. If the FXG fragment uses additional tool specific namespaces, you can add these to the root of the MXML file. For example, FXG exported from Adobe Illustrator typically includes the following namespace declarations:
```
mlns:ai="http://ns.adobe.com/ai/2008" 
xmlns:d="http://ns.adobe.com/fxg/2008/dt"
```
  These namespaces do not impact the rendering of the document, but must be retained to keep the XML document valid as tool-specific private attributes will be prefixed in these namespaces.
Change or remove any namespace prefixes on the <Library>, <Definition>, and <Private> elements. They must use the MXML 2009 language namespace (http://ns.adobe.com/mxml/2009). If you remove a namespace prefix on the tag, you can usually just add the “fx:” prefix to each of these elements.
Move the <Library> tag and any <Definition> elements it contains to the top of the MXML document. If there is already a <fx:Library> tag in the MXML document, move just the <Definition> elements into it and remove the FXG <Library> tag.
For library definitions, add the “fx:” prefix to their tags in the body of the MXML file. In MXML 2009 documents, library definitions are actually in the language namespace. For example, the <fx:Definition name="BlueCircle"> tag references to a definition that must also be in the “fx” namespace; for example, <fx:BlueCircle>.
Move the <Private> tag to the end of the MXML document or remove it. You do not need to include the <Private> tag at all, but it can contain useful information about the tool that generated the FXG.
Update the namespace prefix of the FXG elements. There is likely to be an “s:” prefix already mapped to the Spark component namespace on the MXML document’s root tag (xmlns:s="library://ns.adobe.com/flex/spark"). Add the “s:” prefix to all of the FXG graphical elements. For example, change <Graphic> to <s:Graphic>.
For FXG 1.0 documents only:
1. Convert <TextGraphic> elements to <s:RichText>. This does not apply to FXG 2.0 documents, which use the <RichText> tag. In that case, you just add the “s:” prefix to the <RichText> tag to make it conform to MXML syntax.
2. Convert <BitmapGraphic> elements to <s:BitmapImage>. This does not apply to FXG 2.0 documents, which use the <BitmapImage> tag. In that case, you just add the “s:” prefix to the <BitmapImage> tag to make it conform to MXML syntax.

The following file, exported in FXG format from Adobe Illustrator, includes the private information as well as the <Graphic> root tag. The contents of this *.fxg file are being shown so that you can then see in a subsequent example how the contents are converted to MXML graphics.

<?xml version="1.0" encoding="utf-8" ?>
<!-- assets/skins/SimpleBox.fxg -->
<Graphic version="1.0" 
    viewHeight="30" 
    viewWidth="100" 
    ai:appVersion="14.0.0.367" 
    d:id="1" 
    xmlns="http://ns.adobe.com/fxg/2008" 
    xmlns:ai="http://ns.adobe.com/ai/2008" 
    xmlns:d="http://ns.adobe.com/fxg/2008/dt">
  <Library/>
  <Group 
    x="-0.296875" 
    y="-0.5" d:id="2" 
    d:type="layer" 
    d:userLabel="Layer 1">
    <Group d:id="3">
      <Rect x="0.5" y="0.5" width="100" height="30" ai:knockout="0">
        <fill>
          <LinearGradient x="0.5" y="15.5" scaleX="100" rotation="-0">
            <GradientEntry color="#ffffff" ratio="0"/>
            <GradientEntry ratio="1"/>
          </LinearGradient>
        </fill>
        <stroke>
          <SolidColorStroke 
            color="#0000ff" 
            caps="none" 
            weight="1" 
            joints="miter" 
            miterLimit="4"/>
        </stroke>
      </Rect>
    </Group>
  </Group>
  <Private>
    <ai:PrivateElement d:ref="#1">
      <ai:SaveOptions>
        <ai:Dictionary>
          <ai:DictEntry name="preserveGradientPolicy" value="3" valueType="Integer"/>
          <ai:DictEntry name="rasterizeResolution" value="72" valueType="Integer"/>
          <ai:DictEntry name="clipToActiveArtboard" value="1" valueType="Boolean"/>
          <ai:DictEntry name="downsampleLinkedImages" value="0" valueType="Boolean"/>
          <ai:DictEntry name="preserveFilterPolicy" value="3" valueType="Integer"/>
          <ai:DictEntry name="preserveTextPolicy" value="3" valueType="Integer"/>
          <ai:DictEntry name="writeImages" value="1" valueType="Boolean"/>
          <ai:DictEntry name="includeXMP" value="0" valueType="Boolean"/>
          <ai:DictEntry name="aiEditCap" value="1" valueType="Boolean"/>
          <ai:DictEntry name="versionKey" value="1" valueType="Integer"/>
          <ai:DictEntry name="includeSymbol" value="0" valueType="Boolean"/>
        </ai:Dictionary>
      </ai:SaveOptions>
      <ai:DocData base="SimpleBox.assets/images"/>
      <ai:Artboards 
        originOffsetH="0" 
        originOffsetV="30" 
        rulerCanvasDiffH="50.5" 
        rulerCanvasDiffV="-14.5" 
        zoom="17.17">
        <ai:Artboard active="1" index="0" right="100" top="30"/>
        <ai:ArtboardsParam all="0" range="" type="0"/>
      </ai:Artboards>
    </ai:PrivateElement>
    <ai:PrivateElement d:ref="#2">
      <ai:LayerOptions colorType="ThreeColor">
        <ai:ThreeColor blue="257" green="128.502" red="79.31"/>
      </ai:LayerOptions>
    </ai:PrivateElement>
    <ai:PrivateElement 
        ai:hashcode="769d7bac08ad6bdcf80f40fca11df6c0" 
        d:ref="#3">
      <ai:Rect height="30" knockout="0" width="100" x="0.5" y="0.5">
        <ai:Stroke colorType="ThreeColor" miterLimit="4" weight="1">
          <ai:ThreeColor blue="1"/>
        </ai:Stroke>
        <ai:Fill colorType="Gradient">
          <ai:Gradient 
            gradientType="linear" 
            length="100" originX="0.5" 
            originY="15.5">
            <ai:GradientStops>
              <ai:GradientStop colorType="GrayColor" rampPoint="0">
                <ai:GrayColor/>
              </ai:GradientStop>
              <ai:GradientStop colorType="GrayColor" rampPoint="100">
                <ai:GrayColor gray="1"/>
              </ai:GradientStop>
            </ai:GradientStops>
          </ai:Gradient>
        </ai:Fill>
        <ai:ArtStyle/>
      </ai:Rect>
    </ai:PrivateElement>
  </Private>
</Graphic>

To convert this example to MXML graphics:

Remove the <Library/> tag. This example does not contain any <Definition> elements.
Remove the <Private> block.

Move the two Illustrator-specific namespaces to the application’s root tag:

xmlns:ai="http://ns.adobe.com/ai/2008" 
xmlns:d="http://ns.adobe.com/fxg/2008/dt"

Remove the FXG-specific namespace:
```
"http://ns.adobe.com/fxg/2008"
```
Add the “s:” prefix to all elements.
Because the “d” and “ai” namespace definitions are intact, you do not have to remove the attributes specific to these namespaces. The attributes type and userLabel, for example, appear on the <Group> tag from the original FXG file. To further simplify this example, though, you could remove them because Flex ignores anything in those namespaces.

For example, this:
```
<s:Group x="-0.296875" y="-0.5" d:id="2" d:type="layer" d:userLabel="Layer 1">
```
Becomes this:
```
<s:Group x="-0.296875" y="-0.5">
```

The following example application contains the converted FXG from the previous example:

<?xml version="1.0" encoding="utf-8"?> 
<!-- fxg/ResultsMXMLGraphicsApp.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"    
    xmlns:ai="http://ns.adobe.com/ai/2008" 
    xmlns:d="http://ns.adobe.com/fxg/2008/dt"> 
 
    <s:Graphic version="1.0" 
        viewHeight="30" 
        viewWidth="100" 
        ai:appVersion="14.0.0.367" 
        d:id="1">
      <s:Group x="-0.296875" y="-0.5" d:id="2" d:type="layer" d:userLabel="Layer 1">
        <s:Group d:id="3">
          <s:Rect x="0.5" y="0.5" width="100" height="30" ai:knockout="0">
            <s:fill>
              <s:LinearGradient x="0.5" y="15.5" scaleX="100" rotation="-0">
                <s:GradientEntry color="#ffffff" ratio="0"/>
                <s:GradientEntry ratio="1"/>
              </s:LinearGradient>
            </s:fill>
            <s:stroke>
              <s:SolidColorStroke 
                color="#0000ff" 
                caps="none" 
                weight="1" 
                joints="miter" 
                miterLimit="4"/>
            </s:stroke>
          </s:Rect>
        </s:Group>
      </s:Group>
    </s:Graphic>
</s:Application>The executing SWF file for the previous example is shown below:

Coordinate systems

FXG defines two coordinate system concepts: the document coordinate system, and the user coordinate system.

The document coordinate system refers to the coordinate system of the root tag. By default, its origin sits at the top left of the document, and extends downward along the positive y axis, and to the right along the positive x axis. 1 unit corresponds to 1 pixel on the screen.

The user coordinate system refers to the coordinate system defined on any individual tag in the document. In FXG, the user coordinate system at the root <Graphic> tag is identical to the document coordinate system.

By default, each grouping instance element and graphic element defines its user coordinate system to be identical to that of its parent. Any geometry transform defined on the tag (through attributes or child transform elements) transforms its parent’s user coordinate system into a new system.

All attributes of elements are defined in units of the current user coordinate system. As a result, the coordinates of the segments of a path are relative to its coordinate system. To determine the position of the path segments in document coordinates, you would multiply its x and y by the geometry transform of the path and each of its parent elements until you reached the root graphic tag.

Some fills and strokes have their own user coordinate system. As with Groups, the default coordinate system is aligned with the coordinate system of their most immediate parent instance. As appropriate, fills and strokes support geometry transforms that can modify their coordinate space.

Sizing FXG components

FXG elements use their height and width properties to determine the size of the graphic. The graphic tag scales to the values of the height and width properties. The viewWidth and viewHeight properties define the space that the graphic takes up. When you set these values, the content is not scaled.

If you specify a viewWidth and viewHeight that is larger than the natural size of the content, the graphic takes up more space than its visual size. The result is a boundary around the graphic.

You can also specify a viewWidth and viewHeight that is smaller than the natural size of the content. You might do this if your graphic has chrome such as a border that extends past the edges of the graphic. In this case, be sure to turn off clipping in your layout.