This excerpt is the first part of Chapter 8 of the upcoming (March 17, 2008) book titled Beginning AIR: Building Applications for the Adobe Integrated Runtime ISBN: 0470229047. Beginning AIR is written in a walk through style where the examples are built upon throughout each section of the book. The easiest way to learn how to use the API's covered is to create the examples and follow along as they are built upon.
This excerpt covers how to create, move, copy, delete, and list the contents of directories on the operating system's file system. Part 2 will show how to use the File class to create, move, copy, and delete files. It will also demonstrate the usage of the FileStream class for working with the contents of individual files.
Accessing the File System
This chapter will cover an AIR application's file system access. The features covered include creating directories, moving directories, copying directories, deleting a directory, listing directory contents, creating files, writing and updating file contents, moving files, copying files, deleting files, and temporary files and directories.
File System Security
AIR applications enjoy all the privileges of traditional desktop applications, which means that you must work with extreme caution when accessing the local file system. There are no restrictions built in to prevent an AIR application from moving or deleting a resource on the file system. This type of access is a privilege but can also be a double-edged sword, since giving control to an application to have full file system access can be useful but also dangerous.
Working with the File System
AIR has made it easy to work with the local file system of the client machine. Once an application is installed and has the required permissions, then creating, updating, moving, and deleting files or directories is done through an API. This is an important fact since, because the commands are issued through an API, the AIR runtime ensures that the file system change requests will work on whatever operating system/version the application is installed on.
Directories
The following examples demonstrate how to use the File API to make changes to the file system. These examples use the flash.filesystem.File class for interactions with the file system. The next group of samples will work with the same project and build on it with each new piece of functionality. To get started, create a new AIR project and name it Chapter8_Dir. You should now have an empty file named Chapter8_Dir.mxml that looks like Listing 8-1. Please note that the completed source code for Chapter8_Dir.mxml is available in Listing 8-3.
Listing 8-1: Empty Chapter8_Dir.mxml file used for the next set of examples.
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
layout="absolute">
</mx:WindowedApplication>
Creating a Directory
The first set of functionality that we will explore will be the creation of a new directory. To create a new directory, you must first add an
If you have followed along correctly, your Chapter8_Dir.mxml should now look like Listing 8-2.
Listing 8-2: The updated Chapter8_Dir.mxml file.
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
layout="absolute">
<mx:Script>
<![CDATA[
import mx.controls.Alert;
import flash.filesystem.File;
private function createDirectory():void{
var newDirectory:File =
File.desktopDirectory.resolvePath("MyNewDirectory");
newDirectory.createDirectory();
Alert.show(newDirectory.nativePath);
}
]]>
</mx:Script>
<mx:Button label="Create New Directory"
click="createDirectory()" y="10" horizontalCenter="0"/>
</mx:WindowedApplication>
You may have noticed that the File class had a built-in property named desktopDirectory that gave a reference to the desktop of the user’s machine. This is a convenient shortcut that AIR has provided to make it easy to navigate to the user’s desktop without even knowing what operating system is being used. AIR provides four other shortcut properties. Try any of the following in place of desktopDirectory and see what kind of results you get:
- applicationResourceDirectory is a reference to the application install path /Contents/Resources directory. For example, using applicationResourceDirectory to create the directory in this example will create the MyNewDirectory folder at /Users/rich/Applications/Chapter8File-API.app/Contents/Resources/MyNewDirectory on Mac or C:\Documents and Settings\rich\Local Settings\Application Data\Chapter8-FileAPI\MyNewDirectory on Windows.
- applicationStorageDirectory is a reference to the default storage location for the application. For example, on a Mac it will create the directory at /Users/rich/Library/Preferences/Chapter8-FileAPI/Local Store/MyNewDirectory, while on Windows it will create the folder at C:\Documents and Settings\rich\Application Data\Chapter8-FileAPI\Local Store\MyNewDirectory.
- desktopDirectory is a reference to the users desktop directory. For example, on a Mac it will create the directory at /Users/rich/Desktop/MyNewDirectory, while on Windows it will create the directory at C:\Documents and Settings\rich\Desktop\MyNewDirectory.
- documentsDirectory is a reference to the users documents directory. For example, on a Mac it will create the directory at /Users/rich/Documents/MyNewDirectory, while on Windows it will create the directory at C:\Documents and Settings\rich\My Documents\MyNewDirectory.
- userDirectory is a reference to the user directory. For example, on a Mac it will create the directory at /Users/rich/MyNewDirectory, while on Windows it will create the directory at C:\Documents and Settings\rich\MyNewDirectory.
Moving a Directory
To demonstrate how to move a directory, we will need to add a new function to the test application. Moving a directory is made easy using the moveTo method of the File class. To test this, add the following new function to the script block of the Chapter8_Dir.mxml file:
private function moveDirectory():void{
var originalLoc:File = File.desktopDirectory.resolvePath("MyNewDirectory");
var newLoc:File = File.desktopDirectory.resolvePath("MovedDirectory");
originalLoc.moveTo(newLoc);
}
Now add another button to the file below the original button.
<mx:Button label="Move Directory"
click="moveDirectory()" y="40" horizontalCenter="0"/>
When you test the updated application, be sure to create the directory first before attempting to move it or you will wind up with an error. (Error #3003: File or directory does not exist.)
Copy a Directory
To demonstrate how to copy a directory, we will need to add a new function to the test application. To copy a directory, we will use the copyTo method of the File class. To demonstrate this, add the following new function to the script block of the Chapter8_Dir.mxml file:
private function copyDirectory():void{
var originalLoc:File = File.desktopDirectory.resolvePath("MyNewDirectory");
var copyLoc:File = File.desktopDirectory.resolvePath("MyNewDirectory copy");
originalLoc.copyTo(copyLoc);
}
Now add another button to the file below the original button.
<mx:Button label="Copy Directory"
click="copyDirectory()" y="70" horizontalCenter="0"/>
When you test the updated application, be sure to create the directory first before attempting to copy it or you will wind up with an error. (Error #3003: File or directory does not exist.)
Delete a Directory
To demonstrate how to delete a directory, we will need to add a new function to the test application. The File class has a deleteDirectory method that makes it easy to delete a folder. The following new function added to the script block of the Chapter8_Dir.mxml file will demonstrate how to delete a directory:
private function deleteDirectory():void{
var newDirectory:File=File.desktopDirectory.resolvePath("MyNewDirectory");
newDirectory.deleteDirectory();
}
Now add another button to the file below the original button.
<mx:Button label="Delete Directory"
click="deleteDirectory()" y="100" horizontalCenter="0"/>
When you test the updated application, be sure to create the directory first before attempting to move it to the trash or you will wind up with an error. (Error: Error #3003: File or directory does not exist.)
The deleteDirectory method within the File class takes an optional argument of type Boolean. This argument will determine whether a directory that is not empty will be deleted or throw the same error, Error #3003: File or directory does not exist. To test this, run the application and click the Create Directory button, then without closing the application go to your desktop and add something to the "MyNewDirectory." Now go back to the application and click the Delete Directory button, and you will get a runtime Error #3003: File or directory does not exist.
Close the application and update the source code to say newDirectory.deleteDirectory(true);. Run through the steps again (create directory, add something to it, and then attempt delete), and you will see that this time it was deleted successfully.
Move a Directory to Trash
A safer way to handle file deletes would be to move them to the trash instead of deleting them permanently. To demonstrate how to move a directory to the trash, we will need to add a new function to the test application. Add the following new function to the script block of the Chapter8_Dir.mxml file:
private function moveDirToTrash():void{
var newDirectory:File=File.desktopDirectory.resolvePath("MyNewDirectory");
newDirectory.moveToTrash();
}
Now add another button to the file below the original button.
<mx:Button label="Move Dir to Trash"
click="moveDirToTrash()" y="130" horizontalCenter="0"/>
When you test the updated application, be sure to create the directory first before attempting to move it to the trash or you will wind up with an error. (Error #3003: File or directory does not exist.)
List Directory Contents
To list a directory’s contents, you can use the getDirectoryListing() method of the File class to set the directory’s contents into an Array, which you can then loop through to output the contents of the directory. Here is an example:
private function listDirectory():void{
var newDirectory:File=File.desktopDirectory.resolvePath("MyNewDirectory");
var dirContents:Array = newDirectory.getDirectoryListing();
for(var i:int=0; i<dirContents.length; i++){
log.text += dirContents[i].name + " " + dirContents[i].size + " bytes\n";
}
}
<mx:Button label="List Directory"
click="listDirectory()" y="160" horizontalCenter="0"/>
<mx:TextArea id="log" y="190" horizontalCenter="0"
height="125" width="400"/>
To test this example, open the application and click the Create Directory button. Now go to your desktop and add some files to the directory. Go back to the application and click the List Directory button, and you should see something like what is shown in Figure 8-1.
Many other properties are available in addition to the name and size properties that are shown in the example above. Here is the complete list:
- creationDate
- creator
- exists
- icon
- isDirectory
- modificationDate
- name
- nativePath
- parent
- size
- type
Figure 8-1: Contents of a directory after calling listDirectory().
Listing 8-3: The completed Chapter8_Dir.mxml file.
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
layout="absolute">
<mx:Script>
<![CDATA[
import mx.controls.Alert;
import flash.filesystem.File;
/*
Create a new directory
*/
private function createDirectory():void{
var newDirectory:File =
File.desktopDirectory.resolvePath("MyNewDirectory");
newDirectory.createDirectory();
Alert.show(newDirectory.nativePath);
}
/*
Move a directory
NOTE: Be sure to create the "MyNewDirectory"
first before attempting to move
*/
private function moveDirectory():void{
var originalLoc:File =
File.desktopDirectory.resolvePath("MyNewDirectory");
var newLoc:File = File.desktopDirectory.resolvePath("MovedDirectory");
originalLoc.moveTo(newLoc);
}
/*
Copy a directory
NOTE: Be sure to create the "MyNewDirectory"
first before attempting to copy
*/
private function copyDirectory():void{
var originalLoc:File = File.desktopDirectory.resolvePath("MyNewDirectory");
var copyLoc:File = File.desktopDirectory.resolvePath("MyNewDirectory copy");
originalLoc.copyTo(copyLoc);
}
/*
Delete a directory
NOTE: Be sure to create the "MyNewDirectory"
first before attempting to delete it
*/
private function deleteDirectory():void{
var newDirectory:File =
File.desktopDirectory.resolvePath("MyNewDirectory");
newDirectory.deleteDirectory();
}
/*
Move a directory to Trash
NOTE: Be sure to create the "MyNewDirectory"
first before attempting to move it to Trash
*/
private function moveDirToTrash():void{
var newDirectory:File =
File.desktopDirectory.resolvePath("MyNewDirectory");
newDirectory.moveToTrash();
}
/*
List a directory
*/
private function listDirectory():void{
var newDirectory:File =
File.desktopDirectory.resolvePath("MyNewDirectory");
var dirContents:Array = newDirectory.getDirectoryListing();
for(var i:int=0; i<dirContents.length; i++){
log.text += dirContents[i].name + " " + dirContents[i].size +
"bytes\n";
}
}
]]>
</mx:Script>
<mx:Button label="Create Directory"
click="createDirectory()" y="10" horizontalCenter="0"/>
<mx:Button label="Move Directory"
click="moveDirectory()" y="40" horizontalCenter="0"/>
<mx:Button label="Copy Directory"
click="copyDirectory()" y="70" horizontalCenter="0"/>
<mx:Button label="Delete Directory"
click="deleteDirectory()" y="100" horizontalCenter="0"/>
<mx:Button label="Move Dir to Trash"
click="moveDirToTrash()" y="130" horizontalCenter="0"/>
<mx:Button label="List Directory"
click="listDirectory()" y="160" horizontalCenter="0"/>
<mx:TextArea id="log" y="190" horizontalCenter="0"
height="125" width="400"/>
</mx:WindowedApplication>