Migrating from 1.3 to 2.0
This topic contains the following information to successfully migrate from 1.3 to 2.0:
The following requirements have changed at 2.0:
Flash Player 10 or higher
As part of the move to Flex 4 SDK, Flash Player 10 or higher is now required.
Using Flex 4 SDK instead of Flex 3 SDK
Adobe Flash Builder 4 is very similar to Flex Builder 3, and you should feel right at home from the beginning.
For a basic application, the only migration step is to specify the theme. In Adobe Flash Builder 4, there is an option for "component set" where you can choose either MX+Spark (the default) or MX only. To specifically set existing applications to use the "old" Halo theme, add the following compiler arguments to Project Properties > Flex Compiler:
While it's possible to continue to use Flex Builder 3 if you add Flex 4 SDK support, the documentation in this Help system assumes you're using Adobe Flash Builder 4 or later. Similarly, while there are other integrated development environments (IDEs) you can use, the documentation herein assumes you're using Flash Builder.
Upgrading your Flex API application code from 1.3 to 2.0
The information in this section is to ensure your ArcGIS API for Flex 1.3 code works with ArcGIS API for Flex 2.0 and above. For information on upgrading your code for general Flex 3 to Flex 4 conversion, see Upgrading your Adobe Flex 3 SDK code to Flex 4 SDK below.
Converting from 1.3 to 2.0 of the ArcGIS API for Flex
The following sections explain the changes you need to make to convert from ArcGIS API for Flex 1.3 to ArcGIS API for Flex 2.0:
Connecting to ArcGIS Server 9.3.x
If you're connecting to an ArcGIS 9.3.x server (as opposed to 10 or later), you might have to adjust your code as follows, but everything else should work just fine.
- For Query and Geoprocessor, add useAMF="false" since AMF is now the default output format, and older servers do not support AMF.
- For ArcGISImageServiceLayer, if you're not already specifying imageFormat, add imageFormat="png" since "jpgpng" is now the default output format, and older servers do not support this image format.
- Change barriers to pointBarriers.
- Change returnBarriers to returnPointBarriers.
- Change RouteSolveResult.barriers to RouteSolveResult.pointBarriers
Project property changes
Change the required Flash player version to 10 or higher. Otherwise you might get the following error: "1046: Type was not found or was not a compile-time constant: Matrix3D."
Change the SDK version to Flex 4. Otherwise you might get the following error: "1046: Type was not found or was not a compile-time constant: SolidColorStroke."
The easiest way to update the import statements in your code to use the new package stcture is to open your code in Flash Builder 4, set the project to use the Flex 4 SDK and the 2.0 version of the Flex API, then fix each error as it occurs. One way to do this is to go to the problem line by double-clicking an error, such as "1046: Type was not found or was not a compile-time constant: FeatureSet.", put the cursor at the end of "FeatureSet", and press Ctrl-Space. Flash Builder will then add the missing import statement and organize all your import statements as well. The following is a more extensive list, but again, the easiest way is to take advantage of the IDE and step through the errors.
- The package "controls" has been renamed to components.
- The package "symbol" has been renamed to symbols to follow Flex 4 syntax.
- The package "toolbars" has been renamed to tools to clarify that it contains tools (or functionality) rather than visual toolbars.
- Supporting classes in the Layers package have moved to a subpackage: com.esri.ags.layers.supportClasses.
- Supporting classes in the Renderers package, that is, ClassBreakInfo and UniqueValueInfo, have moved to a subpackage: com.esri.ags.renderers.supportClasses.
- Supporting classes in the Tasks package have moved to a subpackage, com.esri.ags.tasks.supportClasses, except for FeatureSet, which is now in com.esri.ags.FeatureSet.
- Supporting classes in the infoClasses and navigationClasses packages have moved to a common package: com.esri.ags.components.supportClasses.
- All events are now in the Events package. This has affected InfoPlacementEvent and VEGeocodeEvent.
- Due to the package changes, you might have to add import statements for certain classes, for example, the FeatureSet class, which has moved from the com.esri.ags.tasks package to the com.esri.ags package. You'll get a compile error, for example "1046: Type was not found or was not a compile-time constant: FeatureSet." One way to fix this is to go to the problem line, put the cursor at the end of "FeatureSet", and press Ctrl-Space. Flash Builder will then add the missing one and organize all your import statements.
The following name changes are effective at 2.0:
- The Draw and Navigation tools have been renamed to DrawTool and NavigationTool, respectively.
- The arealengthsComplete event in GeometryService has been renamed to areasAndLengthsComplete.
- The arealengths property in GeometryServiceEvent has been renamed to areasAndLengthsComplete.
- GPDateUtil has been renamed DateUtil, since dates aren't specific to just the geoprocessor. The class has moved from com.esri.ags.tasks to com.esri.ags.util for the same reason.
- Geoprocessor.outSpatialReference is the new name for the Geoprocessor.outputSpatialReference property. This makes it consistent with the other "out" SpatialReference properties.
- The getLayerDetails() methods on ArcGISDynamicMapServiceLayer and ArcGISTiledMapServiceLayer have been renamed to getDetails(). They also have a new additional method called getAllDetails().
- All BufferParameters.UNIT_* constants have been renamed to GeometryService.UNIT_*, since they've moved to the GeometryService class.
- Change BaseTask.sendURLVariable was changed to BaseTask.sendURLVariables (it's now plural).
- Routing now also supports line and polygon barriers. Consequently, the barriers properties on RouteParameters and RouteSolveResult have been renamed pointBarriers, and the returnBarriers property on RouteParameters has been renamed returnPointBarriers.
The following items are effective at 2.0:
- Replace the "features" property with "geometries", and make sure you update the value from an array of features to an array of geometries.
- The Extent.contains() method now takes any geometry, combining and expanding the functionality of the old contains(point) and containsExtent(extent) methods.
- The Navigation and Scalebar classes have been "sparkified" to take advantage of new Flex 4 functionality. You can now change the full skin parts instead of just some CSS settings. As part of this, four classes (NavigationEvent, NavigationMinusButton, NavigationPlusButton, and NavigationSlider) have been removed and replaced with three skins (NavigationSkin, NavigationZoomInButtonSkin, and NavigationZoomOutButtonSkin).
- Since FeatureLayer now supports selections, there is less reason to perform selections yourself using the Extent.contains() method.
- Inputs for GeometryService are now geometries instead of graphics. See the following code example:
//1.3: geometryService.project(graphics, new SpatialReference(32618)); //2.0: geometryService.project([graphic.geometry], new SpatialReference(32618));
- GeometryServiceEvent now has a generic "results" property instead of arealengths, graphics, lengths, and relations (depending on the specific method). In the case of a lengths operation, use Array(event.result) instead of event.lengths as shown in the following code example:
//1.3: Alert.show( "Length of line:" + Number(event.lengths/1000).toFixed(0) + " km." ); // 2.0: Alert.show( "Length of line:" + Number((event.result as Array) / 1000).toFixed(1) + " km.");
- In the response from a buffer operation, the GeometryServiceEvent now returns "result" instead of "graphics". In the case of a buffer operation, the actual geometries are now returned instead of an array of graphics as shown in the following code example:
//1.3: for each ( var graphic:Graphic in event.graphics ) // 2.0: for each ( var polygonGeometry:Polygon in event.result)
- The LayerEvent.TILES_UPDATED constant has been renamed to LayerEvent.UPDATE_END. There's also a matching LayerEvent.UPDATE_START.
- The AREA_LENGTHS_COMPLETE constant in GeometryServiceEvent has been renamed to AREAS_AND_LENGTHS_COMPLETE.
- The GRAPHIC_CLEAR constant has moved from GraphicEvent to GraphicsLayerEvent.
- The parameterValues property in ExecuteResult has been renamed to "results". It still returns an array of ParameterValue.
- If you're using graphics with PictureMarkerSymbol and listening to events such as a mouse click, the target is now a custom sprite. In 1.3, the target was a graphic. For more information see the Adobe help page on event propagation.
Upgrading your Adobe Flex 3 SDK code to Flex 4 SDK
To upgrade your Adobe Flex 3 SDK code to Flex 4 SDK, open your existing application and make sure the SDK version is set to Flex 4 (in either Flex Builder or Flash Builder). When you compile it, you might get some errors, or it might just work. Be sure to read the Adobe Flex 4 Features and Migration Guide.
The Adobe Flex Developer Center is a great place to learn more about Flex in general. The following links might also be useful in your migration:
- Introducing Adobe Flex 4 SDK
- What's New in Flash Builder 4 (more than 70 new features)
- Moving existing Flex projects from Flex Builder 3 to Flash Builder 4
- Differences between Flex 3 and Flex 4
The following sections show the steps to migrate Flex 3 code to Flex 4.
Make it work with Flex 4 SDK
Replace Application.application (as in Application.application.url) with FlexGlobals.topLevelApplication (and FlexGlobals.topLevelApplication.url).
Switch from Halo (mx) components to Spark components (optional)
- Replace mx:Application with s:Application, and set the namespaces
as shown in the following code example:
xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:mx="library://ns.adobe.com/flex/mx" xmlns:esri="http://www.esri.com/2008/ags"
- Put any declarations inside fx:Declarations.
- Replace mx:style with fx:style.
- Replace mx:ArrayCollection with s:ArrayCollection.
- Replace mx:Number with fx:Number.
- Consider replacing mx:Text with s:Label.
- Default layout is now absolute. To keep it as "vertical", add the following:
<s:layout> <s:VerticalLayout/> </s:layout>
- Remove any instances of layout="absolute", since it is now the default.
Take advantage of new features in Flex 4 SDK (optional)
Read up on Flex 4 and learn more about Spark components, new layouts, skinning, and styling possibilities.