A common type of dialog is one where the user can select a file to open or save.

File pickers

A file picker is a dialog that allows the user to select a file. It is most commonly used for the Open and Save menu commands, but you can use it any place in which the user needs to select a file. The XPCOM interface nsIFilePicker is used to implement a file picker.

You can use the file picker in one of three modes:

• Open - the user is asked to select a file for opening.
• Get Folder - the user is asked to select a folder (directory).
• Save - the user is asked to select the name to save a file to.

The appearance of the dialog will be different for each type and will vary on each platform. Once the user selects a file or folder, it can be read from or written to.

The file picker interface nsIFilePicker is responsible for displaying a dialog in one of the three modes. You can set a number a features of the dialog by using the interface. When the dialog is closed, you can use the interface functions to get the file that was selected.

Creating a file picker

To begin, you need to create a file picker component and initialize it.

var nsIFilePicker = Components.interfaces.nsIFilePicker;
var fp = Components.classes["@mozilla.org/filepicker;1"].createInstance(nsIFilePicker);
fp.init(window, "Select a File", nsIFilePicker.modeOpen);

First, a new file picker object is created and stored in the variable 'fp'. The 'init' function is used to initialize the file picker. This function takes three arguments, the window that is opening the dialog, the title of the dialog and the mode. The mode here is modeOpen which is used for an Open dialog. You can also use modeGetFolder and modeSave for the other two modes. These modes are constants of the nsIFilePicker interface.

Default directory and filters

There are two features you can set of the dialog before it is displayed.

• The first is the default directory that is displayed when the dialog is opened.
• The second is a filter that indicates the list of file types that are displayed in the dialog. This would be used, for example, to hide all but .html files.

You can set the default directory by setting the displayDirectory property of the file picker object to a directory. The directory should be an nsILocalFile object. If you do not set this, a suitable default will be selected for you. To add filters, call the appendFilters() function to set the file types that you wish to have displayed.

fp.appendFilters(nsIFilePicker.filterHTML | nsIFilePicker.filterImages);
fp.appendFilters(nsIFilePicker.filterText | nsIFilePicker.filterAll);

• The first example will add filters for HTML and for image files. The user will only be able to select those types of files. The manner in which this is done is platform specific. On some platforms, each filter will be separate and the user can choose between HTML files and image files.
• The second example will add filters for text files and for all files. The user therefore has the option to display text files only or all files.

You can also use filterXML and filterXUL to filter for XML and XUL files respectively. If you would like to filter for custom files, you can use the appendFilter() function to do this:

fp.appendFilter("All Files" ,"*.*");
fp.appendFilter("Audio Files (*.wav, *.mp3)","*.wav; *.mp3");

This line will add a filter for Wave and MP3 audio files. The first argument is the title of the file type and the second is a semicolon-seperated list of file masks. You can add more masks or fewer masks as needed. You can call appendFilter as many times as necessary to add additional filters. The order you add them determines their priority. Typically, the first one added is selected by default.

Getting the selected file

Finally, you can show the dialog by calling the show() function. It takes no arguments but returns a status code that indicates what the user selected. Note that the function does not return until the user has selected a file. The function returns one of three constants:

• returnOK - the user selected a file and pressed OK. The file the user selected will be stored in the file picker's file property.
• returnCancel - the user pressed Cancel.
• returnReplace - in the save mode, this return value identifies that the user selected a file to be replaced. (returnOK will be returned when the user entered the name of a new file.)

You should check the return value and then get the file object from the file picker using the file property.

var res = fp.show();
if (res != nsIFilePicker.returnCancel){
  var thefile = fp.file;
  // --- do something with the file here ---
}

Next, we'll see how to create a wizard.