Skip to main content

Visit Mozilla.org

nsIFilePicker

From MDC

The file picker component is used to display standard "Open File"/"Save File"/"Select Folder" dialogs.

Contents


nsIFilePicker is defined in widget/public/nsIFilePicker.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.8a1).

Inherits from: nsISupports

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

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

[edit] Method Overview

void init(in nsIDOMWindow parent, in AString title, in short mode);
void appendFilters(in long filterMask);
void appendFilter(in AString title, in AString filter);
short show();

[edit] Attributes

Attribute Type Description
defaultString AString The filename that should be suggested to the user as a default.
Note: throws NS_ERROR_FAILURE on attempts to get
filterIndex long The (0-based) index of the filter which is currently selected in the File Picker dialog. Set this to choose a particular filter to be selected by default.
displayDirectory nsILocalFile The directory that the file open/save dialog initially displays
file nsILocalFile readonly The currently selected file
fileURL nsIFileURL readonly The url of the currently selected file
files nsISimpleEnumerator readonly An enumerator of the currently selected files
Note: Only works with in modeOpenMultiple mode.

[edit] Constants

[edit] Constants

Constant Value Description
modeOpen 0 Load a file or directory
modeSave 1 Save a file or directory
modeGetFolder 2 Select a folder/directory
modeOpenMultiple 3 Load multiple files
returnOK 0 The file picker dialog was closed by the user hitting 'OK'
returnCancel 1 The file picker dialog was closed by the user hitting 'Cancel'
returnReplace 2 The user chose an existing file and acknowledged that he wants to overwrite the file
filterAll 0x01 Corresponds to the *.* filter for file extensions
filterHTML 0x02 Corresponds to the *.html and *.htm filters for file extensions
filterText 0x04 Corresponds to the *.txt filter for file extensions
filterImages 0x08 Corresponds to the *.png, *.gif, *.jpg, and *.jpeg filters for file extensions
filterXML 0x10 Corresponds to the *.xml filter for file extensions
filterXUL 0x20 Corresponds to the *.xul filter for file extensions
filterApps 0x40 Corresponds to the platform specific application filter for file extensions

[edit] Methods

[edit] 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);
[edit] Parameters
parent

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

title

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

mode

One of the four mode constants defined above.

[edit] appendFilters()

Appends a list of file extension filters to the dialog 

 void appendFilters(in long filterMask);
[edit] Parameters
filterMask

A combination of the appropriate filters, for example: filterAll | filterHTML

[edit] appendFilter()

Appends a custom file extension filter to the dialog 

 void appendFilter(in AString title,
                   in AString filter);
[edit] Paramaters
title

The title for the filter.

filter

The filter string (e.g., *.ics) - semicolon and space separated

[edit] show()

Displays the file picker dialog modally 

 short show();
[edit] Return value

One of the three return constants defined above.

[edit] 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.

Retrieved from "http://developer.mozilla.org/en/docs/nsIFilePicker"