nsIFilePicker

Implemented by: @mozilla.org/filepicker;1. To create an instance, use:

var filePicker = Components.classes["@mozilla.org/filepicker;1"]
                 .createInstance(Components.interfaces.nsIFilePicker);

Method overview

Attributes

Constants

Mode constants

These constants are used to specify the type of file picker to create when calling init().

Return value constants

These values are returned by show(), indicating the result of the file picker activity.

Filter constants

These constants are used to create filters for commonly-used file types. For the most up to date list see filepicker.properties.

Methods

appendFilter()

Appends a custom file extension filter to the dialog. The filter appended first will be used to display the nsIFilePicker dialog, the user may then select another from the list.

void appendFilter(
  in AString title,
  in AString filter
);

Parameters

title

The title of the filter.

filter

The filter string. Multiple extensions may be included, separated by a semicolon and a space.

Example

Some example filter strings:

• "*.ics"
• "*.txt; *.doc; *.rtf"

appendFilters()

Appends a list of file extension filters, from the predefined list, to the dialog.

void appendFilters(
  in long filterMask
);

Parameters

filterMask

A combination of the filters you wish to use. You may OR multiple filters together; for example filterAll | filterHTML.

init()

Initialize the file picker widget. The file picker is not valid until this method is called.

void init(
  in nsIDOMWindow parent,
  in AString title,
  in short mode
);

Parameters

parent

The nsIDOMWindow parent. This dialog will be dependent on this parent. Must be non-null.

title

The file picker dialog title. If this is null, the dialog will have the default title.

mode

One of the mode constants, indicating the type of picker to create.

open()

Opens the file dialog asynchrounously. The passed in object's done method will be called upon completion.

void open(
  in nsIFilePickerShownCallback aFilePickerShownCallback
);

Parameters

aFilePickerShownCallback

The nsIFilePickerShownCallback to be called on completion.

Displays the file picker dialog. The dialog is displayed modally.

short show();

Parameters

None.

Return value

One of the return constants.

Example

Here's an example:

const nsIFilePicker = Components.interfaces.nsIFilePicker;
var fp = Components.classes["@mozilla.org/filepicker;1"]
	           .createInstance(nsIFilePicker);
fp.init(window, "Dialog Title", nsIFilePicker.modeOpen);
fp.appendFilters(nsIFilePicker.filterAll | nsIFilePicker.filterText);
var rv = fp.show();
if (rv == nsIFilePicker.returnOK || rv == nsIFilePicker.returnReplace) {
  var file = fp.file;
  // Get the path as string. Note that you usually won't 
  // need to work with the string paths.
  var path = fp.file.path;
  // work with returned nsILocalFile...
}

If your code is a component and window is not defined, you can get one using nsIWindowMediator.

When selecting multiple files:

    ....
    fp.init(window, "Dialog Title", nsIFilePicker.modeOpenMultiple);
    ....
    var files = fp.files;
    var paths = [];
    while (files.hasMoreElements()) 
    {
        var arg = files.getNext().QueryInterface(Components.interfaces.nsILocalFile).path;
        paths.push(arg);
    }