Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.filesystem 
File 
Packageflash.filesystem
Classpublic class File
InheritanceFile Inheritance FileReference Inheritance EventDispatcher Inheritance Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

A File object represents a path to a file or directory. This can be an existing file or directory, or it can be one that does not yet exist; for instance, it can represent the path to a file or directory that you plan to create.

The File class has a number of properties and methods for getting information about the file system and for performing operations, such as copying files and directories.

You can use File objects along with the FileStream class to read and write files.

The File class extends the FileReference class. The FileReference class, which is available in Flash® Player as well as Adobe® AIR®, represents a pointer to a file, but the File class adds properties and methods that are not exposed in Flash Player (in a SWF running in a browser), due to security considerations.

The File class includes static properties that let you reference commonly used directory locations. These static properties include:

  • File.applicationStorageDirectory—a storage directory unique to each installed AIR application
  • File.applicationDirectory—the read-only directory where the application is installed (along with any installed assets)
  • File.desktopDirectory—the user's desktop directory
  • File.documentsDirectory—the user's documents directory
  • File.userDirectory—the user directory

These properties have meaningful values on different operating systems. For example, Mac OS, Linux, and Windows each have different native paths to the user's desktop directory. However, the File.desktopDirectory property points to the correct desktop directory path on each of these platforms. To write applications that work well across platforms, use these properties as the basis for referencing other files used by the application. Then use the resolvePath() method to refine the path. For example, this code points to the preferences.xml file in the application storage directory:

 var prefsFile:File = File.applicationStorageDirectory;
  prefsFile = prefsFile.resolvePath("preferences.xml");

If you use a literal native path in referencing a file, it will only work on one platform. For example, the following File object would only work on Windows:

new File("C:\Documents and Settings\joe\My Documents\test.txt")

The application storage directory is particularly useful. It gives an application-specific storage directory for the AIR application. It is defined by the File.applicationStorageDirectory property.

Do not add or remove content from the application directory (where the AIR application is installed). Doing so can break an AIR application and invalidate the application signature. AIR does not let you write to the application directory by default, because the directory is not writable to all user accounts on all operating systems. Use the application storage directory to write internal application files. Use the documents directory to write files that a user expects to use outside your application, such as edited pictures or text files.

See also



Public Properties
 PropertyDefined By
  AIR-only applicationDirectory : File
[static] [read-only] The folder containing the application's installed files.
File
  AIR-only applicationStorageDirectory : File
[static] [read-only] The application's private storage directory.
File
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
 InheritedcreationDate : Date
[read-only] The creation date of the file on the local disk.
FileReference
 Inheritedcreator : String
[read-only] The Macintosh creator type of the file, which is only used in Mac OS versions prior to Mac OS X.
FileReference
 Inheriteddata : ByteArray
[read-only] The ByteArray object representing the data from the loaded file after a successful call to the load() method.
FileReference
  AIR-only desktopDirectory : File
[static] [read-only] The user's desktop directory.
File
  AIR-only documentsDirectory : File
[static] [read-only] The user's documents directory.
File
  AIR-only downloaded : Boolean
Indicates whether the referenced file or directory was downloaded (from the internet) or not.
File
  AIR-only exists : Boolean
[read-only] Indicates whether the referenced file or directory exists.
File
 InheritedAIR-only extension : String
[read-only] The filename extension.
FileReference
  AIR-only icon : Icon
[read-only] An Icon object containing the icons defined for the file.
File
  AIR-only isDirectory : Boolean
[read-only] Indicates whether the reference is to a directory.
File
  AIR-only isHidden : Boolean
[read-only] Indicates whether the referenced file or directory is "hidden." The value is true if the referenced file or directory is hidden, false otherwise.
File
  AIR-only isPackage : Boolean
[read-only] Indicates whether the referenced directory is a package.
File
  AIR-only isSymbolicLink : Boolean
[read-only] Indicates whether the reference is a symbolic link.
File
  AIR-only lineEnding : String
[static] [read-only] The line-ending character sequence used by the host operating system.
File
 InheritedmodificationDate : Date
[read-only] The date that the file on the local disk was last modified.
FileReference
 Inheritedname : String
[read-only] The name of the file on the local disk.
FileReference
  AIR-only nativePath : String
The full path in the host operating system representation.
File
  AIR-only parent : File
[read-only] The directory that contains the file or directory referenced by this File object.
File
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  AIR-only separator : String
[static] [read-only] The host operating system's path component separator character.
File
 Inheritedsize : Number
[read-only] The size of the file on the local disk in bytes.
FileReference
  AIR-only spaceAvailable : Number
[read-only] The space available for use at this File location, in bytes.
File
  AIR-only systemCharset : String
[static] [read-only] The default encoding used by the host operating system.
File
 Inheritedtype : String
[read-only] The file type.
FileReference
  AIR-only url : String
The URL for this file path.
File
  AIR-only userDirectory : File
[static] [read-only] The user's directory.
File
Public Methods
 MethodDefined By
  
AIR-only File(path:String = null)
The constructor function for the File class.
File
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
 Inherited
browse(typeFilter:Array = null):Boolean
Displays a file-browsing dialog box that lets the user select a file to upload.
FileReference
  
Displays a directory chooser dialog box, in which the user can select a directory.
File
  
AIR-only browseForOpen(title:String, typeFilter:Array = null):void
Displays the Open File dialog box, in which the user can select a file to open.
File
  
AIR-only 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.
File
  
Displays the Save File dialog box, in which the user can select a file destination.
File
  
[override] Cancels any pending asynchronous operation.
File
  
Canonicalizes the File path.
File
  
Returns a copy of this File object.
File
  
AIR-only copyTo(newLocation:FileReference, overwrite:Boolean = false):void
Copies the file or directory at the location specified by this File object to the location specified by the newLocation parameter.
File
  
AIR-only copyToAsync(newLocation:FileReference, overwrite:Boolean = false):void
Begins copying the file or directory at the location specified by this File object to the location specified by the destination parameter.
File
  
Creates the specified directory and any necessary parent directories.
File
  
[static] Returns a reference to a new temporary directory.
File
  
[static] Returns a reference to a new temporary file.
File
  
AIR-only deleteDirectory(deleteDirectoryContents:Boolean = false):void
Deletes the directory.
File
  
AIR-only deleteDirectoryAsync(deleteDirectoryContents:Boolean = false):void
Deletes the directory asynchronously.
File
  
Deletes the file.
File
  
Deletes the file asynchronously.
File
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
download(request:URLRequest, defaultFileName:String = null):void
Opens a dialog box that lets the user download a file from a remote server.
FileReference
  
Returns an array of File objects corresponding to files and directories in the directory represented by this File object.
File
  
Asynchronously retrieves an array of File objects corresponding to the contents of the directory represented by this File object.
File
  
AIR-only getRelativePath(ref:FileReference, useDotDot:Boolean = false):String
Finds the relative path between two File paths.
File
  
[static] Returns an array of File objects, listing the file system root directories.
File
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Starts the load of a local file selected by a user.
FileReference
  
AIR-only moveTo(newLocation:FileReference, overwrite:Boolean = false):void
Moves the file or directory at the location specified by this File object to the location specified by the destination parameter.
File
  
AIR-only moveToAsync(newLocation:FileReference, overwrite:Boolean = false):void
Begins moving the file or directory at the location specified by this File object to the location specified by the newLocation parameter.
File
  
Moves a file or directory to the trash.
File
  
Asynchronously moves a file or directory to the trash.
File
  
Opens the file in the application registered by the operating system to open this file type.
File
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
Creates a new File object with a path relative to this File object's path, based on the path parameter (a string).
File
 Inherited
save(data:*, defaultFileName:String = null):void
Opens a dialog box that lets the user save a file to the local filesystem.
FileReference
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
upload(request:URLRequest, uploadDataFieldName:String = "Filedata", testUpload:Boolean = false):void
Starts the upload of the file to a remote server.
FileReference
 Inherited
Initiate uploading a file to a URL without any encoding.
FileReference
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
  Dispatched when a pending asynchronous operation is canceled.File
  Dispatched when an asynchronous operation is complete.File
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
  Dispatched when a directory list is available as a result of a call to the getDirectoryListingAsync() method.File
 InheritedDispatched if a call to the upload() or uploadUnencoded() method attempts to access data over HTTP and Adobe AIR is able to detect and return the status code for the request.FileReference
 InheritedDispatched when an upload fails and an HTTP status code is available to describe the failure.FileReference
  Dispatched when an error occurs during an asynchronous file operation.File
 InheritedDispatched when an upload or download operation starts.FileReference
 InheritedDispatched periodically during the file upload or download operation.FileReference
  Dispatched when an operation violates a security constraint.File
  Dispatched when the user selects a file or directory from a file- or directory-browsing dialog box.File
  Dispatched when the user selects files from the dialog box opened by a call to the browseForOpenMultiple() method.File
 InheritedDispatched after data is received from the server after a successful upload.FileReference
Property Detail
AIR-only 

applicationDirectory

property
applicationDirectory:File  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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 File.applicationDirectory directory (by using the resolvePath() method), the url property 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. Also, you cannot 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 the content in the application storage directory to have access to the application-priveleged functionality (AIR APIs), you can expose that functionality by using a sandbox bridge.

The applicationDirectory property provides a way to reference the application directory that works across platforms. If you set a File object to reference the application directory using the nativePath or url property, it will only work on the platform for which that path is valid.



Implementation
    public static function get applicationDirectory():File

See also

AIR-only 

applicationStorageDirectory

property 
applicationStorageDirectory:File  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

The application's private storage directory.

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

When you uninstall an AIR application, the uninstaller does not delete files that are stored in the application storage directory.

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 File.applicationStoreDirectory directory (by using the resolvePath() method), the url of the File object also uses the app-storage URL scheme (as in the example).

The applicationStorageDirectory property provides a way to reference the application storage directory that works across platforms. If you set a File object to reference the application storage directory using the nativePath or url property, it will only work on the platform for which that path is valid.



Implementation
    public static function get applicationStorageDirectory():File

Example  ( How to use this example )
The following code creates a File object pointing to the "images" subdirectory of the application storage directory.
import flash.filesystem.File;

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

desktopDirectory

property 
desktopDirectory:File  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

The user's desktop directory.

The desktopDirectory property provides a way to reference the desktop directory that works across platforms. If you set a File object to reference the desktop directory using the nativePath or url property, it will only work on the platform for which that path is valid.



Implementation
    public static function get desktopDirectory():File

Example  ( How to use this example )
The following code outputs a list of files and directories contained in the user's desktop directory.
import flash.filesystem.File;
var desktop:File = File.desktopDirectory;

var files:Array = desktop.getDirectoryListing();

for (var i:uint = 0; i < files.length; i++) {
    trace(files[i].nativePath);
}
AIR-only 

documentsDirectory

property 
documentsDirectory:File  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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, the default location is /Users/userName/Documents. On Linux, the default location is /home/userName/Documents (on an English system), and the property observes the xdg-user-dirs setting.

The documentsDirectory property provides a way to reference the documents directory that works across platforms. If you set a File object to reference the documents directory using the nativePath or url property, it will only work on the platform for which that path is valid.



Implementation
    public static function get documentsDirectory():File

Example  ( How to use this example )
The following code uses the File.documentsDirectory property and the File.createDirectory() method to ensure that a directory named "AIR Test" exists in the user's documents directory.
import flash.filesystem.File;

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

File.createDirectory(directory);
trace(directory.exists); // true
AIR-only 

downloaded

property 
downloaded:Boolean

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Indicates whether the referenced file or directory was downloaded (from the internet) or not.

This property is only meaningful on operating systems in which files can be flagged as downloaded:

  • Windows XP service pack 2 and later, and on Windows Vista
  • Mac OS 10.5 and later

On systems that do not flag downloaded files, such as Linux, the property is not meaningful (and it is set to false).



Implementation
    public function get downloaded():Boolean
    public function set downloaded(value:Boolean):void

See also

AIR-only 

exists

property 
exists:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Indicates whether the referenced file or directory exists. The value is true if the File object points to an existing file or directory, false otherwise.



Implementation
    public function get exists():Boolean

Example  ( How to use this example )
The following code creates a temporary file, then deletes it and uses the File.exists property to check for the existence of the file.
import flash.filesystem.*;

var temp:File = File.createTempFile();
trace(temp.exists); // true
temp.deleteFile();
trace(temp.exists); // false
AIR-only 

icon

property 
icon:Icon  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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



Implementation
    public function get icon():Icon

Example  ( How to use this example )
The following code shows how to find the image in the icon array that has the greatest height, and it sets a Bitmap object to that image.
import flash.filesystem.File;
import flash.display.*;

var directory:File = File.documentsDirectory;
var bitmaps:Array = directory.icon.bitmaps;
var bmpData:BitmapData = new BitmapData(1, 1);
for (var i:uint = 0; i < bitmaps.length; i++) {
    if (bitmaps[i].height > bmpData.height) {
        bmpData = directory.icon.bitmaps[i];
    }
}
var iconBmp:Bitmap = new Bitmap(bmpData);
You might add this Bitmap object as a child of a display object container, such as a Sprite object or a Flex UIComponent object.
AIR-only 

isDirectory

property 
isDirectory:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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



Implementation
    public function get isDirectory():Boolean

Example  ( How to use this example )
The following code creates an array of File objects pointing to files and directories in the user directory and then uses the isDirectory property to list only those File objects that point to directories (not to files).
import flash.filesystem.*;

var userDirFiles:Array = File.userDirectory.getDirectoryListing();
for (var i:uint = 0; i < userDirFiles.length; i++) {
    if (userDirFiles[i].isDirectory) {
        trace(userDirFiles[i].nativePath);
    }
}    
AIR-only 

isHidden

property 
isHidden:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Indicates whether the referenced file or directory is "hidden." The value is true if the referenced file or directory is hidden, false otherwise.



Implementation
    public function get isHidden():Boolean

Example  ( How to use this example )
The following code creates an array of File objects pointing to files and directories in the user directory and then uses the isHidden property to list hidden files and directories.
import flash.filesystem.*;

var userDirFiles:Array = File.userDirectory.getDirectoryListing();
for (var i:uint = 0; i < userDirFiles.length; i++) {
    if (userDirFiles[i].isHidden) {
        trace(userDirFiles[i].nativePath);
    }
}    
AIR-only 

isPackage

property 
isPackage:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Indicates whether the referenced directory is a package.

The value is true if the referenced directory is a package, 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 property is set to true if the referenced directory is a package, and false if the file is not a directory, does not exist, or is not a package.
  • On other operating systems, this property is always set to false.



Implementation
    public function get isPackage():Boolean
AIR-only 

isSymbolicLink

property 
isSymbolicLink:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Indicates 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 generally behaves 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. Deleting a symbolic link, however, deletes the link and not the target of the link.

Mac® OS®, Linux, and Windows® Vista® support symbolic links. Additionally, on Windows the isSymbolicLink property for a File object referencing a junction point (used in the NTFS file system) is set to true.



Implementation
    public function get isSymbolicLink():Boolean
AIR-only 

lineEnding

property 
lineEnding:String  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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

On Mac OS and Linux, 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).



Implementation
    public static function get lineEnding():String

Example  ( How to use this example )
The following code writes a string (str) to a text file and uses the File.lineEnding static property to replace all instances of the new-line character (represented in the code by the regular expression /\n/g) with the preferred line-ending character for the host operating system.
import flash.filesystem.*;

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

nativePath

property 
nativePath:String

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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

Before writing code to set the nativePath property directly, consider whether doing so may result in platform-specific code. For example, a native path such as "C:\\Documents and Settings\\bob\\Desktop" is only valid on Windows. It is far better to use the following static properties, which represent commonly used directories, and which are valid on all platforms:

  • File.applicationDirectory
  • File.applicationStorageDirectory
  • File.desktopDirectory
  • File.documentsDirectory
  • File.userDirectory

You can use the resolvePath() method to get a path relative to these directories.

Some Flex APIs, such as the source property of the SWFLoader class, use a URL (the url property of a File object), not a native path (the nativePath property).



Implementation
    public function get nativePath():String
    public function set nativePath(value:String):void

Throws
ArgumentError — The syntax of the path is invalid.
 
SecurityError — The caller is not in the application security sandbox.

Example  ( How to use this example )
The following code shows the difference between the nativePath property and the url property of a File object. The comments show results on an example Windows computer.
import flash.filesystem.File;

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

parent

property 
parent:File  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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 that points 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.



Implementation
    public function get parent():File

Example  ( How to use this example )
The following code uses the parent property to show the directory that contains a temporary file.
import flash.filesystem.File;

var tempFile:File = File.createTempDirectory();
trace(tempFile.parent.nativePath);
tempFile.deleteFile();
AIR-only 

separator

property 
separator:String  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

The host operating system's path component separator character.

On Mac OS and Linux, 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.



Implementation
    public static function get separator():String

Example  ( How to use this example )
The following code uses the getRelativePath() method to get the relative path between a directory and a file. The code then uses the File.separator static property to replace forward slash (/) characters in the path with the separator character used by the operating system, which is the backslash character (\) on Windows and the forward slash character on other operating systems.
import flash.filesystem.File;

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

var relativePath:String = directory.getRelativePath(file); // employees/bob/test.txt
relativePath = relativePath.replace(/\//g, File.separator);
trace(relativePath); 
In this example, the replace() method uses a regular expression, /\//g, to match all forward slash characters.
AIR-only 

spaceAvailable

property 
spaceAvailable:Number  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.1

The space available for use at this File location, in bytes.

If the File object references a directory, spaceAvailable indicates the space in the directory that files can use. If the File object references a file, spaceAvailable indicates the space into which the file could grow. If the file location does not exist, spaceAvailable is set to 0. If the File object references a symbolic link, spaceAvailable indicates the space available at the location the symbolic link points to.

Typically the space available for a directory or file is the same as the space available on the volume containing the directory or file. However, space available can take into account quotas and per-directory limits.

Adding a file or directory to a volume generally requires more space than the actual size of the file or the size of the contents of the directory. For example, the operating system may require more space to store index information. Or the disk sectors required may use additional space. Also, available space changes dynamically. So, you cannot expect to allocate all of the reported space for file storage.



Implementation
    public function get spaceAvailable():Number
AIR-only 

systemCharset

property 
systemCharset:String  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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 can use this value when using the readMultiByte() and writeMultiByte() methods of the FileStream class.



Implementation
    public static function get systemCharset():String

See also


Example  ( How to use this example )
The following code opens a file (a test.txt file in the AIR Test subdirectory of the user's documents directory), and uses the File.systemCharset static property as the charSet parameter of a call to the readMultiByte() method of a FileStream object.
import flash.filesystem.File;

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

url

property 
url:String

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

The URL for this file path.

If this is a reference to a path in the application storage directory, the URL scheme is "app-storage"; if it is a reference to a path in the application directory, the URL scheme is "app"; otherwise the scheme is "file".

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



Implementation
    public function get url():String
    public function set url(value:String):void

Throws
ArgumentError — The URL syntax is invalid.
 
SecurityError — The caller is not in the application security sandbox.

See also


Example  ( How to use this example )
The following code shows the difference between the nativePath property and the url property of a File object. The comments show results on an example Windows computer.
import flash.filesystem.File;

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

userDirectory

property 
userDirectory:File  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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. On Linux, it is /home/userName.

The userDirectory property provides a way to reference the user directory that works across platforms. If you set the nativePath or url property of a File object directly, it will only work on the platform for which that path is valid.



Implementation
    public static function get userDirectory():File

Example  ( How to use this example )
The following code outputs a list of files and directories contained in the root level of the user directory:
import flash.filesystem.File;

var files:Array = File.userDirectory.listDirectory();
for (var i:uint = 0; i < files.length; i++) {
    trace(files[i].nativePath);
}
Constructor Detail
AIR-only 

File

()Constructor
public function File(path:String = null)

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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.

Although you can pass a path argument to specify a file path, consider whether doing so may result in platform-specific code. For example, a native path such as "C:\\Documents and Settings\\bob\\Desktop" or a URL such as "file:///C:/Documents%20and%20Settings/bob/Desktop" is only valid on Windows. It is far better to use the following static properties, which represent commonly used directories, and which are valid on all platforms:

  • File.applicationDirectory
  • File.applicationStorageDirectory
  • File.desktopDirectory
  • File.documentsDirectory
  • File.userDirectory

You can then use the resolvePath() method to get a path relative to these directories. For example, the following code sets up a File object to point to the settings.xml file in the application storage directory:

var file:File = File.applicationStorageDirectory.resolvePath("settings.xml");

Important: If you pass a URL string in the path parameter, the URL is decoded to resolve the file path. For example, the statement, new File("file:///c:/test/demo%20file%201%2e0.txt") creates a File object with the native path, "c:\test\demo file 1.0.txt". (A URL uses the file:, app:, or app-storage: scheme prefixes.) However, if the valid URL prefixes are omitted, the path string is treated like a native path and no decoding takes place. You must take this behavior into consideration when validating paths derived from potentially untrusted sources. If you simply validate the input string, URL decoding may allow an attacker to bypass your validation checks. Always validate the final path of the instantiated File object:

     var file:File = new File( taintedString );
     validate( file.nativePath ); //where validate() is your path validation function
     

Parameters
path:String (default = null) — The path to the file. You can specify the path by using either a URL or native path (platform-specific) notation.

If you specify a URL, you can use any of the following URL schemes: file, app, or app-storage. The following are valid values for the path parameter using URL notation:

  • "app:/DesktopPathTest.xml"
  • "app-storage:/preferences.xml"
  • "file:///C:/Documents%20and%20Settings/bob/Desktop" (the desktop on Bob's Windows computer)
  • "file:///Users/bob/Desktop" (the desktop on Bob's Mac computer)

The app and app-storage URL schemes are useful because they can point to a valid file on all file systems. However, in the other two examples, which use the file URL scheme to point to the user's desktop directory, it would be better to pass no path argument to the File() constructor and then assign File.desktopDirectory to the File object, as a way to access the desktop directory that is both platform- and user-independent.

If you specify a native path, on Windows you can use either the backslash character or the forward slash character as the path separator in this argument; on Mac OS and Linux, use the forward slash. The following are valid values for the path parameter using native path notation:

  • "C:/Documents and Settings/bob/Desktop"
  • "/Users/bob/Desktop"

However, for these two examples, you should pass no path argument to the File() constructor and then assign File.desktopDirectory to the File object, as a way to access the desktop directory that is both platform- and user-independent.


Throws
ArgumentError — The syntax of the path parameter is invalid.

See also

Method Detail

AIR-only browseForDirectory

()method
public function browseForDirectory(title:String):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Displays a directory chooser dialog box, in which the user can 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

title:String — The string that is diplayed in the title bar of the dialog box.


Events
cancel:Event — Dispatched when the user clicks the Cancel button in the Open File dialog box.
 
select:Event — Dispatched when the user selects a directory and closes the directory chooser dialog box.

See also


Example  ( How to use this example )

The following code uses the File.browseForDirectory() method to let the user select a directory. When the directory is selected, the code lists the contents of the selected directory in the trace() output.
import flash.filesystem.File;
import flash.events.Event;

var directory:File = File.documentsDirectory;

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

function directorySelected(event:Event):void 
{
    directory = event.target as File;
    var files:Array = directory.getDirectoryListing();
    for(var i:uint = 0; i < files.length; i++)
    {
        trace(files[i].name);
    }
}

AIR-only browseForOpen

()method 
public function browseForOpen(title:String, typeFilter:Array = null):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Displays the Open File dialog box, in which the user can 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

title:String — The string that is diplayed in the title bar of the dialog box.
 
typeFilter:Array (default = null) — An array of FileFilter instances used to filter the files that are displayed in the dialog box. If you omit this parameter, all files are displayed. For more information, see the FileFilter class.


Events
cancel:Event — Dispatched when the user clicks the Cancel button in the Open File dialog box.
 
select:Event — Dispatched when the user selects a file and closes the Open File dialog box.

See also


Example  ( How to use this example )

The following code uses the File.browseForOpen() method to let the user choose a text file. When the file is selected, the code reads the file data into a string.
import flash.filesystem.*;
import flash.events.Event;
import flash.net.FileFilter;

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

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

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

AIR-only browseForOpenMultiple

()method 
public function browseForOpenMultiple(title:String, typeFilter:Array = null):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Displays the Open File dialog box, in which the user can 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(), with the browseForOpenMultiple() method, this File object is not updated to reference any of the chosen files. Instead, the resulting selectMultiple event contains an array of the chosen files.

Parameters

title:String — The string that is diplayed in the title bar of the dialog box.
 
typeFilter:Array (default = null) — An array of FileFilter instances used to filter the files that are displayed in the dialog box. If you omit this parameter, all files are displayed. For more information, see the FileFilter class.


Events
cancel:Event — Dispatched when the user clicks the Cancel button in the Open File dialog box.
 
selectMultiple:FileListEvent — Dispatched when the user selects files and closes the Open File dialog box.

See also


Example  ( How to use this example )

The following code uses the File.browseForOpenMultiple() method to let the user choose multiple files. When the files are selected, the code outputs the paths for the selected files.
import flash.filesystem.*;
import flash.events.FileListEvent;

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

function filesSelected(event:FileListEvent):void 
{
    for (var i:uint = 0; i < event.files.length; i++) 
    {
        trace(event.files[i].nativePath);
    }
}

AIR-only browseForSave

()method 
public function browseForSave(title:String):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Displays the Save File dialog box, in which the user can select a file destination.

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

title:String — The string that is diplayed in the title bar of the dialog box.


Events
cancel:Event — Dispatched when the user clicks the Cancel button in the Save File dialog box.
 
select:Event — Dispatched when the user selects a file and closes the Save File dialog box.

See also


Example  ( How to use this example )

The following code uses the File.browseForSave() method to let the user select a path for saving a file. When the files are selected, the code saves data to the selected file path.
import flash.filesystem.*;
import flash.events.Event;

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

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

AIR-only cancel

()method 
override public function cancel():void

Runtime Versions: AIR 1.0

Cancels any pending asynchronous operation.

AIR-only canonicalize

()method 
public function canonicalize():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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. On case sensitive file systems (such as Linux), when multiple files exists with names differing only in case, the canonicalize() method adjusts the path to match the first file found (in an order determined by the file system).

In addition, canonicalization converts short filesnames to long filenames on Windows.


Example  ( How to use this example )

The following code shows how to use the canonicalize() method to find the correct capitalization of a directory name. Before running this example, create a directory named AIR Test on the desktop of your computer.
import flash.filesystem.*;

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


The following code shows how to use the canonicalize() method to find the long name of a Windows directory based on its short name. This example assumes that there is an AIR Test directory at the root of the C: drive, and that the system has assigned the short name AIR~1 to the directory.
import flash.filesystem.*;

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

AIR-only clone

()method 
public function clone():File

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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 ActionScript File object. To copy a file, use the copyTo() method.

Returns
File

AIR-only copyTo

()method 
public function copyTo(newLocation:FileReference, overwrite:Boolean = false):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Copies the file or directory at the location specified by this File object to the location specified by the newLocation parameter. The copy process creates any required parent directories (if possible).

Parameters

newLocation:FileReference — The target location of the new file. Note that this File object specifies the resulting (copied) file or directory, not the path to the containing directory.
 
overwrite:Boolean (default = false) — If false, the copy fails if the file specified by the target parameter already exists. If true, the operation overwrites existing file or directory of the same name.


Throws
IOError — The source does not exist; or the destination exists and overwrite is false; or the source could not be copied to the target; or the source and destination refer to the same file or folder and overwrite is set to true. On Windows, you cannot copy a file that is open or a directory that contains a file that is open.

See also


Example  ( How to use this example )

The following code shows how to use the copyTo() method to copy a file. Before running this code, create a test1.txt file in the AIR Test subdirectory of the documents directory on your computer. The resulting copied file is named test2.txt, and it is also in the AIR Test subdirectory. When you set the overwrite parameter to true, the operation overwrites any existing test2.txt file.
import flash.filesystem.File;
import flash.events.Event;

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

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

The following code shows how to use the copyTo() method to copy a file. Before running this code, create a test1.txt file in the AIR Test subdirectory of the home directory on your computer. The resulting copied file is named test2.txt. The try and catch statements show how to respond to errors.
import flash.filesystem.File;

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

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

AIR-only copyToAsync

()method 
public function copyToAsync(newLocation:FileReference, overwrite:Boolean = false):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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. The copy process creates any required parent directories (if possible).

Parameters

newLocation:FileReference — The target location of the new file. Note that this File object specifies the resulting (copied) file or directory, not the path to the containing directory.
 
overwrite:Boolean (default = false) — If false, the copy fails if the file specified by the target file already exists. If true, the operation overwrites any existing file or directory of the same name.


Events
complete:Event — Dispatched when the file or directory has been successfully copied.
 
ioError:IOErrorEvent — The source does not exist; or the destination exists and overwrite is false; or the source could not be copied to the target; or the source and destination refer to the same file or folder and overwrite is set to true. On Windows, you cannot copy a file that is open or a directory that contains a file that is open.

See also


Example  ( How to use this example )

The following code shows how to use the copyToAsync() method to copy a file. Before running this code, be sure to create a test1.txt file in the AIR Test subdirectory of the documents directory on your computer. The resulting copied file is named test2.txt, and it is also in the AIR Test subdirectory. When you set the overwrite parameter to true, the operation overwrites any existing test2.txt file.
import flash.filesystem.File;
import flash.events.Event;

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

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

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

AIR-only createDirectory

()method 
public function createDirectory():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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


Throws
IOError — The directory did not exist and could not be created.

Example  ( How to use this example )

The following code moves a file named test.txt on the desktop to the AIR Test subdirectory of the documents directory. The call to the createDirectory() method ensures that the AIR Test directory exists before the file is moved.
import flash.filesystem.*;

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

AIR-only createTempDirectory

()method 
public static function createTempDirectory():File

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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.

Returns
File — A File object referencing the new temporary directory.

See also


Example  ( How to use this example )

The following code uses the createTempFile() method to obtain a reference to a new temporary directory.
import flash.File;

var temp:File = File.createTempDirectory();
trace(temp.nativePath);
Each time you run this code, a new (unique) file is created.

AIR-only createTempFile

()method 
public static function createTempFile():File

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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.

Returns
File — A File object referencing the new temporary file.

See also


Example  ( How to use this example )

The following code uses the createTempFile() method to obtain a reference to a new temporary file.
import flash.File;

var temp:File = File.createTempFile();
trace(temp.nativePath);
Each time you run this code, a new (unique) file is created.

AIR-only deleteDirectory

()method 
public function deleteDirectory(deleteDirectoryContents:Boolean = false):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Deletes the directory. If this File is actually a symbolic link to a directory, then the link, and not the directory, is removed.

Parameters

deleteDirectoryContents:Boolean (default = false) — Specifies whether or not to delete a directory that contains files or subdirectories. When false, if the directory contains files or directories, a call to this method throws an exception.


Throws
IOError — The directory does not exist, or the directory could not be deleted. On Windows, you cannot delete a directory that contains a file that is open.

See also


Example  ( How to use this example )

The following code creates an empty directory and then uses the deleteDirectory() method to delete the directory.
import flash.filesystem.File;

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

AIR-only deleteDirectoryAsync

()method 
public function deleteDirectoryAsync(deleteDirectoryContents:Boolean = false):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Deletes the directory asynchronously. If this File is actually a symbolic link to a directory, then the link, and not the directory, is removed.

Parameters

deleteDirectoryContents:Boolean (default = false) — Specifies whether or not to delete a directory that contains files or subdirectories. When false, if the directory contains files or directories, the File object dispatches an ioError event.


Events
complete:Event — Dispatched when the directory has been deleted successfully.
 
ioError:IOErrorEvent — The directory does not exist or could not be deleted. On Windows, you cannot delete a directory that contains a file that is open.

See also

AIR-only deleteFile

()method 
public function deleteFile():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Deletes the file. If this File is actually a symbolic link, then the link, not the target file, is removed.


Throws
IOError — The file does not exist or could not to be deleted. On Windows, you cannot delete a file that is currently open.

See also


Example  ( How to use this example )

The following code creates a temporary file and then calls the deleteFile() method to delete it.
import flash.filesystem.*;

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

AIR-only deleteFileAsync

()method 
public function deleteFileAsync():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Deletes the file asynchronously. If this File is actually a symbolic link, then the link, not the target file, is removed.


Events
complete:Event — Dispatched when the file has been deleted successfully.
 
ioError:IOErrorEvent — The file does not exist or could not be deleted. On Windows, you cannot delete a file that is currently open.

See also

AIR-only getDirectoryListing

()method 
public function getDirectoryListing():Array

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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.

Returns
Array — An array of File objects.

See also


Example  ( How to use this example )

The following code shows how to use the getDirectoryListing() method to enumerate the contents of the user directory.
import flash.filesystem.File;

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

AIR-only getDirectoryListingAsync

()method 
public function getDirectoryListingAsync():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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


Events
ioError:ErrorEvent — You do not have adequate permissions to read this directory, or the directory does not exist.
 
directoryListing:FileListEvent — The directory contents have been enumerated successfully. The contents event includes a files property, which is the resulting array of File objects.

See also


Example  ( How to use this example )

The following code shows how to use the getDirectoryListingAsync() method to enumerate the contents of the user directory.
import flash.filesystem.File;
import flash.events.FileListEvent;

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

function directoryListingHandler(event:FileListEvent):void {
    var list:Array = event.files;
    for (var i:uint = 0; i < list.length; i++) {
        trace(list[i].nativePath);
    }
}

AIR-only getRelativePath

()method 
public function getRelativePath(ref:FileReference, useDotDot:Boolean = false):String

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Finds the relative path between two File paths.

The relative path is the list of components that can 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 paths will not cross conspicuous volume boundaries.

Parameters

ref:FileReference — A File object against which the path is given.
 
useDotDot:Boolean (default = false) — Specifies whether the resulting relative path can use ".." components.

Returns
String — The relative path between this file (or directory) and the ref file (or directory), if possible; otherwise null.

Throws
ArgumentError — The reference is null.
 
SecurityError — The caller is not in the application security sandbox.

AIR-only getRootDirectories

()method 
public static function getRootDirectories():Array

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Returns an array of File objects, listing the file system root directories.

For example, on Windows this is a list of volumes such as the C: drive and the D: drive. An empty drive, such as a CD or DVD drive in which no disc is inserted, is not included in this array. On Mac OS and Linux, this method always returns the unique root directory for the machine (the "/" directory)

Returns
Array — An array of File objects, listing the root directories.

Example  ( How to use this example )

The following code outputs a list of root directories:
import flash.filesystem.File;
var rootDirs:Array = File.getRootDirectories();

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

AIR-only moveTo

()method 
public function moveTo(newLocation:FileReference, overwrite:Boolean = false):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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.

The move process creates any required parent directories (if possible).

Parameters

newLocation:FileReference — The target location for the move. This object specifies the path to the resulting (moved) file or directory, not the path to the containing directory.
 
overwrite:Boolean (default = false) — If false, the move fails if the target file already exists. If true, the operation overwrites any existing file or directory of the same name.


Throws
IOError — The source does not exist; or the destination exists and overwrite is set to false; or the source file or directory could not be moved to the target location; or the source and destination refer to the same file or folder and overwrite is set to true. On Windows, you cannot move a file that is open or a directory that contains a file that is open.

See also


Example  ( How to use this example )

The following code shows how to use the moveTo() method to rename a file. The original filename is test1.txt and the resulting filename is test2.txt. Since both the source and destination File object point to the same directory (the Apollo Test subdirectory of the user's documents directory), the moveTo() method renames the file, rather than moving it to a new directory. Before running this code, create a test1.txt file in the AIR Test subdirectory of the documents directory on your computer. When you set the overwrite parameter to true, the operation overwrites any existing test2.txt file.

import flash.filesystem.File;
import flash.events.Event;

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

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

The following code shows how to use the moveTo() method to move a file. The original file is the test1.txt file in the Apollo Test subdirectory of the user's documents directory, and the method moves the file to the Results subdirectory. Before running this code, create a test1.txt file in the AIR Test subdirectory of the home directory on your computer. The try and catch statements show how to respond to errors.
import flash.filesystem.File;

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

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

AIR-only moveToAsync

()method 
public function moveToAsync(newLocation:FileReference, overwrite:Boolean = false):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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.

The move process creates any required parent directories (if possible).

Parameters

newLocation:FileReference — The target location for the move. This object specifies the path to the resulting (moved) file or directory, not the path to the containing directory.
 
overwrite:Boolean (default = false) — If false, the move fails if the target file already exists. If true, the operation overwrites any existing file or directory of the same name.


Events
complete:Event — Dispatched when the file or directory has been successfully moved.
 
ioError:IOErrorEvent — The source does not exist; or the destination exists and overwrite is false; or the source could not be moved to the target; or the source and destination refer to the same file or folder and overwrite is set to true. On Windows, you cannot move a file that is open or a directory that contains a file that is open.

See also


Example  ( How to use this example )

The following code shows how to use the moveToAsync() method to rename a file. The original filename is test1.txt and the resulting name is test2.txt. Since both the source and destination File object point to the same directory (the Apollo Test subdirectory of the user's documents directory), the moveToAsync() method renames the file, rather than moving it to a new directory. Before running this code, create a test1.txt file in the Apollo Test subdirectory of the documents directory on your computer. When you set overwrite parameter to true, the operation overwrites any existing test2.txt file.
import flash.filesystem.File;
import flash.events.Event;

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

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

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

AIR-only moveToTrash

()method 
public function moveToTrash():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Moves a file or directory to the trash.


Throws
IOError — The operating system did not allow the operation; or the file or directory does not exist. On Windows, you cannot move a file that is open or a directory that contains a file that is currently open.

See also

AIR-only moveToTrashAsync

()method 
public function moveToTrashAsync():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Asynchronously moves a file or directory to the trash.


Events
ioError:IOErrorEvent — The operating system did not allow the operation; or the file or directory does not exist. On Windows, you cannot move a file that is open or a directory that contains a file that is currently open.
 
complete:Event — Dispatched when the file or directory has been successfully moved to the trash.

See also

AIR-only openWithDefaultApplication

()method 
public function openWithDefaultApplication():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 2

Opens the file in the application registered by the operating system to open this file type.

AIR prevents you from using the File.openWithDefaultApplication() method to open certain files. On Windows, AIR prevents you from opening files that have certain file types (files with specific extensions, listed below). On Mac OS and Linux, AIR prevents you from opening files that will launch in specific applications, specified below. Attempting to open one of these files using the openWithDefaultApplication() method results in an exception. However, AIR applications installed with a native installer (extended desktop profile applications) are not restricted by these limitations; they can open files of any type.

You cannot open documents from the application directory.

The tables below list file extensions that are prohibited on Windows, as well as the prevented applications on Mac OS and Linux:

Windows Document Extension Kind Mac OS Application Counterpart Linux Application Counterpart
bat Batch file command Terminal No default application
cmd DOS and Windows command file Terminal No default application
com Command Terminal No default application
csh UNIX csh shell script Terminal /bin/csh
dash UNIX dash shell script Terminal /bin/dash
ksh UNIX ksh shell script Terminal /bin/ksh
sh UNIX shell script Terminal /bin/bash
tcsh UNIX tcsh shell script Terminal /bin/tcsh
zsh UNIX zsh shell script Terminal /bin/zsh
exe Executable file Executable bit, .app extension /lib/ld.so
lnk Windows shortcut file Executable bit, .app extension Links in Linux, executable bit set, no default application
pif Program Information File Executable bit, .app extension N/A
reg Registration Information/Key for Windows 95/98, Registry Data File N/A N/A
scf Windows Explorer command ScriptEditor, AutomatorRunner N/A
shb, shs Shell Scrap Object file N/A N/A
prg Program file N/A N/A
vb, vbe, vbs VBScript files N/A N/A
vsmacros Visual Studio .NET binary-based macro project N/A N/A
ws, wsc, wsf, wsh Windows script files ScriptEditor, AutomatorRunner N/A
fxp Fox Pro compiled source code N/A N/A
mas Microsoft Access stored procedures N/A N/A
scr Windows screen saver N/A N/A
py, pyc Python script file Python Python
pl Perl script file Terminal perl
cgi Common Gateway Interface script file Terminal perl
msi, msm, msp, mst, idt, cub, pcp Windows installer file installer N/A
job Windows Task Scheduler task object N/A N/A
jar, js, jse Java archive file, JavaScript file, JScript encoded script file JarLauncher jar
url Internet shortcut N/A N/A
hta HTML application N/A N/A

Mac OS X Only Kind Mac OS X Application Linux Application Counterpart
N/A Mac OS X Java applet AppletLauncher N/A
N/A Mac OS X AppleScript plugin systemevents N/A
N/A Mac OS X widget dock, dashboardlauncher N/A

Linux-only Document Extension Kind Mac OS X Application Counterpart Linux Application
rb Ruby shell script N/A ruby
desktop Desktop files and shortcuts N/A No default application
directory Directory files and shortcuts N/A No default application


Throws
Error — (Mac OS and Linux) No application was found that can open the file. (On Windows, attempting to open a file that has no associated application fails silently, without an exception.)
 
IllegalOperationError — The file is in the application directory or it is of a prohibited file type. This error does not apply for AIR applications installed with a native application installer (extended desktop profile applications).
 
IOError — The file does not exist or no application is registered to open the file.
 
ReferenceError — The file does not exist.

See also


Example  ( How to use this example )

The following code lets the user navigate to an MP3 file and open it in the default application for playing MP3 files.
import flash.filesystem.File;
import flash.net.FileFilter;

var file:File = File.documentsDirectory; 
var mp3Filter:FileFilter = new FileFilter("MP3 Files", "*.mp3"); 
file.browseForOpen("Open", [mp3Filter]); 
file.addEventListener(Event.SELECT, fileSelected); 
 
function fileSelected(e:Event):void 
{ 
    file.openWithDefaultApplication(); 
}

AIR-only resolvePath

()method 
public function resolvePath(path:String):File

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

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

You can use a relative path or absolute path as the path parameter.

If you specify a relative path, the given path is "appended" to the path of the File object. 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.

If you specify an absolute file reference, the method returns the File object pointing to that path. The absolute file reference should use valid native path syntax for the user's operating system (such as "C:\\test" on Windows). Do not use a URL (such as "file:///c:/test") as the path parameter.

All resulting paths are normalized as follows:

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

You should always use the forward slash (/) character as the path separator. On Windows, you can also use the backslash (\) character, but you should not. Using the backslash character can lead to applications that do not work on other platforms.

Filenames and directory names are case-sensitive on Linux.

Parameters

path:String — The path to append to this File object's path (if the path parameter is a relative path); or the path to return (if the path parameter is an absolute path).

Returns
File — A new File object pointing to the resulting path.
Event Detail
AIR-only 

cancel

Event
Event Object Type: flash.events.Event
property Event.type = flash.events.Event.CANCEL

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Dispatched when a pending asynchronous operation is canceled.

The Event.CANCEL constant defines the value of the type property of a cancel event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetA reference to the object on which the operation is canceled.
AIR-only 

complete

Event  
Event Object Type: flash.events.Event
property Event.type = flash.events.Event.COMPLETE

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Dispatched when an asynchronous operation is complete.

The Event.COMPLETE constant defines the value of the type property of a complete event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object that has completed loading.
AIR-only 

directoryListing

Event  
Event Object Type: flash.events.FileListEvent
property FileListEvent.type = flash.events.FileListEvent.DIRECTORY_LISTING

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Dispatched when a directory list is available as a result of a call to the getDirectoryListingAsync() method.

The FileListEvent.DIRECTORY_LISTING constant defines the value of the type property of the event object for a directoryListing event.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
filesAn array of File objects representing the files and directories found.
targetThe FileListEvent object.

See also

AIR-only 

ioError

Event  
Event Object Type: flash.events.IOErrorEvent
property IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Dispatched when an error occurs during an asynchronous file operation.

Defines the value of the type property of an ioError event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
errorIDA reference number associated with the specific error (AIR only).
targetThe network object experiencing the input/output error.
textText to be displayed as an error message.
AIR-only 

securityError

Event  
Event Object Type: flash.events.SecurityErrorEvent
property SecurityErrorEvent.type = flash.events.SecurityErrorEvent.SECURITY_ERROR

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Dispatched when an operation violates a security constraint.

The SecurityErrorEvent.SECURITY_ERROR constant defines the value of the type property of a securityError event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object reporting the security error.
textText to be displayed as an error message.
AIR-only 

select

Event  
Event Object Type: flash.events.Event
property Event.type = flash.events.Event.SELECT

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Dispatched when the user selects a file or directory from a file- or directory-browsing dialog box.

The Event.SELECT constant defines the value of the type property of a select event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe object on which an item has been selected.
AIR-only 

selectMultiple

Event  
Event Object Type: flash.events.FileListEvent
property FileListEvent.type = flash.events.FileListEvent.SELECT_MULTIPLE

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0

Dispatched when the user selects files from the dialog box opened by a call to the browseForOpenMultiple() method.

The FileListEvent.SELECT_MULTIPLE constant defines the value of the type property of the event object for a selectMultiple event.
PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
filesAn array of File objects representing the files selected.
targetThe FileListEvent object.

See also