Using the File System API

Some of the methods of the File class (such as
File.copyFile()andFile.copyFileAsync()) and of theFileStream class have both synchronous and asynchronous versions.

The synchronous methods don’t relinquish control until the file operation is complete. The asynchronous methods run in the background, allowing other ActionScript processes to take place at the same time. When the asynchronous file operation finishes, an event is dispatched to notify listeners that it is done.

Here’s an example of copying a file using the synchronouscopyTo()method:

  var file1:File = File.documentsDirectory.
  resolve("ApolloTest/test.txt");
  var file2:File = File.documentsDirectory.
  resolve("ApolloTest/copy of test.txt");
  file1.copyTo(file2);
  trace("Not output until the file is copied.");

Here’s an example of copying a file using the asynchronouscopyToAsync()method:

  var file1:File = File.documentsDirectory.
  resolve("ApolloTest/test.txt");
  var file2:File = File.documentsDirectory.
  resolve("ApolloTest/copy of test.txt");
  file1.copyToAsync(file2);

  file1.addEventListener(Event.COMPLETE, completeHandler);
  trace("This line executes before the complete event.");
  trace("So does this line.");

  private function completeHandler(event:Event):void {
    trace("Done.");
  }

The following table lists the asynchronous methods of theFile class (all of which have synchronous counterparts) and the events that can fire after the method is called:

When you open a file, use either theopen()oropenAsync()method of theFileStreamobject. The first opens the file for synchronous operations, and the second opens the file for asynchronous operations. For more information, see “The open( ) and openAsync( ) Methods” later in this chapter.

Use asynchronous methods whenever you want to make sure that other essential ActionScript-driven processes—such as progress bar animation—continue while the file operations take place. For example, you could use theopen()(synchronous) method of aFileStreamobject if you are going to write a small file (1 MB or less) and use theopenAsync()method when writing larger files, or when the file size is unknown.

For more information on asynchronous methods in general, see the “Handling Events” chapter in Programming ActionScript 3.0, which is available at:

http://livedocs.macromedia.com/flex/2/docs/Part5_ProgAS.html

Please check back next week for the conclusion to this article.