Reading from and writing to an XML preferences file
Requirements
Prerequisite knowledge
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.
User Level
Intermediate
Required products
- Adobe AIR
- Flash Builder (Download trial)
- Flex (Download trial)
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
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.
Reading data from the XML file
The 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.applicationStorageDirectory points to the AIR application store directory, which is uniquely defined for each AIR application.
The appCompleteHandler() method also sets up an event handler to respond to the window closing (which saves the preferences data to the file):
stage.nativeWindow.addEventListener(Event.CLOSING, windowClosingHandler);
The 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);
The open() method of the stream object opens the file synchronously and begins reading data into the read buffer.
The processXMLData() event method processes the XML data and closes the file. The bytesAvailable property 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();
Repositioning and resizing the application window
In the application.xml file, which defines properties of the application, the visible attribute of the initialWindow property is set to false . The window is resized and repositioned before the window is made visible.
The window property of the Stage object contains properties of the AIR window.
The 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.@x is the value of the x attribute of the windowState property of the prefsXML XML object. For more information, see the Working with XML chapter of the Programming ActionScript 3.0 book.
The readXML() method makes the window visible after the processXMLData() method returns:
stage.nativeWindow.visible = true;
Writing XML data to the file
The 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 File.lineEnding constant):
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.WRITE is specified as the fileMode parameter 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);
Next, the writeUTFBytes() method is called, which writes the string version of the XML data to the file (as UTF-8 data):
stream.writeUTFBytes(outputString);
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 closing event, 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 closing event, 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.