Building a text file editor
Back to: Apollo Documentation home page
The Text Editor sample application shows a number of features of working with files in Apollo, including the following:
- Setting up a File object to point to a file path.
- Getting the system-specific path (nativePath) for the file.
- Using the FileMode and FileStream classes to read data from the file.
- Using the FileMode and FileStream classes to write data from the file.
- Using events to handle asynchronous processes.
Note: This is a sample application provided, as is, for instructional purposes.
| Contents |
|---|
Installing and testing the application
The TextEditor application is intentionally simple. The intent is to show you the basics of how to work with files in Apollo.
The installer (AIR) file for this sample application is available in the Samples directory included with the documentation at the Apollo pre-release site.
The application is a straightforward, but simple, editor of plain text files. The application uses UTF-8 encoding for reading and writing all text files.
Files used to build the application
The application is built from the following source files:
| File | Description |
|---|---|
| TextEditor.mxml | The main application file in MXML for Flex. Details of the code are discussed in the Understanding the code section. |
| FileOpenPanel.mxml | A Flex component that lets the user select a file to open. |
| FileSavePanel.mxml | A Flex component that lets the user select a path to use to save a file. |
| TextEditor-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 (409K).
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.
Pointing a File object to a file
The appCompleteHandler() method sets the defaultFile File object to point to a pre-defined path:
defaultFile = File.documentsDirectory.resolve("test.txt");
This code sets the File object to point to the "text.txt" file in the user's documents directory. On Windows, this is the "My Documents" directory. On Mac OS, it is the /Users/userName/Documents directory.
The defaultFile File is later passed to Open and Save As pop-up windows, if the user has not yet selected a file path.
Reading a file
The openFile() method contains code that opens a pop-up window (defined int the FileOpenPanel.mxml file), in which the user can select a file. When the user selects a file in this pop-up window and clicks the OK button. The fileOpenSelected() method is called. The method first initiates the file File object to point to the path specified by the user:
currentFile = event.file;
Next a the stream FileStream object is closed (in case it currently has a file open) and the stream FileStream object are initialized:
if (stream != null)
{
stream.close();
}
stream = new FileStream();
stream.openAsync(currentFile, FileMode.READ);
Note that the fileMode parameter of the openAsync() method is set to FileMode.READ. This lets you read the file.
Event handlers are set up to respond to the complete and ioError events:
stream.addEventListener(Event.COMPLETE, fileReadHandler); stream.addEventListener(IOErrorEvent.IO_ERROR, readIOErrorHandler);
Apollo begins reading the file asynchronously, and the Apollo runtime automatically starts reading the file in and firing events. Note that you can add these event listeners after calling the openAsync() method, because the Apollo runtime will complete executing this ActionScript code (the block of code that includes the calls to addEventListener() methods) before responding to any events.
Note: This sample application shows how to read a file asynchronously. You can also read the file synchronously by calling the open() method when opening the file, rather than calling the openAsync() method. For more information, see Synchronous and asynchronous methods.
If the stream object dispatches an ioError event, the readIOErrorHandler() displays an error message for the end user.
When the file is read in fully, the stream object dispatches the complete event, and the fileReadHandler()) method reads and processes the file.
The readUTFBytes() method of the stream object returns a string by reading UTF-8 characters from specified number of bytes. Since the stream object just dispatched complete event, the bytesAvailable property represents the total length of the file, and it is passed as the length property of the call to the readUTFBytes() method:
var str:String = stream.readUTFBytes(stream.bytesAvailable);
The following code replaces the line ending characters from the file with the "\n" newline character, which is used in a TextField object in a SWF file. It then assigns the string to the text property of the Text control:
var lineEndPattern:RegExp = new RegExp(File.lineEnding, "g"); str = str.replace(lineEndPattern, "\n"); mainTextField.text = str;
Writing data to a file
The saveFile() contains code that writes the text to the file.
First, the method checks to see if the main File object is set:
if (currentFile)
The currentFile object is undefined when the user first opens the application, and when the user clicks the New button. If there is no currentFile defined, then the saveAs() method is called (in the else block), which lets the user select a file path for saving the file.
Next the stream FileStream object is closed (if it is currently open) and then it is initialized:
if (stream != null)
{
stream.close();
}
stream = new FileStream();
stream.openAsync(currentFile, FileMode.WRITE);
Note that the mode parameter of the openAsync() method is set to FileMode.WRITE. This lets you write to the file.
An event handlers is set up to respond to the any ioError events:
stream.addEventListener(IOErrorEvent.IO_ERROR, writeIOErrorHandler);
The following code replaces the the "\n" newline character, which is used in a TextField object in a SWF file, with the line ending character used in text files in the file system (File.lineEnding) It then assigns the string to the text property of the Text control:
var str:String = mainTextField.text; str = str.replace(/\r/g, "\n"); str = str.replace(/\n/g, File.lineEnding);
The writeUTFBytes() method of the stream object writes a string to the file in UTF-8 format and then closes the file:
stream.writeUTFBytes(str); stream.close();
If the stream object dispatches an ioError event, the writeIOErrorHandler() displays an error message to the end user.
Back to: Apollo Documentation home page