Reading from and writing to an XML preferences file
Requirements
Prerequisite knowledge
General experience building HTML-based applications is suggested. For more details on getting started with this Quick Start, refer to Building the Quick Start sample applications with HTML.
Additional Requirements
User level
Intermediate
Required products
Sample files
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:
- index.html: The main application source code.
- AIRAliases.js: The AIR JavaScript aliases file
- application.xml: The AIR application descriptor file
- Sample AIR icon files
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
This section does not describe all of the HTML mark-up for the file—only the AIR specific JavaScript code.
Reading data from the XML file
The init() method initializes the prefsFile File object to point to a predefined path and then call the readXML() method, which reads the data:
prefsFile = air.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 init() method also sets up an event handler to respond to the window closing (which saves the preferences data to the file):
window.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 (if it exists).
stream = new air.FileStream();
if (prefsFile.exists) {
stream.open(prefsFile, air.FileMode.READ);
processXMLData();
}
The open() method of the stream object opens the file synchronously and begins reading data into the read buffer.
The processXMLData() 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 = stream.readUTFBytes(stream.bytesAvailable);
stream.close();
Repositioning and resizing the application window
The processXMLData() function uses JavaScript DOM API to 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):
var domParser = new DOMParser();
prefsXML = domParser.parseFromString(prefsXML, "text/xml");
var windowState = prefsXML.getElementsByTagName("windowState")[0];
window.moveTo(windowState.getAttribute("x"), windowState.getAttribute("y"));
document.getElementById("xPositionField").value = windowState.getAttribute("x");
document.getElementById("yPositionField").value = windowState.getAttribute("y");
window.resizeTo(windowState.getAttribute("width"), windowState.getAttribute("height"));
document.getElementById("widthField").value = windowState.getAttribute("width");
document.getElementById("heightField").value = windowState.getAttribute("height");
document.getElementById("dateField").value =
prefsXML.getElementsByTagName("saveDate")[0].firstChild.nodeValue;
In the application.xml file, which defines properties of the application, the visible property of the initialWindow property is set to false. The window is resized and repositioned before the window is made visible.
The readXML() method makes the window visible after the processXMLData() method returns:
window.nativeWindow.visible = true;
Writing XML data to the file
The createXMLData() function 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 File.lineEnding constant):
var cr = air.File.lineEnding;
prefsXML = "<?xml version='1.0' encoding='utf-8'?>" + cr
+ "<preferences>" + cr
+ " <windowState" + cr
+ " width = '" + window.outerWidth.toString() + "'" + cr
+ " height = '" + window.outerHeight.toString() + "'" + cr
+ " x = '" + window.screenLeft.toString() + "'" + cr
+ " y = '" + window.screenTop.toString() + "'" + "/>" + cr
+ " <saveDate>"
+ new Date().toString()
+ "</saveDate>" + cr
+ "</preferences>";
document.getElementById("widthField").value = window.outerWidth.toString();
document.getElementById("heightField").value = window.outerWidth.toString();
document.getElementById("xPositionField").value = window.screenLeft.toString();
document.getElementById("yPositionField").value = window.screenTop.toString();
The writeXMLData() function 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 truncates any existing data before writing):
stream = new air.FileStream();
stream.open(prefsFile, air.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(prefsXML);
stream.close();
When the user closes the window, the NativeWindow object dispatches a closing event. The event handler for this event cancels the default behavior of the event (which is to close the application, and calls the saveData() method, which saves the XML data. After the data is saved, the code closes the application by calling the NativeApplication.nativeApplication.exit() method:
function windowClosingHandler(event)
{
event.preventDefault();
nativeWindow.removeEventListener("closing", windowClosingHandler)
saveData();
air.NativeApplication.nativeApplication.exit();
}
