Reading and writing from an XML preferences file
Back to: Apollo Documentation home page
This section shows the following Apollo features:
- Reading and writing to a text file
- Specifying a file in the Apollo application storage directory
- Modifying the position, size, and visibility of an Apollo application window
- Responding to the closing event dispatched by a Window object
Note: This is a sample application provided, as is, for instructional purposes.
| Contents |
|---|
Installing and testing the application
The application is intentionally simple. 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 based on 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 the application:
- Open the application.
- Resize and reposition the window.
- Click the Save Preferences button.
The application writes the new data to the XML file. - Restart the application to see your preferences take effect.
Files used to build the application
The application is built from the following source files:
| File | Description |
|---|---|
| PrefsXMLDemo.mxml | The main application file in MXML for Flex. Details of the code are discussed in the Understanding the code section. |
| PrefsXMLDemo-app.xml | The Apollo application descriptor file. |
| icons/ApolloApp_16.png icons/ApolloApp_32.png icons/ApolloApp_48.png icons/ApolloApp_128.png | Sample Apollo icon files. |
To download the source files for this example, click here (284K).
For help on building this quick start sample application, see How to build the quick start sample applications.
Understanding the code
The following sections discuss how the Apollo-related code works in the file.
This article does not describe all of the Flex components used in the MXML code for the file. For information on these, see the Flex 2.0 Language Reference.
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.appStorageDirectory;
prefsFile = prefsFile.resolve("preferences.xml");
readXML();
File.appStorageDirectory points to the Apollo application store directory, which is uniquely defined for each Apollo 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.window.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 rootContent 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 Apollo window.
The processXMLData() method resizes and repositions the window based on data in the XML preferences object (which was just read in from the preferences file):
stage.window.x = prefsXML.windowState.@x; stage.window.y = prefsXML.windowState.@y; stage.window.width = prefsXML.windowState.@width; stage.window.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.window.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 Apollo 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 will be 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 were to want to write a file asynchronously, you would want to cancel the closing event, and explicitly close the application by calling the Shell.shell.exit()) method in an event handler for the outputProgress event dispatched by the FileStream object. For more information, see Synchronous and asynchronous methods.
Back to: Apollo Documentation home page