flash.net.FileReferenceList

Package	flash.net
Class	public class FileReferenceList
Inheritance	FileReferenceList Object

Player version:

Flash Player 8

The FileReferenceList class provides a means to let users select one or more files for uploading. A FileReferenceList object represents a group of one or more local files on the user's disk as an array of FileReference objects. For detailed information and important considerations about FileReference objects and the FileReference class, which you use with FileReferenceList, see the FileReference class.

To work with the FileReferenceList class:

Instantiate the class: var myFileRef = new FileReferenceList();
Call FileReferenceList.browse(), to display a dialog box in which the user can select one or more files to upload: myFileRef.browse();
After browse() is successfully called, the fileList property of the FileReferenceList object is populated with an array of FileReference objects.
Call FileReference.upload() on each element in the fileList array.

The FileReferenceList class includes a browse() method and a fileList property for working with multiple files. While a call to FileReferenceList.browse() is executing, SWF file playback pauses on stand-alone and external players for Linux and Mac OS X 10.1 and earlier.

Example
The following example allows a user to select multiple files and then uploads each of them to a server.

import flash.net.FileReferenceList;
import flash.net.FileReference;

var listener:Object = new Object();

listener.onSelect = function(fileRefList:FileReferenceList) {
    trace("onSelect");
    var list:Array = fileRefList.fileList;
    var item:FileReference;
    for(var i:Number = 0; i < list.length; i++) {
        item = list[i];
        trace("name: " + item.name);
        trace(item.addListener(this));
        item.upload("http://www.yourdomain.com/");
    }
}

listener.onCancel = function():Void {
    trace("onCancel");
}

listener.onOpen = function(file:FileReference):Void {
    trace("onOpen: " + file.name);
}

listener.onProgress = function(file:FileReference, bytesLoaded:Number, bytesTotal:Number):Void {
    trace("onProgress with bytesLoaded: " + bytesLoaded + " bytesTotal: " + bytesTotal);
}

listener.onComplete = function(file:FileReference):Void {
    trace("onComplete: " + file.name);
}

listener.onHTTPError = function(file:FileReference, httpError:Number):Void {
    trace("onHTTPError: " + file.name + " httpError: " + httpError);
}

listener.onIOError = function(file:FileReference):Void {
    trace("onIOError: " + file.name);
}

listener.onSecurityError = function(file:FileReference, errorString:String):Void {
    trace("onSecurityError: " + file.name + " errorString: " + errorString);
}

var fileRef:FileReferenceList = new FileReferenceList();
fileRef.addListener(listener);
fileRef.browse();

See also

FileReference

	Property
		fileList : Array An array of FileReference objects.

	Properties inherited from class Object
	`__proto__, __resolve, constructor, prototype`

	Methods inherited from class Object
	`addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch`

	Event	Summary	Defined by
		onCancel = function(fileRefList:FileReferenceList) {}	Invoked when the user dismisses the file-browsing dialog box.	FileReferenceList
		onSelect = function(fileRefList:FileReferenceList) {}	Invoked when the user selects one or more files to upload from the file-browsing dialog box.	FileReferenceList

Property detail

fileList

property

public var fileList:Array

Player version:

Flash Player 8

An array of FileReference objects.

When the FileReferenceList.browse() method has been called and the user has selected one or more files from the dialog box opened by browse(), this property is populated with an array of FileReference objects, each of which represents a file the user selected. You can then use this array to upload the files with FileReference.upload(). You must upload one file at a time.

The fileList property is populated anew each time browse() is called on that FileReferenceList object.

The properties of FileReference objects are described in the FileReference class documentation.

Example
The following example demonstrates the fileList property.

import flash.net.FileReferenceList;
import flash.net.FileReference;

var listener:Object = new Object();
listener.onSelect = function(fileRefList:FileReferenceList) {
    trace("onSelect");
    var list:Array = fileRefList.fileList;
    var item:FileReference;
    for(var i:Number = 0; i < list.length; i++) {
        item = list[i];
        trace("name: " + item.name);
    }
}

var fileRef:FileReferenceList = new FileReferenceList();
fileRef.addListener(listener);
fileRef.browse();

Constructor detail

FileReferenceList

()

constructor

public function FileReferenceList()

Player version:

Flash Player 8

Creates a new FileReferenceList object. This object contains nothing until you call browse() on it. When you call browse() on the FileReference object, the fileList property of the object is populated with an array of FileReference objects.

Example
The following example creates a new FileReferenceList object, iterates over each selected file, and outputs their names.

import flash.net.FileReferenceList;

var listener:Object = new Object();
listener.onSelect = function(fileRefList:FileReferenceList) {
    trace("onSelect");
    var arr:Array = fileRefList.fileList;
    for(var i:Number = 0; i < arr.length; i++) {
        trace("name: " + arr[i].name);
    }
}

var fileRef:FileReferenceList = new FileReferenceList();
fileRef.addListener(listener);
fileRef.browse();

Method detail

addListener

()

method

public function addListener(listener:Object):Void

Player version:

Flash Player 8

Registers an object to receive notification when a FileReferenceList event listener is invoked.

Parameters

listener:Object — An object that listens for a callback notification from the FileReferenceList event listeners.

Example
The following example demonstrates the addListener() method.

import flash.net.FileReferenceList;

var listener:Object = new Object();
listener.onCancel = function(fileRefList:FileReferenceList) {
    trace("onCancel");
}

listener.onSelect = function(fileRefList:FileReferenceList) {
    trace("onSelect: " + fileRefList.fileList.length);
}

var fileRef:FileReferenceList = new FileReferenceList();
fileRef.addListener(listener);
fileRef.browse();

browse

()

method

public function browse([typelist:Array]):Boolean

Player version:

Flash Player 8

Displays a file-browsing dialog box in which the user can select one or more local files to upload. The dialog box is native to the user's operating system. When you call this method and the user successfully selects files, the fileList property of this FileReferenceList object is populated with an array of FileReference objects, one for each file selected by the user. Each subsequent time that FileReferenceList.browse() is called, the FileReferenceList.fileList property is reset to the file or files selected by the user in the dialog box.

You can pass an array of file types to determine which files the dialog box displays.

Only one browse() or download() session can be performed at a time on a FileReferenceList object (because only one dialog box can be displayed at a time).

Parameters

typelist:Array [optional] — An array of file types used to filter the files that are displayed in the dialog box. If you omit this parameter, all files are displayed. If you include this parameter, the array must contain one or more elements enclosed in curly braces { }. You can use one of two formats for the array:

A list of file type descriptions followed by their Windows file extensions only.
Each element in the array must contain a string that describes the file type and a semicolon-delimited list of Windows file extensions, with a wildcard (*) character preceding each extension. The syntax for each element is as follows:
[{description: "string describing the first set of file types", extension: "semicolon-delimited list of file extensions"}]
Example:
[{description: "Images", extension: "*.jpg;*.gif;*.png"}, {description: "SWF files", extension: "*.swf"}, {description: "Documents", extension: "*.doc;*.pdf"}]
A list of file type descriptions followed by their Windows file extensions and their Macintosh file types.
Each element in the array must contain a string that describes the file type; a semicolon-delimited list of Windows file extensions, with a wildcard (*) character preceding each extension; and a semicolon-delimited list of Macintosh file types, with a wildcard (*) character preceding each type. The syntax for each element is as follows:
[{description: "string describing the first set of file types", extension: "semicolon-delimited list of Windows file extensions", macType: "semicolon-delimited list of Macintosh file types"}]
Example:
[{description: "Image files", extension: "*.jpg;*.gif;*.png", macType: "JPEG;jp2_;GIFf;PNGf"}, {description: "SWF files", extension: "*.swf", macType: "SWFL"}]

The two formats are not interchangeable in a single browse() call. You must use one or the other.

The list of extensions is used to filter the files in Windows, depending on the file type the user selects. It is not actually displayed in the dialog box. To display the file types for users, you must list the file types in the description string as well as in the extension list. The description string is displayed in the dialog box in Windows. (It is not used on the Macintosh.) On the Macintosh, if you supply a list of Macintosh file types, that list is used to filter the files. If you don't supply a list of Macintosh file types the list of Windows extensions is used.

Returns

Boolean — Returns true if the parameters are valid and the file-browsing dialog box is displayed. Returns false if the dialog box is not displayed, if another browse session is already in progress, or if you use the typelist parameter but fail to provide a description or extension string in any element in the array.

See also

FileReference.browse()
FileReference

Example
The following example demonstrates the browse() method.

import flash.net.FileReferenceList;

var allTypes:Array = new Array();
var imageTypes:Object = new Object();
imageTypes.description = "Images (*.JPG;*.JPEG;*.JPE;*.GIF;*.PNG;)";
imageTypes.extension = "*.jpg; *.jpeg; *.jpe; *.gif; *.png;";
allTypes.push(imageTypes);

var textTypes:Object = new Object();
textTypes.description = "Text Files (*.TXT;*.RTF;)";
textTypes.extension = "*.txt; *.rtf";
allTypes.push(textTypes);

var fileRef:FileReferenceList = new FileReferenceList();
fileRef.browse(allTypes);

removeListener

()

method

public function removeListener(listener:Object):Boolean

Player version:

Flash Player 8

Removes an object from the list of objects that receive event notification messages.

Parameters

listener:Object — An object that listens for a callback notification from the FileReferenceList event listeners.

Returns

Boolean — Returns true if the object is removed. Otherwise, this method returns false.

Example
The following example demonstrates the removeListener method.

import flash.net.FileReferenceList;

var listener:Object = new Object();
listener.onCancel = function(fileRefList:FileReferenceList) {
    trace("onCancel");
    trace(fileRefList.removeListener(this)); // true
}

listener.onSelect = function(fileRefList:FileReferenceList) {
    trace("onSelect: " + fileRefList.fileList.length);
}

var fileRef:FileReferenceList = new FileReferenceList();
fileRef.addListener(listener);
fileRef.browse();

Event detail

onCancel

event listener

public onCancel = function(fileRefList:FileReferenceList) {}

Player version:

Flash Player 8

Invoked when the user dismisses the file-browsing dialog box. (This dialog box is displayed when you call the FileReferenceList.browse(), FileReference.browse(), or FileReference.download() methods.)

Parameters

fileRefList:FileReferenceList — The FileReferenceList object that initiated the operation.

Example
The following example demonstrates the onCancel listener.

import flash.net.FileReferenceList;

var listener:Object = new Object();
listener.onCancel = function(fileRefList:FileReferenceList) {
    trace("onCancel");
}

var fileRef:FileReferenceList = new FileReferenceList();
fileRef.addListener(listener);
fileRef.browse();

See also

flash.net.FileReferenceList.browse()

onSelect

event listener

public onSelect = function(fileRefList:FileReferenceList) {}

Player version:

Flash Player 8

Invoked when the user selects one or more files to upload from the file-browsing dialog box. (This dialog box is displayed when you call the FileReferenceList.browse(), FileReference.browse(), or FileReference.download() methods.) When the user selects a file and confirms the operation (for example, by clicking Save), the FileReferenceList object is populated with FileReference objects that represent the files selected by the user.

Parameters

fileRefList:FileReferenceList — The FileReferenceList object that initiated the operation.

Example
The following example demonstrates the onSelect listener.

import flash.net.FileReferenceList;
import flash.net.FileReference;

var listener:Object = new Object();

listener.onSelect = function(fileRefList:FileReferenceList) {
    trace("onSelect");
    var list:Array = fileRefList.fileList;
    var item:FileReference;
    for(var i:Number = 0; i < list.length; i++) {
        item = list[i];
        trace("name: " + item.name);
        trace(item.addListener(this));
        item.upload("http://www.yourdomain.com/");
    }
}

listener.onComplete = function(file:FileReference):Void {
    trace("onComplete: " + file.name);
}

var fileRef:FileReferenceList = new FileReferenceList();
fileRef.addListener(listener);
fileRef.browse();

See also

flash.net.FileReferenceList.browse()

Flash CS5 ActionScript 2.0 Language Reference	All Packages \| All Classes \| Language Elements \| Index \| Appendixes \| Frames No Frames
Class FileReferenceList	Properties \| Methods \| Events

	Method
		FileReferenceList() Creates a new FileReferenceList object.
		addListener(listener:Object):Void Registers an object to receive notification when a FileReferenceList event listener is invoked.
		browse([typelist:Array]):Boolean Displays a file-browsing dialog box in which the user can select one or more local files to upload.
		removeListener(listener:Object):Boolean Removes an object from the list of objects that receive event notification messages.