The Adobe AIR File API

The idea behind Adobe AIR is to allow developers to use their existing Adobe Flash, Adobe Flex, Hypertext Markup Language (HTML), and JavaScript skills to move their applications from the Web browser onto the desktop. The ActionScript Virtual Machine (AVM) embedded in AIR makes this move possible, because it functions similar to the Java virtual machine (JVM). When users have the AVM, they can then run applications that have been compiled with the amxmlc compiler. AIR applications are installed like any other desktop application—through an installer. This installer even checks to see if the user has the runtime installed and, if not, prompts the user to install it.

In making this move to the desktop, AIR applications are granted privileges that are not available to their Web-based counterparts. One such privilege is access to the local file system. This article examines the AIR File application programming interface (API), including some of the special directories defined in the API as well as the pre-built user interface (UI) components available in Adobe Flex Builder for working with the file system. Finally, you’ll learn how to build a simple application that uses the File API to browse for and display an image file from your local hard disk.

Flex Builder makes it particularly easy to work with AIR, as it includes a wizard for making AIR projects and includes some nice UI components for working with the file system. As such, you will be using Flex Builder as the integrated development environment (IDE) for building the sample application. If you do not have Flex Builder, you can download a trial version that includes everything you need to build AIR applications.

The AIR File API

Before I begin, let me note that this article doesn’t cover the complete documentation for the AIR File API but rather highlights some of the capabilities that it affords you. The File object is located in the flash.filesystem package. The object can be conceptualized as a representation of a file or a directory—existing files or directories or those that have yet to be created. Before I get into some simple examples of how you can use the File object, however, I want to take a moment to discuss some special directories that the File class defines.

Special Directories

AIR is designed to be a cross-platform tool. As anyone who has worked on more than one operating system knows, file system structures vary greatly from system to system. Fortunately, the AVM for the particular system you’re running on takes care of handling these differences for you by defining a number of static properties in the File class that can be used to reference common directories:

• File.applicationStorageDirectory: This directory is uniquely dedicated for each application for file storage. The application storage directory location is based on the user name, the application ID, and the publisher ID.
  • In Mac OS X, the directory resides in /Users/user_name/Library/Preferences/applicationID.publisherID/Local Store/ (for example, /Users/someUser/Library/Preferences/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1/Local Store).
  • In Windows, the directory resides in user_name\Application Data\applicationID.publisherID\Local Store\ (for example, C:\Documents and Settings\someUser\Application Data\com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Local Store).
• File.applicationDirectory: This directory refers to the file path in which the application and any assets are installed. This is a read-only directory (for example, C:\Program Files\AppName in Windows or /Applications in Mac OS X or wherever the user decided to install the application).
• File.desktopDirectory: This directory contains a reference to the user’s desktop directory.
• File.documentsDirectory: This directory contains a reference to the user’s documents directory.
• File.userDirectory: This directory contains a reference to the user directory.

By using these static references, you can write your code so that you don’t have to worry about what system it will be running on.

Creating File References

There are two main methods of creating a reference to a file or directory. The first is to pass in the file path to the File class’s constructor:

new File("C:\Documents and Settings\someUser\My Documents\someFile.txt")

However, when using this method, your code becomes platform specific. The preferred method of creating a file reference is to use one of the aforementioned static directory references, then use the resolvePath method:

var someFile:File = File.applicationStorageDirectory;
 someFile = someFile.resolvePath("someFileName.txt");
 

The result of the above code is that the variable someFile now points to the someFileName.txt file located in the application storage directory. When you have this reference, you can access any of the following properties of the File object. (There are other properties: These are just examples of the more commonly used options. See the API reference for the full list.)

• creationDate: The date the file was created
• creator: The Macintosh creator type of the file (pre–Mac OS X operating systems)
• data: A ByteArray object representing the data of the loaded file after calling the load method
• exists: A Boolean value indicating whether the file exists on the hard disk
• extension: The file extension name
• isDirectory: A Boolean value indicating whether the referenced file is a directory
• isHidden: A Boolean value indicating whether the referenced file is hidden
• isPackage: A Boolean value indicating whether the referenced directory is a package
• isSymbolicLink: A Boolean value indicating whether the referenced file is a symbolic link
• modificationDate: The date on which the file was last modified
• name: The name of the file on the local disk
• nativePath: The full path name of the file
• parent: The directory that contains the referenced file
• size: The file size in bytes
• type: The file type

Some of these properties may seem a bit odd at first, because you pass the file name to the resolvePath method. However, consider the case where you are pointing to a directory, then need to iterate through the files that it contains to find specific information for each file.

Browsing for Files

A common task for many desktop applications is allowing the user to browse the local file system for a particular file. The File class has several methods for just this purpose:

• browseForDirectory(title:String):void: Displays a directory chooser dialog box in which the user can select a directory
• browseForOpen(title:String, typeFilter:Array = null):void: Displays the Open File dialog box, in which the user can select a file to open
• browseForOpenMultiple(title:String, typeFilter:Array = null):void: Displays the Open File dialog box, in which the user can select one or more files to open
• browseForSave(title:String):void: Displays the Save File dialog box, in which the user can select a file destination