AIR:Migration
From Adobe Labs
Adobe AIR Beta 2 Migration Notes
September 30, 2007
| Table of contents |
Migrating your application descriptor (application.xml) files from Beta 1 to Beta 2
To update applications built for AIR Beta 1 so that they work with AIR Beta 2, make the following changes in the application descriptor file:
- Change xmlns to “http://ns.adobe.com/air/application/1.0.M5”
- Create initialWindow element in application descriptor
- Move rootContent element to initialWindow/content. All attributes previously in the rootContent element should be moved out of rootContent and become elements (not attributes) of the initialWindow element, as in the following:
<initialWindow>
<content>Main.swf</content>
<systemChrome>standard</systemChrome>
</initialWindow>
Setting the visible property of the initialWindow element is optional, and default value (for visible) when omitted is false. Set visible to true if you want the the main window of the application to be visible from the start.
For example, here is a sample application descriptor for Beta 1.
<?xml version="1.0" encoding="utf-8" ?>
<application
xmlns="http://ns.adobe.com/air/application/1.0.M4"
appId="sampleapp"
version="1.1">
<name>Sample</name>
<title>Sample Application</title>
<description>Sample App!</description>
<publisher>Sample</publisher>
<copyright>Sample app copyright information</copyright>
<rootContent visible="true" transparent="false" systemChrome="standard" width="800" height="600">SampleApplication.swf</rootContent>
</application>
Here is the equivalent application descriptor file in Beta 2:
<?xml version="1.0" encoding="utf-8" ?>
<application
xmlns="http://ns.adobe.com/air/application/1.0.M5"
appId="Sample"
version="1.2">
<name>Sample</name>
<description>Sample app!</description>
<copyright>Sample app copyright information</copyright>
<title>Sample Application </title>
<initialWindow>
<title>Main Window</title>
<content>SampleApplication.swf</content>
<systemChrome>standard</systemChrome>
<transparent>false</transparent>
<visible>true</visible>
<minimizable>true</minimizable>
<maximizable>true</maximizable>
<resizable>true</resizable>
<width>800</width>
<height>600</height>
<x>150</x>
<y>150</y>
</initialWindow>
</application>
Migrating Apollo projects created in Flex Builder 2.0.1 to Flex Builder 3.0 Moxie
AIR applications developed using Flex Builder 2.0.1 and the Alpha version of AIR (referred to by its code name Apollo), are not supported in Flex and Flex Builder 3. To port your AIR applications to the new version, you need to do the following:
If you’re using Flex Builder:
- Create a new AIR project in Flex Builder.
- Copy and paste the application code from your old Apollo project’s main MXML file into the new AIR project MXML file. Note that the AIR application container (ApolloApplication) has been changed to WindowedApplication.
- If you made any additions or customizations to the application descriptor file in your Flex Builder 2.0.1 project, they will need to be replicated in the application descriptor of your new AIR project in Flex Builder 3.0.
- Add your project’s assets into the new project using the Flex Builder project navigator.
- Update any remaining code that refers to the ApolloApplication container.
If you’re using the Flex SDK:
- Recreate the application.xml file.
- Update your code with the new name for the AIR application container (WindowedApplication).
Changes/Updates to AIR APIs
ByteArray
ByteArray.inflate() and ByteArray.deflate() have been deprecated and removed. They are now replaced with a new algorithm argument (defined by CompressionAlgorithm.DEFLATE and CompressionAlgorithm.ZLIB) to ByteArray.compress() and ByteArray.uncompress().
Clipboard, Drag and Drop
There are changes for clipboard and drag and drop APIs. Any application using ClipboardManager, TransferableData, and DragManager class need to be updated:
The TransferableData and ClipboardManager classes have been removed and are replaced by the Clipboard class. Instead of using ClipboardManager.accessClipboard() to read and write to the system clipboard, you must now use the Clipboard.generalClipboard singleton object.
DragManager.isDragging is now a property instead of a method.
Door
The Door class has been removed. The Door-related API in the LoaderInfo class has been renamed to sandboxBridge, as listed below:
- LoaderInfo.parentDoor –> LoaderInfo.parentSandboxBridge
- LoaderInfo.childDoor –> LoaderInfo.childSandboxBridge
Please refer to the “Adobe AIR HTML Security Changes FAQ” for more details.
File API
There are few File API changes and application using these functions must be updated:
- File.listDirectories() –> File.getDirectoryListing()
- File.listDirectoriesAsync() –> File.getDirectoryListingAsync()
- File.listRootDirectories() –> File.getRootDirectories()
- File.relativize() –> File.getRelativePath()
- File.resolve() –> File.resolvePath()
- The clobber parameter has been renamed overwrite
HTML
For loading SWF libraries into HTML using script tag, type attribute is now required. The type attribute should be set to “application/x-shockwave-flash”, as in the following:
<script src="swflib.swf" type="application/x-shockwave-flash" />
NativeWindow
The visible parameter in the NativeWindow constructor has been removed and the constructor now only takes one parameter. The visible property has been added to NativeWindow and can be set after the NativeWindow object is instantiated.
- Stage.window has been changed to Stage.nativeWindow.
- NativeWindowCapabilties has been removed and the properties has been relocated to NativeWindow class.
- NativeWindowCapabilities.hasWindowIcon –> NativeWindow.supportsIcon
- NativeWindowCapabilities.hasMenu –> NativeWindow.supportsMenu
- NativeWindowCapabilities.windowMinSize –> NativeWindow.systemMinSize
- NativeWindowCapabilities.windowMaxSize –> NativeWindow.systemMaxSize
Relative URLs
For beta 1 and earlier, relative URLs were resolved against app-resource:/. Starting beta 2, all relative URLs will resolve relative to the calling SWF or HTML content. This includes URLs used in URLRequest objects and in loading content from RSLs. It also applies to URLs used in all ActionScript code, including ActionScript 1, ActionScript 2, and ActionScript 3.
System
System.pause(), System.resume(), and System.gc() are now only enabled when the debugging mode is enabled. (The debugging mode is enabled using ADL unless the -nodebug flag is specified.) System.exit() is now disabled in AIR, and calling System.exit will throw an exception. User Shell.exit() instead.
HTML security
Beta 2 has improved security for content displayed in the HTMLControl object and in HTML-based applications. Some calls to the JavaScript eval() function and changes to innerHTML properties of DOM object that were previously allowed are now restricted in content in the application security sandbox. Those calls still work in content in other security sandboxes.
Please refer to the “Adobe AIR HTML Security Changes FAQ” for more details (http://labs.stage.adobe.com/wiki/index.php/AIR:HTML_Security_FAQ).
Debugging Mode
The debugging mode is enabled when launching an application from ADL, unless the -nodebug flag is specified. When in debugging mode, the runtime makes additional checks and generates additional debugging information. In case of an error, debugging messages may get displayed. The debugging mode can cause an application to run more slowly but can be helpful to isolate errors.
Seamless Installation Update
For AIR Beta 2 the badge detection logic (install.as) and badge file (badge.fla) have been updated. To update your existing badge while keeping your existing badge look and feel, take your badge.fla and the AIR Beta 2 intall.as file and create a new badge. Change the “airversion” variable setting to 1.0.M5
Note: Using a version of Flash Player 7 or below may cause some instability when using the sample badge provided. Flash Player 8 or greater is recommended.
