by Jeff Swartz
10 October 2011
General experience of building applications
with Flex Builder or the Flex SDK is
suggested. For more details on getting
started with this Quick Start, refer to
Building the Quick Start sample
applications with Flex.
The sample application reads and writes data related to the position and size of the application, as well as the date saved. It also positions the window according to that data when the application opens. More specifically, this sample application demonstrates the following Adobe AIR features:
- Reading and writing to a text file
- Specifying a file in the Adobe AIR application storage directory
- Modifying the position, size, and visibility of an AIR application window
- Responding to the closing event dispatched by a Window object
Figure 1. This sample application enables you to specify XML preferences.
Note: This is a sample application provided, as is, for instructional purposes.
This sample application includes the following files:
- PrefsXMLDemo.mxml: The main application file in MXML for Flex; includes the code discussed in this article
- PrefsXMLDemo-app.xml: The AIR application descriptor file
- Sample AIR icon files
Important: The application descriptor file, FileCompressionTool-app.xml, uses the AIR 3.0 namespace. To modify and repackage this application, you need to download and use AIR 3 SDK along with Flash Builder 4.5.
Testing the application
The application reads and writes data related to the position and size of the application, as well as the date saved. It also positions the window according to that data when the application opens. The preferences are stored in a text file contains XML data. The application converts that data to an XML object, upon reading, and converts the XML data to text upon writing. To test this application, follow these steps:
- Open the application.
- Resize and reposition the window.
- Quit the application.
- Restart the application to see your preferences take effect.
Understanding the code
Note: This article does not describe all of the Flex components used in the MXML code for the file. For more information, see the ActionScript 3 Reference for the Adobe Flash Platform.
appCompleteHandler()method initializes the prefsFile File object to point to a pre-defined path and then call the
readXML()method, which reads the data:
prefsFile = File.applicationStorageDirectory; prefsFile = prefsFile.resolvePath("preferences.xml"); readXML();
File.applicationStorageDirectorypoints to the AIR application store directory, which is uniquely defined for each AIR application.
appCompleteHandler()method also sets up an event handler to respond to the window closing (which saves the preferences data to the file):
readXML()method sets up a File object and a FileStream object. The fileMode parameter of the call to the
open()method is set to
FileMode.READ, so that the FileStream object can read data from the file:
stream = new FileStream(); stream.open(prefsFile, FileMode.READ);
open()method of the stream object opens the file synchronously and begins reading data into the read buffer.
processXMLData()event method processes the XML data and closes the file. The
bytesAvailableproperty of the FileStream object is the number of bytes in the read buffer, which is all of the bytes from the file (since the file is read synchronously):
prefsXML = XML(stream.readUTFBytes(stream.bytesAvailable)); stream.close();
In the application.xml file, which defines properties of the application, the visible attribute of the
initialWindowproperty is set to
false. The window is resized and repositioned before the window is made visible.
windowproperty of the Stage object contains properties of the AIR window.
processXMLData()method resizes and repositions the window based on data in the XML preferences object (which was read in from the preferences file):
stage.nativeWindow.x = prefsXML.windowState.@x; stage.nativeWindow.y = prefsXML.windowState.@y; stage.nativeWindow.width = prefsXML.windowState.@width; stage.nativeWindow.height = prefsXML.windowState.@height;
Note: This code sample uses E4X notation, which was introduced in ActionScript 3.0. For example,
prefsXML.windowState.@xis the value of the x attribute of the
windowStateproperty of the
prefsXMLXML object. For more information, see the Working with XML chapter of the Programming ActionScript 3.0 book.
readXML()method makes the window visible after the
stage.nativeWindow.visible = true;
writeXMLData()converts the XML data to a string, adds the XML declaration to the beginning of the string, and replaces line ending characters with the platform-specific line ending character (represented by the AIR
var outputString:String = '<?xml version="1.0" encoding="utf-8"?>\n'; outputString += prefsXML.toXMLString(); outputString = outputString.replace(/\n/g, File.lineEnding);
It then sets up and uses a FileStream object for writing the data. Note that
FileMode.WRITEis specified as the
fileModeparameter in the
open()method. This specifies that the FileStream object is able to write to the file (and will truncate any existing data before writing):
stream = new FileStream(); stream.open(prefsFile, FileMode.WRITE);
writeUTFBytes()method is called, which writes the string version of the XML data to the file (as UTF-8 data):
Since this file was opened for synchronous operations (using the
open()method) and the write method is included within the event handler for the Window object's
closingevent, the file writing will complete before the window (and application) actually close. This application uses synchronous read and write operations because the XML preferences file is relatively small. If you want to write a file asynchronously, you would want to cancel the
closingevent, and explicitly close the application by calling the
NativeApplication.nativeapplication.exit()) method in an event handler for the outputProgress event dispatched by the FileStream object.