The FileReference Class | Macromedia Flash Professional 8 Unleashed

The `FileReference` Class

The FileReference class was created to allow users to browse for, upload, and download single files.

It is important when using this class to import it first at the beginning of your script, like this:

 import flash.net.FileReferece;

And to instantiate a new instance of the FileReference object, use this code as a template:

 var myFile_fr:FileReference = new FileReference();

Properties

`creationDate`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.creationData;

Description:

This Date property represents the creation date of the file on the end user's computer.

`creator`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.creator;

Description:

This string property represents the Macintosh creator file type of the file on the end user's computer.

`modificationDate`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.modificationDate;

Description:

This Date property represents the last modification date of the file on the end user's computer.

`name`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.name;

Description:

This string property is the name of the file on the end user's computer. Note that this will not return the path to the file, because that is a security risk.

`size`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.size;

Description:

This property represents the total size of the file in bytes.

`type`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.type;

Description:

This string property represents the file type date of the file on the end user's computer.

Methods

`addListener`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.addListener(listener);

Parameter:

listener This is the object that listens for the events of a FileReference object.

Description:

This method will add an event listener to an instance of the FileReference object.

Example:

This example will create a FileReference object and automatically call the browse method when you test it. After you select a file and click Open, all the properties of that file will be sent to the Output panel:

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onSelect = function(){     trace("name: "+file_fr.name);     trace("creation date: "+file_fr.creationDate);     trace("modification date: "+file_fr.modificationDate);     trace("type: "+file_fr.type);     trace("size in bytes: "+file_fr.size);     trace("creator: "+file_fr.creator); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse();

`browse`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.browse(types);

Parameter:

types This array is an optional parameter that will allow you to set certain file types to be able to be selected. Inside this array are objects that have three properties:
- description This is what appears to the user in the file type drop-down.
- extensions These are the different file type extensions you want to allow, each separated by a semicolon, like this: "*.jpg;*.png;*.gif".
- macType This a Macintosh-specific property that will allow you to limit files to macType.

Description:

This method will allow end users to browse for files on their local system and have them returned to Flash.

Example:

This example will create a FileReference object and automatically call the browse method when you test it. And it will limit the files to just a few image types. After you select a file and select Open, all the properties of that file will be sent to the Output panel:

[View full width]
 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onSelect = function(){     trace("name: "+file_fr.name);     trace("creation date: "+file_fr.creationDate);     trace("modification date: "+file_fr.modificationDate);     trace("type: "+file_fr.type);     trace("size in bytes: "+file_fr.size);     trace("creator: "+file_fr.creator); } //add the listener to the FileReference object file_fr.addListener(list_obj); //the file types you want var fileTypes:Array = new Array({description: "Images - .jpg, .gif, .png", extension: " * .jpg;*.gif;*.png"}); //browse file_fr.browse(fileTypes);

`cancel`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.cancel();

Description:

This method will cancel any download or upload currently active.

Example:

This example will allow someone to download about 90% of the file and then cancel on them:

 import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //the listener var list_obj:Object = new Object(); list_obj.onProgress = function(file:FileReference,  bytesLoaded:Number, bytesTotal:Number):Void  {     if ((bytesLoaded/bytesTotal/2) >= .9) {         //almost completed, but not quite         file_fr.cancel();     } } //add the listener file_fr.addListener(list_obj); var path:String = "http://localHost.com/bigImage.jpg"; file_fr.download(path,"myImage.jpg");

`download`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.download(path, fileName);

Parameters:

path This is a string holding the path to the file on the server you want to download.
fileName This string is the default filename displayed in the window that allows you to map to where you want to save the file.

Returns: Boolean

If the window pops up allowing you to map where the file should be saved, it returns true; otherwise, false is returned.

Description:

This method will allow end users to download files from a server directly to their computer.

Example:

This example will allow someone to download a file from the local server:

 import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //the listener var list_obj:Object = new Object(); list_obj.onComplete = function(file:FileReference):Void  {     trace("ALL DONE!"); } //add the listener file_fr.addListener(list_obj); var path:String = "http://localHost.com/bigImage.jpg"; file_fr.download(path,"myImage.jpg");

`removeListener`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.removeListener(listener);

Parameter:

listener This is the object that listens for the events of a FileReference object.

Returns: Boolean

If the listener is removed successfully, true is returned; otherwise, false is returned.

Description:

This method will remove an event listener from an instance of the FileReference object.

Example:

This example will create a FileReference object and automatically call the browse method when you test it. After you select a file and click Open, the name property will be sent to the Output panel, and the listener will be removed:

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onSelect = function(){     trace("name: "+file_fr.name);     trace(file_fr.removeListener(this)); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse();

`upload`

Availability: FP:8, AS:1.0

Generic Template: myFile_fr.upload(path);

Parameter:

path This is the path to the server-side script where the upload will take place.

Returns: Boolean

If there was no problem with calling this method (that is, no file in the FileReference yet), then TRue is returned; otherwise, false is returned.

Description:

This method will allow end users to upload files directly from Flash to a server.

Example:

This example will create a FileReference object and automatically call the browse method when you test it. After you have selected a file, it will call the upload method that will send the information to a server-side page.

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onSelect = function(){     file_fr.upload("http://localHost/upload.php"); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse(); For a real working example, see Chapter 22, "PHP and Flash."

Events

`onCancel`

Availability: FP:8, AS:1.0

Generic Template: Listener.onCancel = function(fileRef);

Parameter:

fileRef This is a reference to the FileReference object that initiated the dialog window opening.

Description:

This event is triggered when the dialog window is open, and the user chooses Cancel.

Example:

This example will open a dialog box for a user to choose a file, and then it listens for the Cancel button:

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits cancel list_obj.onCancel = function(fileRef:FileReference){     trace("Cancel Hit"); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse();

`onComplete`

Availability: FP:8, AS:1.0

Generic Template: Listener.onComplete = function(fileRef);

Parameter:

fileRef This is a reference to the FileReference object that initiated the dialog window opening.

Description:

This event is triggered when a file upload or download completes successfully.

Example:

This example will allow a user to upload a file to a PHP page; then it listens for when the upload is complete:

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onCancel = function(fileRef:FileReference){     fileRef.upload("http://localHost/upload.php"); } //the event for when the file is finished uploading list_obj.onComplete = function(fileRef:FileReference){     trace("ALL DONE!!"); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse(); For a real working example, see Chapter 22, "PHP and Flash."

`onHTTPError`

Availability: FP:8, AS:1.0

Generic Template: Listener.onHTTPError = function(fileRef, error){

Parameter:

fileRef This is a reference to the FileReference object that initiated the dialog window opening.
error A numerical value representing the error returned. For a complete list of errors, try ftp://ftp.isi.edu/in-notes/rfc2616.txt.

Description:

This event is triggered when an HTTP error occurs during uploading.

Exa-mple:

This example will allow a user to upload a file to a PHP page; then it listens for an HTTP error:

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onCancel = function(fileRef:FileReference){     fileRef.upload("http://localHost/upload.php"); } //the event for HTTP errors list_obj.onHTTPError = function(fileRef:FileReference, error:Number){     trace("HTTP error: with " + fileRef.name + ":error #" + error); } //the event for when the file is finished uploading list_obj.onComplete = function(fileRef:FileReference){     trace("ALL DONE!!"); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse(); For a real working example, see Chapter 22, "PHP and Flash".

`onIOError`

Availability: FP:8, AS:1.0

Generic Template: Listener.onIOError = function(fileRef){

Parameter:

fileRef This is a reference to the FileReference object that initiated the dialog window opening.

Description:

This event is triggered when any input or output errors occur. You will see these errors most often when servers require authentication, and because there are no means for this to be accomplished with Flash, an error will occur.

Example:

This example will allow a user to upload a file to a PHP page; then it listens for an IO error:

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onCancel = function(fileRef:FileReference){     fileRef.upload("http://localHost/upload.php"); } //the event for IO errors list_obj.onIOError = function(fileRef:FileReference){     trace("Input/Output error occured"); } //the event for when the file is finished uploading list_obj.onComplete = function(fileRef:FileReference){     trace("ALL DONE!!"); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse(); For a real working example, see Chapter 22, "PHP and Flash."

`onOpen`

Availability: FP:8, AS:1.0

Generic Template: Listener.onOpen = function(fileRef){

Parameter:

fileRef This is a reference to the FileReference object that initiated the dialog window opening.

Description:

This event is triggered when an upload or download method is called.

Example:

This example will allow a user to upload a file to a PHP page; then it listens for when the upload starts:

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onCancel = function(fileRef:FileReference){     fileRef.upload("http://localHost/upload.php"); } //the event for when the upload starts list_obj.onOpen = function(fileRef:FileReference){     trace("Upload has started"); } //the event for when the file is finished uploading list_obj.onComplete = function(fileRef:FileReference){     trace("ALL DONE!!"); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse(); For a real working example, see Chapter 22, "PHP and Flash."

`onProgress`

Availability: FP:8, AS:1.0

Generic Template: Listener.onProgress = function(fileRef, bytesLoaded, bytesTotal){

Parameter:

fileRef This is a reference to the FileReference object that initiated the dialog window opening.
bytesLoaded This is a reference to amount of bytes that have been downloaded or uploaded, depending on the method called.
bytesTotal This is a reference to total amount of bytes being downloaded or uploaded, depending on the method called.

Description:

This event is triggered periodically during either upload or download.

Example:

This example will download a file and trace the percentage downloaded as it progresses:

[View full width]
 import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //the listener var list_obj:Object = new Object(); //the event that monitors download progress list_obj.onProgress = function(file:FileReference, bytesLoaded:Number, bytesTotal:Number) :Void  {     var per = bytesLoaded/bytesTotal;     trace(Math.floor(per*100)+"%"); } //add the listener file_fr.addListener(list_obj); var path:String = "http://localHost.com/bigImage.jpg"; file_fr.download(path,"myImage.jpg");

`onSecurityError`

Availability: FP:8, AS:1.0

Generic Template: Listener.onSecurityError = function(fileRef, error){

Parameter:

fileRef This is a reference to the FileReference object that initiated the dialog window opening.
error This is a string describing the security error that occurred.

Description:

This event is triggered when a security error occurs during either upload or download.

Example:

This example will attempt to download a file from the server, and if a security error occurs, it will be sent to the Output panel:

 import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //the listener var list_obj:Object = new Object(); //the event that is triggered when a security error occurs list_obj.onSecurityError = function(file:FileReference, error:String):Void  {     trace("Security error: " + error); } //add the listener file_fr.addListener(list_obj); var path:String = "http://localHost.com/bigImage.jpg"; file_fr.download(path,"myImage.jpg");

`onSelect`

Availability: FP:8, AS:1.0

Generic Template: Listener.onSelect = function(fileRef){

Parameter:

fileRef This is a reference to the FileReference object that initiated the dialog window opening.

Description:

This event is triggered when a user selects a file and either clicks Open or double-clicks the file.

Example:

This example will allow the user to select a file, and when the user clicks open, all the file properties will be sent to the Output panel:

 //import the FileReference Object import flash.net.FileReference; //the file reference object var file_fr:FileReference = new FileReference(); //object for listening to for FileReference events var list_obj:Object = new Object(); //the event for when a user selects a file and hits open list_obj.onSelect = function(){     trace("name: "+file_fr.name);     trace("creation date: "+file_fr.creationDate);     trace("modification date: "+file_fr.modificationDate);     trace("type: "+file_fr.type);     trace("size in bytes: "+file_fr.size);     trace("creator: "+file_fr.creator); } //add the listener to the FileReference object file_fr.addListener(list_obj); //browse file_fr.browse();