Using the File System API

Apollo applications can run on multiple platforms, including Windows and Mac OS. The Apollo file API uses platform-neutral code syntax so you don’t have to write any OS-specific code.

For example, the way you represent a path to a file differs between Mac OS and Windows:

1. A typical file path on Mac OS is /Users/joe/Documents/test.txt
   
2. A typical file path on Windows is C:\Documents and Settings\joe\My Documents\test.txt

However, you can use exactly the same Apollo components, classes, methods, and properties to access files in either operating system.

An ActionScriptFile object is a pointer to a file or directory. TheFileclass includes the static propertydocumentsDirectory, which contains aFileobject that points to the user’s documents directory. This is the My Documents directory on Windows, and it is the Documents subdirectory of the user directory on Mac OS, as illustrated in the following code:

  trace(File.documentsDirectory.nativePath)
       // On Windows:
       //       C:\Documents and Settings\joe\MyDocuments
       // On Mac OS:  /Users/joe/Documents

Once you point aFileobject to a directory, you can use theresolve()method to modify it to point to a file or subdirectory within that directory (or within a subdirectory). For example, the following code creates an Apollo Test subdirectory of the user’s documents directory:

  var newDir:File = File.documentsDirectory;
  newDir = newDir.resolve("ApolloTest");
  newDir.createDirectory();

AFileobject can point to either a file or a directory. Also, aFileobject may point to a file or directory that does not exist, as in the previous example. This lets you point aFileobject to a directory location that you wish to create.

File Class Properties for Accessing Common Directory Locations

The Fileclass includes the following static properties, which point to commonly used directory locations:

Continued

The url and nativePath Properties of a File Object

The urlproperty of aFile object returns the location of a file or folder as a platform-independent string that begins with a URL scheme, such asfile, as in the following:

  var directory:File = File.userDirectory;
  trace(directory.url)
    // on Windows: file:///C:/Documents%20and%20Settings
    // on Mac OS: file:///Users

whereas thenativePath property of aFileobject returns a string that is unique to Windows or Mac OS. For example, you can use this code to point to a specific file on a Windows computer:

  var file:File = new File();
  file.nativePath = "c:/ApolloTest/surprise.txt";

However, it is generally better to start with one of the static properties listed in the table in the previous section (such as theFile.appStorageDirectory)—that point to known directories on the operating system—and then use theresolve()method to create to a relative path based on that directory, as in this code:

  var logFile:File = File.appStorageDirectory;
  logFile = logFile.resolve("log.txt");

Use the application store directory to store files that you want your application to be able to access in the future but that the end user may not need to know about. For instance, this is a good place to store preferences files.