The folder containing the application's installed files.

The url property for this object uses the app URL scheme (not the file URL scheme). This means that the url string is specified starting with "app:" (not file:). Also, if you create a File object relative to the applicationDirectory directory (using the resolvePath() method), the url of the File object also uses the app URL scheme.

Note: You cannot write to files or directories that have paths that use the app URL scheme. Nor can you delete or create files or folders that have paths that use the app URL scheme. Modifying content in the application directory is a bad practice, for security reasons. If you want to store application-specific data, consider using the application storage directory (File.applicationStorageDirectory). If you want any of that content (in the application storage directory) to have access to the application-priveleged functionality (AIR APIs), you can expose that functionality using a sandbox bridge.

See also

The application's private storage directory. Each AIR application has a unique, persistent application storage directory, which is created when you first access applicationStorageDirectory. This directory is a convenient location to store application-specific data.

The url property for this object uses the app-storage URL scheme (not the file URL scheme). This means that the url string is specified starting with "app-storage:" (not file:). Also, if you create a File object relative to the applicationStoreDirectory directory (using the resolvePath() method), the url of the File object also uses the app-storage URL scheme (as in the example).

var tempFiles = air.File.applicationStorageDirectory;
tempFiles = tempFiles.resolvePath("images/");
air.trace(tempFiles.url); // app-storage:/images

The user's desktop directory.

var desktop = air.File.desktopDirectory;

var files = desktop.getDirectoryListing()

for (i = 0; i < files.length; i++) {
    air.trace(files[i].nativePath)
}

The user's documents directory.

On Windows, this is the "My Documents" directory (for example, C:\Documents and Settings\userName\My Documents). On Mac OS, it is /Users/userName/Documents.

var directory = air.File.documentsDirectory;
directory = directory.resolvePath("AIR Test");

air.File.createDirectory(directory);
air.trace(directory.exists); // true

Whether the referenced file or directory exists. The value is true if the File object points to an existing file or directory; and false otherwise.

var temp = air.File.createTempFile();
air.trace(temp.exists) // true
temp.deleteFile();
air.trace(temp.exists) // false

An Icon object containing to the icons defined for the file. An Icon object is an array of BitmapData objects corresponding to the various icon states.

var directory = air.File.documentsDirectory;
var bitmaps = file.icon.bitmaps;
var bmpData = new BitmapData(1, 1);
for (i = 0; i < bitmaps.length; i++) {
    if (bitmaps[i].height > bmpData.height) {
        bmpData = file.icon.bitmaps[i];
    }
}
var iconBmp = new Bitmap(bmpData);

Whether the reference is to a directory. The value is true if the File object points to a directory; false otherwise.

var userDirFiles = air.File.userDirectory.getDirectoryListing();
for (i = 0; i < userDirFiles.length; i++) {
    if (userDirFiles[i].isDirectory) {
        air.trace(userDirFiles[i].nativePath);
    }
}    

Whether the referenced file or directory is "hidden." The value is true if the referenced file or directory is hidden; and false otherwise.

var userDirFiles = air.File.userDirectory.getDirectoryListing();
for (i = 0; i < userDirFiles.length; i++) {
    if (userDirFiles[i].isHidden) {
        air.trace(userDirFiles[i].nativePath);
    }
}    

Whether the referenced directory is a package. The value is true if the referenced directory is a package; and false otherwise. Note that the File class does not allow creating packages directly.

• On Mac OS, directories can be designated as packages and will show up in the Finder as a single file rather than as a directory. This function will return true if the referenced directory is a package, and false if the file is not a directory, does not exists, or is not a package.
• On other operating systems, this function always returns false.

Whether the reference is a symbolic link. The value is true if the File object is a symbolic link; false otherwise. Note that the File class does not allow creating symbolic links directly.

Symbolic links allow a file to point to another file or directory on disk. Although similar, symbolic links are not the same as aliases on Mac OS and shortcuts on Windows. An alias or a shortcut is always reported as a file (rather than a directory), and reading or writing to an alias or shortcut never affects the original file or directory that it points to. On the other hand, a symbolic link behaves exactly like the file or directory it points to. It can be reported as a file or a directory, and reading or writing to a symbolic link affects the file or directory that it points to, not the symbolic link itself.

The line-ending character sequence used by the host operating system.

On Mac OS, this is the line-feed character (character code 0x0A hexadecimal). On Windows, this is the carriage return character (character code 0x0D hexadecimal) followed by the line-feed character (character code 0x0A hexadecimal).

var str = "Hello\n" + 
        "World\n";
str = str.replace(/\n/g, air.File.lineEnding);
var file = air.File.documentsDirectory.resolvePath("AIR Test/test.txt");
var fileStream = new air.FileStream();
fileStream.open(file, air.FileMode.WRITE);
fileStream.writeUTF(str);
fileStream.close();

The full path in the host operating system representation. On Mac OS, the forward slash (/) character is used as the path separator. However, in Windows, you can set the nativePath property using the forward slash (/) character or the backslash (\) character as the path separator, and AIR automatically replaces forward slashes with the appropriate backslash (\) character.

var docs = air.File.documentsDirectory;
air.trace(docs.nativePath); // C:\Documents and Settings\turing\My Documents
air.trace(docs.url); // file:///C:/Documents%20and%20Settings/turing/My%20Documents

The directory that contains the file or directory referenced by this File object. If the file or directory does not exist, the parent property still returns the File object pointing to the containing directory (even if that directory does not exist).

This property is identical to the return value for resolvePath("..") except that the parent of a root directory is null.

var tempFile = air.File.createTempDirectory();
air.trace(tempFile.parent.nativePath);
tempFile.deleteFile();

The host operating system's path component separator character.

On Mac OS, this is the forward slash (/) character. On Windows, it is the backslash (\ character.

Note: When using the backslash character in a String literal, remember to type the character twice (as in "directory\\file.ext"). Each pair of backslashes in a String literal represent a single backslash in the String.

var directory = air.File.documentsDirectory.resolvePath("Apollo Test");
var file = air.File.documentsDirectory.resolvePath("Apollo Test/employees/bob/test.txt");

var relativePath = directory.getRelativePath(file); // employees/bob/test.txt
relativePath = relativePath.replace(/\//g, air.File.separator);
air.trace(relativePath); 

The default encoding used by the host operating system. Possible values include "windows-1252" "shift-jis", "cn-gb", "iso-8859-1", and others. For a complete list, see Supported Character Sets.

You may use this value when using the readMultiByte() and writeMultiByte() methods of the FileStream class.

See also

var file = air.File.documentsDirectory.resolvePath("AIR Test/test.txt");
var fileStream = new air.FileStream();
fileStream.open(file, air.FileMode.READ);
var str = fileStream.readMultiByte(file.size, air.File.systemCharset);
air.trace(str);    

The URL for this File path.

If this is a reference to the persistent store, the URL scheme is "app-storage", otherwise the scheme is "file".

You can use blank space characters (rather than "%20") when assigning a value to the url property, and AIR automatically encodes the strings (for instance, converting spaces to "%20").

See also

var docs = air.File.documentsDirectory;
air.trace(docs.nativePath); // C:\Documents and Settings\turing\My Documents
air.trace(docs.url); // file:///C:/Documents%20and%20Settings/turing/My%20Documents

The user's directory.

On Windows, this is the parent of the "My Documents" directory (for example, C:\Documents and Settings\userName). On Mac OS it is /Users/userName.

var files = air.File.userDirectory.getDirectoryListing();
for (i = 0; i < files.length; i++) {
    air.trace(files[i].nativePath);
}

The constructor function for the File class. If you pass a path argument, the File object points to the specified path, and the nativePath property and and url property are set to reflect that path.

See also

Displays a directory chooser dialog box, which lets the user select a directory. When the user selects the directory, the select event is dispatched. The target property of the select event is the File object pointing to the selected directory.

Parameters

See also

var directory = air.File.documentsDirectory;

try
{
    directory.browseForDirectory("Select Directory");
    directory.addEventListener(air.Event.SELECT, directorySelected);
}
catch (error)
{
    air.trace("Failed:", error.message)
}

function directorySelected(event) 
{
    directory = event.target ;
    var files = directory.getDirectoryListing();
    for(var i = 0; i < files.length; i++)
    {
        air.trace(files[i].name);
    }
}

Displays an Open File dialog box, which lets the user select a file to open. When the user selects the file, the select event is dispatched. The target property of the select event is the File object pointing to the selected file.

Parameters

See also

var fileToOpen = new air.File();
var txtFilter = new air.FileFilter("Text", "*.as;*.css;*.html;*.txt;*.xml");

try 
{
    fileToOpen.browseForOpen("Open", [txtFilter]);
    fileToOpen.addEventListener(air.Event.SELECT, fileSelected);
}
catch (error)
{
    air.trace("Failed:", error.message)
}

function fileSelected(event) 
{
    var stream = new air.FileStream();
    stream.open(event.target, air.FileMode.READ);
    var fileData = stream.readUTFBytes(stream.bytesAvailable);
    air.trace(fileData);
}

Displays an Open File dialog box, which lets the user select one or more files to open. When the user selects the files, the selectMultiple event is dispatched. The target property of the select event is this File object. Unlike browseForOpen(), this File object is not updated to reference any of the chosen files. Instead, the resulting FileListEvent contains an array of the chosen Files.

Parameters

See also

var docsDir = air.File.documentsDirectory;
try
{
    docsDir.browseForOpenMultiple("Select Files");
    docsDir.addEventListener(air.FileListEvent.SELECT_MULTIPLE, filesSelected);
}
catch (error)
{
    air.trace("Failed:", error.message)
}

function filesSelected(event) 
{
    for (i = 0; i < event.files.length; i++) 
    {
        air.trace(event.files[i].nativePath);
    }
}

Displays a Save File dialog box, which lets the user select a file desitination. When the user selects the file, the select event is dispatched. The target property of the select event is the File object pointing to the selected Save destination.

Parameters

See also

var docsDir = air.File.documentsDirectory;
try
{
    docsDir.browseForSave("Save As");
    docsDir.addEventListener(air.Event.SELECT, saveData);
}
catch (error)
{
    air.trace("Failed:", error.message)
}

function saveData(event) 
{
    var newFile = event.target ;
    var str = "Hello.";
    if (!newFile.exists)
    {
        var stream = new air.FileStream();
        stream.open(newFile, air.FileMode.WRITE);
        stream.writeUTFBytes(str);
        stream.close();
    }
}

Cancels any pending asynchronous operation.

Canonicalizes the File path.

If the File object represents an existing file or directory, canonicalization adjusts the path so that it matches the case of the actual file or directory name. If the File object is a symbolic link, canonicalization adjusts the path so that it matches the file or directory that the link points to, regardless of whether the file or directory that is pointed to exists.

In addition, canonicalization converts short files names to long file names on Windows.

var path = air.File.desktopDirectory.resolvePath("air test");
air.trace(path.nativePath); 
path.canonicalize();
air.trace(path.nativePath); // ...\AIR Test

var path = new air.File();
path.nativePath = "C:\\AIR~1";
path.canonicalize();
air.trace(path.nativePath); // C:\AIR Test

Returns a copy of this File object. Event registrations are not copied.

Note: This method does not copy the file itself. It simply makes a copy of the instance of the JavaScript File object. To copy a file, use the copyTo() method.

Copies the file or directory at the location specified by this File object to the location specified by newLocation parameter.

Parameters

See also

var sourceFile = air.File.documentsDirectory;
sourceFile = sourceFile.resolvePath("AIR Test/test1.txt");
var destination = air.File.documentsDirectory;
destination = destination.resolvePath("AIR Test/test2.txt");

if (sourceFile.copyTo(destination, true)) {
    air.trace("Done.")
}

var sourceFile = air.File.documentsDirectory;
sourceFile = sourceFile.resolvePath("AIR Test/test1.txt");
var destination = air.File.documentsDirectory;
destination = destination.resolvePath("AIR Test/test2.txt");

try 
{
    if (sourceFile.copyTo(destination, true)) {
}
catch (error)
{
    air.trace("Error:" error.message)
}

Begins copying the file or directory at the location specified by this File object to the location specified by the destination parameter. Upon completion, either a complete event (successful) or an ioError event (unsucessful) is dispatched.

Parameters

See also

var sourceFile = air.File.documentsDirectory;
sourceFile = sourceFile.resolvePath("AIR Test/test1.txt");
var destination = air.File.documentsDirectory;
destination = destination.resolvePath("AIR Test/test2.txt");

var sourceFile.copyToAsync(destination, true);
sourceFile.addEventListener(air.Event.COMPLETE, fileCopiedHandler);

function fileCopiedHandler(event): void {
    air.trace("Done.")
}

Creates the specified directory and any necessary parent directories. If the directory already exists, no action is taken.

var source = air.File.desktopDirectory.resolvePath("test.txt");
var target = air.File.documentsDirectory.resolvePath("AIR Test/test.txt");
var targetParent = target.parent;
targetParent.createDirectory();
source.moveTo(target, true);

Returns a reference to a new temporary directory. This is a new directory in the system's temporary directory path.

This method lets you identify a new, unique directory, without having to query the system to see that the directory is new and unique.

You may want to delete the temporary directory before closing the application, since it is not deleted automatically.

See also

var temp = air.File.createTempDirectory();
air.trace(temp.nativePath);

Returns a reference to a new temporary file. This is a new file in the system's temporary directory path.

This method lets you identify a new, unique file, without having to query the system to see that the file is new and unique.

You may want to delete the temporary file before closing the application, since it is not deleted automatically.

See also

var temp = air.File.createTempFile();
air.trace(temp.nativePath);

Deletes the directory.

Parameters

See also

var directory = air.File.documentsDirectory.resolvePath("Empty Junk Directory/");
air.File.createDirectory(directory);
air.trace(directory.exists); // true
directory.deleteDirectory();
air.trace(directory.exists); // false

Deletes the directory asynchronously.

Parameters

See also

Deletes the file.

See also

var file = air.File.createTempFile();
air.trace(file.exists); // true
file.deleteFile();
air.trace(file.exists); // false

Deletes the file asynchronously.

See also

Returns an array of File objects corresponding to files and directories in the directory represented by this File object. This method does not explore the contents of subdirectories.

See also

var directory = air.File.userDirectory;
var list = directory.getDirectoryListing();
for (i = 0; i < list.length; i++) {
    air.trace(list[i].nativePath);
}

Asynchronously retrieves an array of File objects corresponding to the contents of the directory represented by this File object.

See also

var directory = air.File.userDirectory;
directory.getDirectoryListingAsync();
directory.addEventListener(air.FileListEvent.DIRECTORY_LISTING, directoryListingHandler);

function directoryListingHandler(event) {
    var list = event.files;
    for (i = 0; i < list.length; i++) {
        air.trace(list[i].nativePath);
    }
}

Finds relative path between two File paths.

The relative path is the list of components which may be appended to (resolved against) this reference in order to locate the second (parameter) reference. The relative path is returned using the "/" separator character.

Optionally, relative paths may include ".." references, but such a paths will not cross conspicuous volume boundaries.

Parameters

Returns an array of file system root directories.

var rootDirs = air.File.getRootDirectories();

for (i = 0; i < rootDirs.length; i++) {
    air.trace(rootDirs[i].nativePath)
}

Moves the file or directory at the location specified by this File object to the location specified by the destination parameter.

To rename a file, set the destination parameter to point to a path that is in the file's directory, but with a different filename.

Parameters

See also

var sourceFile = air.File.documentsDirectory;
sourceFile = sourceFile.resolvePath("AIR Test/test1.txt");
var destination = air.File.documentsDirectory;
destination = destination.resolvePath("AIR Test/test2.txt");

try  
{
    sourceFile.moveTo(destination, true);
}
catch (error)
{
    air.trace("Error:" error.message);
}

var sourceFile = air.File.documentsDirectory;
sourceFile = sourceFile.resolvePath("AIR Test/test1.txt");
var destination = air.File.documentsDirectory;
destination = destination.resolvePath("AIR Test/Results/test1.txt");

try 
{
    sourceFile.moveTo(destination, true);
}
catch (error)
{
    air.trace("Error:" error.message);
}

Begins moving the file or directory at the location specified by this File object to the location specified by the newLocation parameter.

To rename a file, set the destination parameter to point to a path that is in the file's directory, but with a different filename

Parameters

See also

var sourceFile = air.File.documentsDirectory;
sourceFile = sourceFile.resolvePath("Apollo Test/test1.txt");
var destination = air.File.documentsDirectory;
destination = destination.resolvePath("Apollo Test/test2.txt");

var sourceFile.moveToAsync(destination, true);
sourceFile.addEventListener(air.Event.COMPLETE, fileMoveCompleteHandler);

function fileMoveCompleteHandler(event): void 
{
    air.trace("Done.")
}

Moves a file or directory to the trash.

See also

Asynchronously moves a file or directory to the Trash.

See also

Creates a new File object with a path relative to this File object's path, based on the path parameter (a String).

If the given path is an absolute file reference, then that path is used, otherwise the path is interpreted relative to this File object as follows.

The given path is "appended" to this path (however, use of ".." in the path can return a resulting path that is not a child of the File object). The resulting reference need not refer to an actual file system location. Use the forward slash (/) character as the path separator (not \).

All resulting paths are normalized as follows:

• Any "." element is ignored.
• Any ".." element consumes its parent entry.
• No ".." reference reaching the file system root or the application-persistent storage root will pass that node; it will be ignored.

Parameters

Dispatched when a pending asynchronous operation is canceled.

This event has the following properties:

Dispatched when an asynchronous operation is complete.

This event has the following properties: