| | {section} |
| | {column:width=80%} |
| | h1. Flex 3: Backwards Compatibility and Migration |
| | |
| | *Contents* |
| | * [Deprecated Items|#DeprecatedItems] |
| | * [Backwards Compatibility Compiler Option|#BackwardsCompatibilityCompilerOption] |
| | * [Changes Not Supported by the Compatibility Compiler Option|#ChangesNotSupportedByTheBackwardsCompatibilityFlag] |
| | * [Flash Player Backwards Compatibility|#FlashPlayerBackwardsCompatibility]\\ |
| | {column} |
| | {column} |
| | {adbe-prev:http://learn.adobe.com/wiki/display/Flex/Part+IV.+Building+Your+Own+Flex+Application} |
| | {adbe-next:http://learn.adobe.com/wiki/display/Flex/Flex+Builder+3+Compiler+Errors} |
| | {rate:title=User rating\|theme=dynamic\|key=focal\|display=default} |
| | {column} |
| | {section} |
| | ---- |
| | h2. Deprecated items |
| | Starting in Flex 3, the Flex ActionScript Language Reference has an Appendix that lists deprecated classes, methods, etc. You can get to this page either by scrolling to the bottom of the top-left frame or by going directly to http://livedocs.adobe.com/flex/3/langref/deprecated.html |
| | |
| | ---- |
| | h2. Backwards Compatibility Compiler Option |
| | |
| | A new compiler argument, \-compatibility-version=2.0.1, was added to the Flex 3 SDK. This compiler argument allows your Applications to use some of the Flex 2.0.1 behavior instead of the new Flex 3 behavior. The following table list the backwards compatibility changes in Flex 3 that support the use of the backwards compatibility flag. |
| | bq. *Note:* You cannot select a subset of the Flex 2.0.1 behavior you want to use in your application. If you compile with the backwards compatibility flag, you get all of the Flex 2.0.1 behavior described below. |
| | Here is an example of using the backwards compatibility flag: |
| | |
| | {{$./mxmlc \-compatibility-version=2.0.1 ../samples/explorer/controls/ButtonExample.mxml}} |
| | |
| | To use the backwards compatibility flag in a Flex Builder project, select Project > Properties > Flex Compiler. In the Additional Compiler Arguments text field, add \-compatibility-version=2.0.1 to the list of compiler arguments for the project. Click OK and your project now compiles with the Flex 2.0.1 behaviors described below. |
| | \\ |
| | || Summary || Flex 2.0.1 Behavior || Flex 3 Behavior || Scenario \\ || |
| | | *Button Padding Improvements* | Button did not respect paddingLeft, paddingRight, paddingTop and paddingBottom styles which affected the size and position of the label placement. | All Button padding styles behave correctly. | If you set padding styles on any Button component, you will be affected by this change. A Flex 2.01 Button and a Flex 3 Button with the same padding style values will have different sizes. \\ \\ |
| | For example, if you set a width on a Button in flex 2.0.1, in Flex 3 the label text might be truncated text. \\ \\ {{<mx:Button label="Submit" width="60" />}} \\ \\ |
| | This Button in Flex 2.01 had less than 10 pixels of space on the right and left to accommodate the full label. However, in Flex 3, the default paddingLeft and paddingRight is 10 pixels. \\ \\ |
| | Because these padding styles work properly in Flex 3, the "Submit" label is now truncated. To workaround this, you can set the paddingLeft and paddingRight styles to be smaller. For example: \\ \\ {{<mx:Button width="60" label="Submit" paddingLeft="4" paddingRight="4" />}}\\ | |
| | | | Buttons with an icon and no label ignored the padding values. | By default, the paddingLeft and paddingRight properties for Buttons are set to 10 by default | Applications that implement Buttons that have an icon and no label will be different sizes. \\ \\ |
| | To make your icon Buttons look like the Flex 2.01 buttons, set paddingLeft and paddingRight on these Buttons to 0. | |
| | | | For a DateChooser year navigator skin, the measuredHeight getter returns a larger value in Flex 2.0.1. | For a DateChooser year navigator skin in flex 3, the measuredHeight getter returns a smaller value. | Any application implementing a custom DateChooser year navigator skin. | |
| | | | RadioButtons did not take into account padding when determining their height. \\ \\ |
| | The default height of a Flex 2.0.1 RadioButton is 18 pixels. | RadioButtons now take padding into account for height measurements. \\ \\ |
| | The default height of a Flex 3 RadioButton is 22 pixels. \\ |
| | This change was made to fix [SDK-11907|https://bugs.adobe.com/jira/browse/SDK-11907] | Any application implementing a RadioButton | |
| | | *DataGrid Header Skinning Changes* | To customize the DataGrid header background, you subclass DataGrid and override the drawHeaderBackground function. | The logic from drawHeaderBackground is now implemented in DataGridHeaderBackgroundSkin. Also, headerBackgroundSkin style was added. | Applications that subclass DataGrid and change drawHeaderBackground. | |
| | | *Menu's default horizontalGap has changed.* \\ \\ *Menu spacing has been improved* \\ |
| | ([SDK-11780|https://bugs.adobe.com/jira/browse/SDK-11780]) | In Flex 2.0.1, horizontalGap for Menu is 0. \\ \\ |
| | If a Menu contains a RadioButton and icon, the two items overlap. | In Flex 3, horizontalGap for Menu is 6. \\ \\ |
| | A separate space is given for a RadioButton/CheckBox and the icon of a MenuItem | Any application using an icon style (for example, branchIcon or checkIcon). These Menus will have a larger horizontalGap, so the Menus will likely be a little wider. | |
| | | *Changes to ScrollBar layout* | Width of a scrollbar is determined by the upArrow width | Width of a scrollbar is determined by the largest width among the upArrow, downArrow, track, and thumb. | Subclassing Scrollbar classes or using custom skins for a Scrollbar. | |
| | | *Disabled ScrollBars have a new skin* ([SDK-9411|https://bugs.adobe.com/jira/browse/SDK-9411]) | There is no separate skin for the buttons on a disabled scrollbar. | A disabled state was added to ScrollArrowSkin. \\ \\ |
| | The scrollTrack was changed from a DisplayObject to a Button. \\ \\ |
| | The ScrollTrackSkin now supports button states. | Applications that display scrollbars in any container or component when they are disabled. | |
| | | | upArrow, downArrow, track, and thumb are left-aligned | upArrow, downArrow, track, and thumb are center-aligned | Subclassing the ScrollBar classes or using custom skins of various widths. | |
| | | | Thumb width is the width of the ScrollBar | Thumb width is thumb's measuredWidth | Subclassing the ScrollBar classes or using custom skins | |
| | | | *Canvas padding styles* | Canvas padding styles have no effect | Canvas now respects padding styles | Applications specifying paddingLeft, paddingRight, paddingTop or paddingBottom in a Canvas | |
| | | *Containers: Constraint based layout rules.* Constraint-based layout rules in content-sized Containers changed | Width was ignored when left and right styles were set for components in Containers where no width is set. In these cases, the preferredWidth of a component was used. \\ \\ |
| | Height was ignored when top and bottom styles were set for components in Containers where no height is set. In these cases, the preferredHeight of a component was used. For example: \\ \\ {{<mx:Canvas id="mycanvas">}} \\ |
| | {{<mx:Button left="50" right="50" width="100" id="b"/>}} \\ {{<mx:/Canvas>}} \\ \\ |
| | This would be a 40 pixel button. | Width and height are now honored for components with contstraints set in content sized containers. \\ |
| | In the button example, the width would be 100 in Flex 3. | Affects applications where components specified width along with left/right styles in content-sized containers and components that specified height along with top/bottom styles in content-sized containers. | |
| | | *FormItem Padding* | FormItem adds unnecessary extra padding underneath the controls when there are more than one control. | No extra padding is allocated underneath a FormItem control. | Applications using FormItem with multiple controls. | |
| | | *Panel now supports 9-slice scaling* | Panel's skin used HaloBorder | The Panel's skin now uses a new PanelSkin class. | Applications that created custom Panel skins that extended HaloBorder or Border. \\ |
| | Some measurement logic was removied from the Panel class and put into the PanelSkin class. Therefore, older skins may not layout correctly. \\ |
| | In these cases, subclassing PanelSkin rather than HaloBorder or Border should solve any issues. | |
| | | *Panel no longer supports borderStyle* | You can set borderStyle="solid" and set a borderColor and borderThickness. | Panel no longer supports any borderStyle other than "default". Supporting only the default borderStyle simplifies using graphical skins with Panel. \\ \\ |
| | Panel will support other borderStyles when using the backwards compatibility flag. In addition, you can use a combination of explicit heights/widths and absolute positioning to replicate most of the old behavior for alternate borderStyles. \\ \\ |
| | PanelSkin's implementation of alternate borderStyles will not layout the header and control bar in the correct locations, nor will it size the Panel to be large enough. | Anyone setting borderStyle, borderColor and borderThickness for a Panel. | |
| | | *TitleWindow: title alignment.* Title alignment is a few pixels different | n/a | To fix [SDK-12716|https://bugs.adobe.com/jira/browse/SDK-12716], the TitleWindow title alignment logic was changed. | Any applications using TitleWindow. | |
| | | *SubComponent style changes* | *Accordion*: Accordion headers have paddingTop and paddingBottom set to \-1 to solve layout issues. | The height of the header has changed by 1-2 pixels. | Any application using an Accordion. | |
| | | | *Accordion*: Styles set on the Accordion were always passed on to the Accordion header. | In Flex 3, the Accordion header no longer gets its styleName set to the Accordion. Instead, it only gets assigned to the headerStyleName style if one is specified. \\ \\ |
| | The following styles have been deprecated: |
| | * fillAlphas |
| | * fillColors |
| | * focusRoundedCorners |
| | * horizontalGap |
| | * selectedFillColors |
| | * verticalGap | Applications using any styles on their Accordion expecting them to take effect on the Accordion header. This includes styles such as skin, and icon. All of these styles should be specified in a headerStyleName instead. | |
| | | | *ColorPicker*: The ColorPicker passes all of the styles set on it to the swatch panel. | Any styles that affect the swatch panel do not take effect if they are set on the ColorPicker. Instead, the swatchPanelStyleName should be used. \\ \\ |
| | The following ColorPicker styles have been deprecated: |
| | * backgroundColor |
| | * columnCount |
| | * horizontalGap |
| | * veriticalGap |
| | * previewHeight |
| | * previewWidth |
| | * swatchGridBackgroundColor |
| | * swatchGridBorderSize |
| | * swatchHeight |
| | * swatchHighlightColor |
| | * swatchHighlightSize |
| | * swatchWidth |
| | * textFieldWidth |
| | * textFieldStyleName | Any Application setting styles on the ColorPicker that affect the ColorPicker swatchPanel. | |
| | | | *ComboBox*: The ComboBox dropdown that popped up from clicking on a ComboBox inherits its styles from the ComboBox. | In Flex 3, the dropdown list does not get any of its styles from ComboBox. Instead, use the style dropDownStyleName to specify any style on the ComboBox's dropdown list. | This affects any application that sets styles on the ComboBox that would be applied to the dropdown list. This includes styles such as rollOverColor, alternatingItemColors, and selectionColors. | |
| | | | *DateChooser*: Setting cornerRadius and fillColors affects the nextButton and prevButton. | Setting cornerRadius and fillColors only affects the DateChooser itself, but, not the sub-component buttons. The following styles have been deprecated: |
| | * fillColors |
| | * fillAlphas. | An Application setting cornerRadius or fillColors on a DateChooser. To change the cornerRadius or fillColors of a DateChooser, override the getter for the nextMonthStyleFilters and prevMonthStyleFilters. | |
| | | | *DateField*: The DateChooser that popped up from clicking on a DateField inherits its styles from the DateField. | In Flex 3, the DateChooser does not get any of its styles from DateField. Instead, use the style dateChooserStyleName to specify any style that affects the popUp DateChooser. \\ \\ |
| | The following DateField styles have been deprecated: |
| | * cornerRadius |
| | * fillAlphas |
| | * fillColors |
| | * headerColors |
| | * headerStyleName |
| | * highlightAlphas |
| | * todayStyleName |
| | * weekDayStyleName | This affects setting styles on the DateField and expecting the styles to apply to the DateChooser PopUp. DateChooser will only inherit styles from the DateField including. | |
| | | | *LinkBar*: LinkButtons in a LinkBar inherit their styles from their parent LinkBar. | Flex 3 adds the linkButtonStyleName style. All styles that affect a LinkButton in a LinkBar should be set though a class selector that is assigned to linkButtonStyleName. | Any Application using styles on a LinkBar that are inherited by the LinkButtons. | |
| | | | *MenuBar*: The MenuBar passes all of the styles set on it to the submenus. | Any non-inheriting styles that affect the MenuBar sub-menus will not take effect if they are set on the MenuBar. Instead, use the menuStyleName style. \\ \\ |
| | Most of the styles on MenuBar that only affect the sub-menus have been deprecated. The following MenuBar styles have been deprecated: |
| | * backgroundAlpha |
| | * backgroundColor. | Any Application setting non-inheriting styles on the MenuBar that affect the sub-menus. | |
| | | | *NumericStepper*: setting border styles such as borderColor, borderStyle, and borderThickness affects the up and down buttons. | Setting border styles such as borderColor, borderStyle, and borderThickness does not affect the up and down buttons. It only affects the TextField of a NumericStepper. | An Application setting border styles on a NumericStepper. \\ \\ |
| | To change the border styles for a NumericStepper, subclass NumericStepper and override the getters for the downArrowStyleFilters and upArrowStyleFilters. | |
| | | | *TabBar*: The firstButtonStyleName and lastButtonStyleName styles inherited from ButtonBar on a TabBar. | In Flex 3, use firstTabStyleName and lastTabStyleName to specify any styles that apply to tab styles. | Any Application using styles firstButtonStyleName and lastButtonStyleName on a TabBar. | |
| | | | *PopUpManager*: Any PopUp takes its inheriting styles from the Application if they are not set for the PopUp. | The PopUp receives its inheriting styles from its owner. | This potentially affects any popup who's owner was not the parent Application. | |
| | | *ColorPicker:* ColorPicker is visually darker when alpha is set on it. [(SDK-11734|https://bugs.adobe.com/jira/browse/SDK-11734]) | n/a | n/a | Any Application setting alpha on the ColorPicker might notice a cosmetic difference. | |
| | | *Compiler Parsing Rules:* Parsing rules for .properties files were changed to more closely follow Java's rules. | The rules in Flex 2 for parsing .properties files were peculiar, such as removing certain sequences of "bad characters,", requiring you to write double escape characters for double-quote or newline character, and \\\\ to get a backslash. | Flex 3 uses Java's rules. Go to [SDK-11000|https://bugs.adobe.com/jira/browse/SDK-11000] to get the full changes. | Applications using .properties files. | |
| | | *Form Layout Changes* ([SDK-9730|https://bugs.adobe.com/jira/browse/SDK-9730]) | FormItem layout percentage height does not behave correctly. | Form layout code now uses BoxLayout. Percentage heights and widths should now work correctly. Also, Form and FormItem now support includeInLayout. You might find small layout changes from Flex 2.0.1. | Any Application using FormHeader and FormItem. | |
| | | *For percent layouts*, round off is now saved and the extra pixel is distributed to one of the components in the layout. ([SDK-10871|https://bugs.adobe.com/jira/browse/SDK-10871]) | If the width of a container was 275 pixels and two children both had width=50%, each component would be 137 pixels. The 1 pixel roundoff is not taken into account. | In Flex 3, for a container with width=275 pixels and two children with width=50%, the components are 137 pixels and 138 pixels. The extra pixel is saved and distributed to one of the components. | Applications using percent width and height values. | |
| | | *Runtime Localization*: Compilation of \_CompiledResourceBundleInfo | n/a | The new \_CompiledResourceBundleInfo class is not autogenerated for SWCs or when the \-compatibility-version is Flex 2.0.X. It is only for Flex 3 SWFs. | This does not affect Flex 2.0.1 swfs. This affects swfs using runtime localization that are also using the compatibility flag. Flex 2.0.1 resource bundle parsing rules will be used when the compatibility flag is used. | |
| | \\ |
| | |
| | ---- |
| | \\ |
| | |
| | h2. Changes Not Supported By The Backwards Compatibility Flag |
| | |
| | The following changes are not supported by the \-compatibility-version=2.0.1 flag. Therefore, you cannot revert any of the new behavior to an older version of Flex. |
| | || Summary || Flex 2.0.1 Behavior || Flex 3 Behavior || Scenario || |
| | | *keep-as3-metadata* was removed from flex-config.xml | keep-as3-metadata added custom metadata or replaced the default metadata. | If your metadata names are for linking with a third party SWC that doesn't declare metadata names, then you should remove the default Flex metadata names and move your own metadata names to application specific configuration files. This way the metadata names are available for linking but unavailable when creating SWC files. If you leave your metadata names in flex-config.xml no harm will be done. However, the SWCs they create will have extra metadata names that aren't really needed. \\ \\ |
| | If your metadata names link to a third party SWC that is compiled with Flex 3.0 and does declare metadata names, then you should remove the metadata names from flex-config.xml. No harm will be done if the names are left in flex-config.xml. \\ \\ |
| | If your metadata names are for linking with your own libraries, then you should compile your libraries using the keep-as3-metadata option to preserve the metadata names in the SWCs and remove the metadata names from flex-config.xml. No harm will be done if the names are left in flex-config.xml. | Applications that added their own metadata names to keep-as3-metadata | |
| | | *Locales* are now included in frameworks.swc | Locales are in frameworks/locales/_locale_ in .properties files | Locales are included with frameworks.swc | References to frameworks/locale/_locale_ will generate compile errors. | |
| | | *Specifying a locale* in local-config.xml (<locale>en_US</locale>) gives a runtime error. | <locale>en_US</locale> was valid. (SDK-9438) | In Flex 3, you must use the locale-element tag as well. \\ \\ |
| | <locale><locale-element>en_US</locale-element></locale> | Applications specifying locales in their locale-config.xml file. | |
| | | *An empty locale/*{*}{_}locale{_}* *directory* has to be created in project's or framework's directory structure if specifying a locale. (bug: SDK-11855) | A command similar to the following worked: \\ {{>COMPC \-locale=de_DE \-source-path=custom/_locale_ \-include-resource-bundles bundle1 \-o deCustomResources.swc}} | You need to create an empty locale/de_DE directory in your project or in the frameworks directory to have the compc \-locale command work. | Anyone using compc with a specified locale. | |
| | | *flashType has been deprecated* | You can set flashType=true. | Use fontAntiAliasType="advanced" to set flashType to true. \\ \\ |
| | fontAntiAliasType="normal" is equivalent to flashType=false. | Using flashType generates a compiler warning. | |
| | | *ComboBox ItemRenderer* Padding Changes | The dropDown of a ComboBox itemRenderer receives its paddingLeft style from the List. By default, this paddingLeft value is 2. | The ComboBox dropdown gets its paddingLeft style from its dropDownStyleName. This gives it a default paddingLeft value of 5. | Anyone using a ComboBox ItemRenderer | |
| | | *DataGrid Layout Changes* | The verticalScrollBar of a DataGrid is the fourth child of the component. | The verticalScrollBar is child 5. | If you are subclassing DataGrid and accessing the verticalScrollBar with DataGrid.getChildAt(4). | |
| | | | The y value for an itemEditorInstance was its y value in the whole DataGrid. Therefore, an itemEditorInstance in the fourth row of a DataGrid with rowHeight="25" would have a y value of 75. | In Flex 3, each itemEditorInstance is relative to its renderer. Therefore, the y value is 0 (for the Flex 2.0.1 example). | Applications using the y value of an itemEditorInstance. | |
| | | *DataGrid rowCount and lockedRowCount* do not include the header. | rowCount and lockedRowCount includes the header. The itemClick event's rowIndex property returns 1 for the first row of data. | rowCount and lockedRowCount do not include the header. Also, the itemClick event's rowIndex property returns 0 for the first row of data. | Applications that reference rowCount or use lockedRowCount. | |
| | | *DataGrid: Specifying a verticalSeparatorSkin* doesn't draw for the headers. | n/a | In early Beta versions of Flex 3, a verticalSeparatorSkin in a DataGrid used the skin within the header and the rest of the rows (bug: SDK-9364). Now, in Flex 3, the separatorSkin no longer draws the headers, only for the rows. | VerticalSeparatorSkin didn't exist in Flex 2.0.1. This is only a backwards compatibility issue for applications built in earlier Beta versions of Flex 3. | |
| | | *DataGrid: headerStyle* now overrides styles set on a DataGridColumn (SDK-10900) | If you set a headerStyle on a DataGrid and set styles on your DataGridColumn, the DataGridColumn styles would affect the header, overriding the styles in the headerStyle. | In Flex 3, styles set on the headerStyle override styles set on a DataGridColumn. | Applications using headerStyle and DataGridColumn styles. | |
| | | *DataGrid: Editor focus*. If there is no previous editor session, one won't get into focus when you focus on a DataGrid. (bug: SDK-9836) | If you've selected an item in the DataGrid, and there is no previous editor session, an editor is set into focus. | If you've selected an item in the DataGrid, and there is no previous editor session, the editor will get into focus. | An Application using an editable DataGrid. | |
| | | *List: Selecting a component.* An item in a List-based component that corresponds to a null object in a dataProvider cannot be selected. (SDK-13094) | In previous releases, it is possible to select a row in a List-based component that corresponded to a null object in the dataProvider. This set the selectedItem to null. | In Flex 3, you can no longer select an item corresponding to a null object. | Applications using null objects in their dataProvider for a List-based component. | |
| | | *Panel: Rounded corners.* A Panel's default rounded corners are a few pixels different in Flex 3 | n/a | n/a | This change is not very noticeable. An Application would run into it if they had a Panel with rounded corners (which is the default). | |
| | | *Button: Selected skin styles.* selectedUpSkin, selectedDownSkin, and selectedOverSkin of Button components do not size correctly. (SDK-11020) | These skins size without using any working padding styles. | Even when compiling with the \-compatibility-version flag on, there is an issue where the skins do not size correctly when the Button component is selected and then moused away from. This affects Button and components like CheckBox and RadioButton that extend Button. | Applications using custom selectedUpSkin, selectedDownSkin, and selectedOverSkin styles | |
| | | *Variables of type UITextField* that were protected are now type IUITextField. | Some protected variables are of type UITextField. | In Flex 3, the protected variables that were UITextField are now of type IUITextField. | This generates a compile error in any Application using a variable as a UITextField. For example, this affects the Flex MaskedTextInput component. | |
| | | *TileList* has different behavior when scrolling through items with the pageDown key. SDK-13665 | At the end of the TileList, there is an extra empty column. | The additional empty column no longer exists when scrolling through a TileList using the pageDown key. | Applications implementing a TileList that includes a scrollbar | |
| | \\ |
| | |
| | ---- |
| | \\ |
| | |
| | h2. Flash Player Backwards Compatibility |
| | |
| | The following table lists issues with respect to Flash Player backwards compatibility. |
| | || Summary || Player Version 9 r28 Behavior || Player Behavior in Flex 3 || Scenario || |
| | | *Skins render differently.* (Player Bug [205034|http://frpbugapp.macromedia.com/bugapp/detail.asp?ID=205034]) | | There are small differences in how some skins look in the current player and the past player. These differences have been observered in various upSkins and downSkins styles for components such as the ComboBox and NumericStepper. Here is an example. Look closely at the text in the skin. (Image:Difference.jpg). | Applications that use custom up, over, and down skins for components such as ComboBox and NumericStepper. (Other components might be affected--contact us if you run into these kind of differences.) | |
| | | *htmlText: resized images* Appearance of resized png image in htmlText has changed. (Player Bug [204829|http://frpbugapp.macromedia.com/bugapp/detail.asp?ID=204829]) | | The Images in the htmlText for the current player are not as crisp and clear. There appear to be some vertical lines going through the image. | Applications using images in htmlText for TextArea may be affected. | |
| | | *Player mm.cfg changes (Macintosh only)* | The player ignored an mm.cfg file in your Macintosh home directory /Users/<username> | The player looks for mm.cfg in your Macintosh home directory(~), generally /Users/<username>. If mm.cfg is not found, it looks for mm.cfg in /Library/Application Support/Macromedia. | Macintosh players that have an mm.cfg in /Users/<username> and /Library/Application Support/Macromedia. | |
| | |
| | {adbe-prev:http://learn.adobe.com/wiki/display/Flex/Part+IV.+Building+Your+Own+Flex+Application} |
| | {adbe-next:http://learn.adobe.com/wiki/display/Flex/Flex+Builder+3+Compiler+Errors} |
