Backward compatibility

To specify the version of the Flex compiler and framework that the output should be compatible with, use the compatibility-version compiler option. Possible values for this compiler option are defined as constants in the FlexVersion class. This option affects some behavior such as the theme, layout rules, padding and gaps, skins, and other style settings. In addition, it affects the rules for parsing properties files.

If you do not explicitly set the value of the compatibility-version option, the compiler defaults to the current SDK’s version.

In Flash Builder, you add the compatibility-version compiler option to the Additional Compiler Arguments field on the Flex Compiler properties panel. The following example sets the compatibility version to 3.0.0:

-compatibility-version=3.0.0

For the command-line compilers, you can either pass the compatibility-version compiler option on the command line or set the value in the configuration file. The following example sets the compatibility version to 4.0 in the flex-config.xml file:

<compiler> 
    <mxml> 
        <compatibility-version>4.0</compatibility-version> 
    <mxml> 
<compiler>

When you set the compatibility-version option, you must be sure that the configuration files that you use are compatible with the version you select.

You can programmatically access the version of the application that you are running by using the FlexVersion class. To get the current compatibility version in your application, use the compatibilityVersionString property of that class. This lets you conditionalize the logic in your application based on the compatibility version.

Using themes with compatibility-version

When you set the compatibility version, you should also be sure to use the appropriate theme file that matches that version. Themes are located in the frameworks/themes directory. For Flex 4.x, you do not have to specify a theme file. The default Spark theme file is designed for Flex 4.x compatibility. However, if you want the Flex 3 look and feel, you must specify the Halo theme or another theme that is compatible with the Flex 3 SDK.

The following command-line example uses the Halo theme and sets compatibility-version to 3.0.0:
mxmlc -compatibility-version=3.0.0 -theme=..\frameworks\themes\Halo\halo.swc MyApp.mxml

For more information on using themes, see About themes.

The default style sheets for several versions of Flex are available in the framework.swc file. This SWC file contains the current default style sheet (defaults.css) and the Flex 3 default style sheet (defaults-3.0.0.css). The compiler uses the style sheet that is appropriate for the compatibility version you set. For example, if you set the compatibility-version option to 3.0, then the compiler uses the Flex 3 default style sheet.

Differences between SDK 3 and SDK 4.x

The differences between SDK 3 and SDK 4.x that result from setting the compatibility-version option include fonts, skins, and styles.

If you set compatibility-version to 3.0.0, differences include:

  • The value of embedAsCFF defaults to false. This means that non-CFF fonts are embedded, rather than CFF fonts. For more information, see Embedding fonts with MX components.

  • The Halo theme should be used to define the look and feel of your application. This includes styles and skins.

  • Bi-directional binding will not work.

For a list of differences when using the compatibility-version compiler option, see Flex 4: Backward Compatibility.