Adobe AIR Quick Start

Building a text-file editor

The Text Editor sample application shows a number of features of working with files in Adobe AIR, including the following:

• Setting up a File object to point to a file path.
• Using the FileMode and FileStream classes to read data from the file.
• Using the FileMode and FileStream classes to write data from the file.

Note: This is a sample application provided, as is, for instructional purposes.

Figure 1. This sample application is a simple editor of plain text files.

Note: This is a sample application provided, as is, for instructional purposes.

Requirements

To make the most of this article, you need the following software and files:

Adobe AIR

• Download

Adobe AIR SDK

• Download

Sample files:

• TextEditorHTML.zip (ZIP, 41K)
• TextEditorHTML.air (AIR, 89K)

This sample application includes the following files:

• Index.html: The main application content.
• AIRAliases.js: The AIR JavaScript aliases file
• Application.xml: The AIR application descriptor file that you use to debug and build the application (using ADL and ADT).
• Sample AIR icon files

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.

Testing the application

Download and launch the application's installer (TextEditorHTML.air) to install the application. The application is a simple editor of plain text files. The application uses UTF-8 encoding for reading and writing all text files.

Understanding the code

For more information about using AIR classes, see the Adobe AIR Language Reference for HTML Developers.

Pointing a File object to a file

The init() method sets the defaultDir File object to point to a predefined path:

defaultDir = air.File.documentsDirectory;

This code sets the object to point to the user's documents directory. On Windows, this is the My Documents directory. On Mac OS X, it is the /Users/userName/Documents directory.

The defaultDir file is later referenced by the FileChooser window, if the user has not yet selected a file path.

Browsing for a file

When the user clicks the Open button, the openFileDB() method calls the browseForOpen() method of a File object to open a new file browser dialog box:

var fileChooser;
if(currentFile)
{
    fileChooser = currentFile;
}
else
{
    fileChooser = defaultDir;
}
fileChooser.browseForOpen("Open");

When the user clicks the Save As button in the main window, the saveAs() method calls a similar method: the browseForSave() method of a File object:

var fileChooser;
if(currentFile)
{
    fileChooser = currentFile;
}
else
{
    fileChooser = defaultDir;
}
fileChooser.browseForSave("Save");

Reading a file

When the user selects a file to open, the fileChooser File object dispatches a select event. The openFile() function is registered as the event listener for this event. It sets up a new FileStream object, named stream, and

stream = new air.FileStream();
try
{
    document.getElementById("mainText").value = "";
    currentFile = event.target;
    stream.open(currentFile, air.FileMode.READ);
    var str = stream.readUTFBytes(stream.bytesAvailable);
    stream.close();
    document.getElementById("mainText").value = str;
    document.title = "Text Editor - " + currentFile.name;
}
catch(error)
{
    ioErrorHandler()
}

Note: The code to open and read the file is enclosed in a try/catch structure, so that if there is an I/O error, the ioErrorHandler() method is invoked.

The open() method of the stream object has two parameters:

• The first parameter is the File object to open—in this case, the main file object in the application.
• The second parameter is the file mode defined by one of the constants of the FileMode class—in this case, the READ constant, which allows for data reading.

The readUTFBytes() method reads UTF-8 text data from the file. The parameter of the method is passed stream.bytesAvailable, so that the entire file is read. Once it is read, the data is passed to the mainText TEXTAREA element of the page.

This example uses the open() method, which opens the file for synchronous operations. You could also use the openAsync() method to open the file for asynchronous operations. However, if you did, you would need to set up event listeners to handle complete and ioError events.

Writing data to a file

When the user clicks the Save button, the saveFile() method is invoked. It sets up a new FileStream object, named stream, and writes data to the file.

try
{
    stream = new air.FileStream();
    stream.open(file, air.FileMode.WRITE);
    var outData = document.getElementById("mainText").value;
    outData = outData.replace(/\n/g, air.File.lineEnding);
    stream.writeUTFBytes(outData);
    document.title = "Text Editor - " + file.name;
}
catch(error)
{
    ioErrorHandler()
}

The code to open and read the file is enclosed in a try/catch structure, so that if there is an I/O error, the ioErrorHandler() method is invoked.

The open() method of the stream object has two parameters:

• The first parameter is the File object to open—in this case, the main file object in the application.
• The second parameter is the file mode defined by one of the constants of the FileMode class—in this case, the WRITE constant, which allows for data writing and overwrites any existing data in the file.

The fourth line after the try statement replaces the \n newline characters in the TEXTAREA data with the platform-specific line ending character, which is represented by the static File.lineEnding property:

outData = outData.replace(/\n/g, air.File.lineEnding);

The writeUTFBytes() method writes UTF-8 text data to the file.

This example uses the open() method, which opens the file for synchronous operations. You could also use the openAsync() method to open the file for asynchronous operations. However, if you did, you would need to set up event listeners to handle outputProgress and ioError events.

Using asynchronous operations can allow other processes, such as a graphical progress status, to take place as files are read and written (asynchronously).

About the author