Adobe Flex 3 Help

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. This option affects some behavior such as the layout rules, padding and gaps, skins, and other style settings. In addition, it affects the rules for parsing properties files. Setting the compatibility version does not enforce all differences that exist between the versions. For a list of differences that are enforced, see Differences between SDK 2.0.1 and SDK 3.

The currently supported values for the compatibility-version compiler option are 2.0.0 and 2.0.1. If you do not explicitly set the value of this option, the compiler defaults to the current SDK's version. You can determine the current SDK's version by using the -version option on the command line. For example:

mxmlc -version

In Flex 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 2.0.1:

-compatibility-version=2.0.1

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 2.0.1 in the flex-config.xml file:

<compiler>
    <mxml>
        <compatibility-version>2.0.1</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. For example, the way that locales and metadata elements are set up in the flex-config.xml file is different between Flex 2.0.1 and Flex 3. For a complete list of differences, see Differences between SDK 2.0.1 and SDK 3.

You can programmatically access the version of the Flex application that you are running by using the mx.core.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

When you set the compatibility version, you should also be sure to use the appropriate theme file that matches that version. For Flex 2.0.0 and 2.0.1, you should use the HaloClassic.swc theme file. Themes are located in the frameworks/themes directory. For Flex 3, you do not have to specify a theme file. The default theme file is designed for Flex 3 compatibility. For more information on using themes, see About themes in the Adobe Flex 3 Developer Guide.

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), the Flex 2.0.1 default style sheet (defaults-2.0.1.css), and the Flex 2 default style sheet (defaults-2.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 2.0.1, then the compiler uses the Flex 2.0.1 default style sheet.

Differences between SDK 2.0.1 and SDK 3

The differences between SDK 2.0.1 and SDK 3 that result from setting the compatibility-version option are mostly style properties and the styles applied to subcomponents.

Subcomponents are components within other components that inherited the styles of their parent in SDK 2.0.1 but do not in SDK 3. For example, the DateField control has a DateChooser subcomponent. In Flex 2.0.1, if you set noninheritable style properties such as borderColor or cornerRadius on the DateField control, the styles are also applied to the DateChooser subcomponent. This resulted in unexpected styling of the subcomponent and it was difficult to override this behavior. In Flex 3, these styles are not passed through from the DateField control to the DateChooser subcomponent, but you can choose to pass them through.

The following application shows the difference between how a DateField control appeared in SDK 2.0.1 and how it appears in SDK 3:

<?xml version="1.0" encoding="utf-8"?>
<!-- versioning/DateFieldSubComponentStyles.mxml -->
<!-- Compile this sample twice: once with the compatibility-version
     compiler option set to 2.0.1 and once without setting it. -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:DateField 
        id="dateField1" 
        yearNavigationEnabled="true" 
        borderColor="red"
    />
</mx:Application>

The executing SWF file for the previous example is shown below:

To see the difference in how styles are passed (or not passed) to subcomponents, compile this application twice. The first time you compile this example, do not set the compatibility-version compiler option. The second time you compile this example, set the compatibility-version option to 2.0.1, as the following example shows:

mxmlc -compatibility-version=2.0.1 DateFieldSubComponentStyles.mxml

When you run this application without setting the compatibility-version, the borderColor style is applied to the DateField control, but not to any part of the DateChooser calendar. When you run the 2.0.1 version of this application, the borderColor style is applied to the DateField control as well as the buttons and header lines of the DateChooser calendar.

You can add style properties to a filter list so that they are passed from the control to its subcomponent. For more information, see Subcomponent styles in the Adobe Flex 3 Developer Guide.

The following table lists the framework differences between Flex SDK 2.0.1 and Flex SDK 3 that are enforced when you use the compatibility-version compiler option:

Difference

Behavior in SDK 2.0.1

Behavior in SDK 3

Button control padding properties

The values of the paddingLeft, paddingRight, paddingTop, and paddingBottom styles are ignored by Button controls.

The values of the paddingLeft, paddingRight, paddingTop, and paddingBottom styles are honored. To make your icon Buttons look like the SDK 2.0.1 buttons, set the paddingLeft and paddingRight style properties to 0.

RadioButton control height

RadioButton controls do not use the padding properties when determining their height.

The default height of a RadioButton control is 18 pixels.

RadioButton controls take padding properties into account when determining their height.

The default height of a RadioButton control is 22 pixels.

DateChooser year navigator skins

The measuredHeight property was larger because of the changes in Button sizing.

The measuredHeight property was smaller.

DataGrid header skins

To customize the DataGrid header background, you subclass DataGrid and override the drawHeaderBackground() method.

The logic from the drawHeaderBackground() method is in the DataGridHeaderBackgroundSkin class. Also, you use the headerBackgroundSkin style to style DataGrid header background skins.

Menu control's horizontalGap property

The default value of the horizontalGap property for Menu controls is 0. If a Menu has a RadioButton control and an icon, the two overlap.

The default value of the horizontalGap property is 6. Additional space is added for a RadioButton or CheckBox, but not for icons in a MenuItem control.

ScrollBar layout

The width of a ScrollBar was determined by the up arrow skin's width.

The width of a ScrollBar component is the largest width among the up arrow, down arrow, track, and thumb skins.

Disabled ScrollBars

There is no separate skin for the buttons on a disabled ScrollBar.

ScrollArrowSkin has a disabled state. The scroll track was changed from a DisplayObject to a Button. The ScrollTrackSkin now supports Button states.

ScrollBar subcomponent alignment

The up arrow, down arrow, track, and thumb are left-aligned.

The up arrow, down arrow, track, and thumb are center-aligned.

ScrollBar thumb width

The thumb width is the width of the ScrollBar.

The thumb width is the same as the thumb's measuredWidth property.

Padding styles with the Canvas container

Padding styles have no effect on the Canvas container.

Canvas respects padding styles.

Constraint-based layout rules for content-sized containers

Width is ignored when left and right styles are set for components in containers where no width is set. In these cases, the preferredWidth property of a component is used. Height is ignored when top and bottom styles are set for components in containers where no height is set. In these cases, the preferredHeight property of a component is used.

In the following example, the Button control is 40 pixels wide:

<mx:Canvas id="mycanvas"> <mx:Button left="50" right="50"
width="100" id="b"/>
</mx:Canvas>

Width and height are honored for components with constraints set in content-sized containers. In the previous example, the Button control's width is 100 pixels.

FormItem padding

FormItem controls add unnecessary extra padding underneath the controls when there is more than one control.

No extra padding is allocated underneath a FormItem control.

Scale-9 for Panel containers

The Panel container's skin uses the HaloBorder class.

The Panel container's skin uses the PanelSkin class. Some measurement logic was removed from the Panel class and put into the PanelSkin class.

Border style for Panel containers

You can set the borderStyle property to "solid" and set a borderColor and borderThickness property on the Panel container.

Panel does not support any value for the borderStyle property other than "default".

You can use a combination of explicit heights and widths and absolute positioning to replicate most of the SDK 2.0.1 behavior for alternative borderStyle properties.

The PanelSkin class's implementation of alternative borderStyle properties does not lay out the header and control bar in the correct locations; the Panel is not large enough.

TitleWindow title alignment

The TitleWindow control's textHeight property adjusts to the scale factor.

The TitleWindow control's textHeight property ignores the scale factor.

Accordion header padding

The paddingTop and paddingBottom properties of the Accordion headers is set to -1.

The height of the Accordion container's header is different by one to two pixels.

Accordion subcomponent styles

The styles of the Accordion headers are inherited from the Accordion container.

The Accordion header does not inherit its styles from the Accordion control. Instead, the header uses the headerStyleName style, if one is specified.

The following Accordion styles are deprecated: fillAlphas, fillColors, focusRoundedCorners, horizontalGap, selectedFillColors, and verticalGap.

ColorPicker subcomponent styles

The ColorPicker's swatch panel subcomponent inherits its styles from the ColorPicker control.

Styles that affect the swatch panel do not apply if they are set on the ColorPicker. Instead, the swatch panel uses the swatchPanelStyleName style, if one is specified.

The following ColorPicker styles are deprecated: backgroundColor, columnCount, horizontalGap, verticalGap, previewHeight, previewWidth, swatchGridBackgroundColor, swatchGridBorderSize, swatchHeight, swatchHighlightColor, swatchHighlightSize, swatchWidth, textFieldWidth, and textFieldStyleName.

ComboBox subcomponent styles

The List drop-down in a ComboBox control inherits its styles from the ComboBox control.

The List subcomponent does not inherit its styles from the ComboBox control. Instead, the List subcomponent uses the dropdownStyleName style, if one is specified.

DateChooser subcomponent styles

The cornerRadius and fillColors styles are applied to the next and previous month button subcomponents of a DateChooser control.

Setting the cornerRadius and fillColors style properties affects only the DateChooser itself, but not the subcomponent buttons. To style the buttons, you must edit their skin classes or override the style filters list.

The fillColors and fillAlphas styles of the DateChooser control are deprecated.

DateField subcomponent styles

The DateChooser that pops up from clicking on a DateField inherits its styles from the DateField control.

The DateChooser subcomponent of a DateField control does not inherit its styles from the DateField control. Instead, the DateChooser subcomponent uses the dateChooserStyleName style, if one is specified.

The following DateField styles are deprecated: cornerRadius, fillAlphas, fillColors, headerColors, headerStyleName, highlightAlphas, todayStyleName, and weekDayStyleName.

LinkBar subcomponent styles

The LinkButton subcomponents in a LinkBar control inherit their styles from the LinkBar control.

The LinkButton subcomponents of a LinkBar do not inherit their styles from the LinkBar control. Instead, the LinkButton subcomponents use the linkButtonStyleName style, if one is specified.

MenuBar subcomponent styles

The submenus of a MenuBar control inherit their styles from the MenuBar control.

The submenus of a MenuBar control do not inherit their styles from the MenuBar control. Instead, they use the menuStyleName style, if one is specified.

The backgroundAlpha and backgroundColor MenuBar styles are deprecated.

NumericStepper subcomponent styles

The up and down buttons in a NumericStepper control inherit their border styles from the NumericStepper control.

The up and down buttons of a NumericStepper control do not inherit their border styles from the NumericStepper control.

To change the border styles for a NumericStepper control's button subcomponents, you must subclass the NumericStepper class and override the getters for the downArrowStyleFilters and upArrowStyleFilters properties. For more information, see Subcomponent styles in the Adobe Flex 3 Developer Guide.

TabBar subcomponent styles

The firstButtonStyleName and lastButtonStyleName are inherited from the ButtonBar control on a TabBar control.

The firstTabStyleName and lastTabStyleName styles apply to tab styles.

PopUpManager subcomponent styles

PopUp controls inherit their styles from the Application if they were not explicitly set on the PopUp control.

PopUp controls inherit styles from their owners.

ColorPicker alpha

The ColorPicker control's alpha property is lower, resulting in a lighter control.

The ColorPicker control's alpha property is higher, resulting in a darker control.

Form and FormItem layout

FormItem layout percentage height is not calculated correctly.

FormItem layout code uses BoxLayout. Percentage heights and widths are calculated correctly.

Also, Form and FormItem now support the includeInLayout property.

Percent width rounding rule

If two the width of a container is 275 pixels and two children have the width set to 50%, each component is 137 pixels. The extra pixel is ignored.

If the width of a container is 275 pixels and two children have a width set to 50%, the components widths are 137 pixels and 138 pixels. The extra pixel is applied to one of the components.

Run-time localization

The _CompiledResourceBundleInfo class is not autogenerated for SWC and SWF files.

The _CompiledResourceBundleInfo class is autogenerated for SWC and SWF files.

Parsing rules for .properties files

Parsing .properties files requires removing certain sequences of characters. To use a double quote, you use \\". To use a new-line character, you use \\n. To use a backslash, you use \\\\.

Parsing .properties files use the same rules as Java.

For more information about how properties files are parsed in SDK 3, see Properties file syntax in the Adobe Flex 3 Developer Guide.

Metadata

The keep-as3-metadata compiler option is set in flex-config.xml. The default metadata preserved by the Flex framework includes Bindable, Managed, ChangeEvent, NonCommittingChangeEvent, and Transient.

If you use a third-party library with custom metadata in your projects, you must add that metadata to the keep-as3-metadata option.

SWC libraries define what metadata the linker preserves when linking in code from that library.

When you compile a library, the keep-as3-metadata option instructs the compc compiler what metadata to declare. The option adds the metadata names to preserve in the SWC file's catalog.xml file.

If you use that library, you do not need to specify the metadata when compiling your application.

Profiler

Applications are not compatible with the profiler.

Applications are compatible with the profiler.

Signed framework Runtime Shared Libraries (RSLs)

Applications are not compatible with signed framework RSLs.

Applications are compatible with signed framework RSLs.

Icons for disabled components

When the disabledIcon property is set to null, the icon is invisible when the component is disabled.

The icon for a disabled component does not disappear when the disabledIcon property is set to null. To mimic the Flex 2.0.1 behavior, you can create a style that specifies null for the classes in the appropriate icon properties. For example:

RadioButton { icon:ClassReference(null); disabledIcon:ClassReference(null); selectedDisabledIcon:
ClassReference(null);
}

You can set remaining icon properties, such as downIcon and overIcon, to the appropriate skin class; for example, mx.skins.halo.RadioButton.

The configuration file syntax is also different between SDK 2.0.1 and SDK 3. If you use a customized flex-config.xml file, you must ensure that you match its syntax to the syntax of the SDK that you compile with. If you change SDKs, you might need to change the configuration file.

The following table lists the differences between the configuration files:

SDK 2.0.1

SDK 3

<flash-type>
true
</flash-type>
<advanced-anti-aliasing>
true
</advanced-anti-aliasing>
<!-- <locale>en_US</locale> --> <locale> <locale-element>en_US</locale-element> </locale>
<!-- <source-path> <path-element>locale/{locale}</path-element> <path-element>string</path-element> </source-path> --> <!-- <source-path> <path-element>string</path-element> </source-path> -->
<external-library-path> <path-element>
libs/playerglobal.swc
</path-element>
</external-library-path>
<external-library-path> <path-element>
libs/player
</path-element>
</external-library-path>
<fonts> <managers> <manager-class>
flash.fonts.JREFontManager
</manager-class>
<manager-class>
flash.fonts.BatikFontManager
</manager-class>
</managers> </fonts>
<fonts> <managers> <manager-class>
flash.fonts.JREFontManager
</manager-class>
<manager-class>
flash.fonts.AFEFontManager
</manager-class>
<manager-class>
flash.fonts.BatikFontManager
</manager-class>
</managers> </fonts>
<warn-class-is-sealed>
false
</warn-class-is-sealed>
<warn-class-is-sealed>
true
</warn-class-is-sealed>
<warn-deprecated-event-handler-error>
false
</warn-deprecated-event-handler-error>
<warn-deprecated-event-handler-error>
true
</warn-deprecated-event-handler-error>
<warn-deprecated-function-error>
false
</warn-deprecated-function-error>
<warn-deprecated-function-error>
true
</warn-deprecated-function-error>
<warn-deprecated-property-error>
false
</warn-deprecated-property-error>
<warn-deprecated-property-error>
true
</warn-deprecated-property-error>
<warn-level-not-supported>
false
</warn-level-not-supported>
<warn-level-not-supported>
true
</warn-level-not-supported>

n/a

<show-unused-type-selector-warnings>
true
</show-unused-type-selector-warnings>

n/a

<!-- <target-player>version</target-player> -->

n/a

<runtime-shared-library-path> <path-element>libs/framework.swc</path- element> <rsl-url>framework_3.0.183453.swz</rsl-url> <policy-file-url></policy-file-url> <rsl-url>framework_3.0.183453.swf</rsl-url> <policy-file-url></policy-file-url> </runtime-shared-library-path>

n/a

<static-link-runtime-shared-libraries>
true
</static-link-runtime-shared-libraries>

n/a

<!-- <compute-digest>boolean</compute-digest> -->
<metadata> <title>Adobe Flex 2 Application</title> </metadata> <metadata> <title>Adobe Flex 3Application</title> </metadata>
<show-deprecation-warnings> true </show-deprecation-warnings>

n/a