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:
And to instantiate a new instance of the FileReference object, use this code as a template:
import flash.net.FileReferece;
var myFile_fr:FileReference = new FileReference();
Properties
creationDate
Availability :
FP:8, AS:1.0Generic 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.0Generic 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.0Generic 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.0Generic 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.0Generic Template :
myFile_fr.size;Description: This property represents the total size of the file in bytes.
type
Availability :
FP:8, AS:1.0Generic 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.0Generic 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.0Generic 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
Description: This method will allow end users to browse for files on their local system and have them returned to Flash.[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: " *

//browse
file_fr.browse(fileTypes);
cancel
Availability :
FP:8, AS:1.0Generic 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.0Generic 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 :
BooleanIf 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.0Generic Template :
myFile_fr.removeListener(listener);Parameter:
- listener
This is the object that listens for the events of a FileReference object.
Returns :
BooleanIf 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.0Generic Template :
myFile_fr.upload(path);Parameter:
- path
This is the path to the server-side script where the upload will take place.
Returns :
BooleanIf 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.0Generic 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.0Generic 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.0Generic 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.0Generic 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.0Generic 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.0Generic 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.0Generic 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.0Generic 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();