Typical browser applications cannot access the local filesystem. However, Adobe AIR applications can, giving those applications a distinct advantage. Learn how the AIR File API works and build an application that can read and write from a local disk. Someday, your browser will do the very same thing.
amxmlc compiler. AIR applications are installed like any other desktop applicationthrough 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 directoryexisting 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.
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
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 (preMac OS X operating systems)
ByteArray object representing the data of the loaded file after calling the
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