1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #include
"nsISupports.idl"
11 interface mozIDOMWindowProxy
;
12 interface nsISimpleEnumerator
;
14 // Declared in this file, below.
15 interface nsIFilePickerShownCallback
;
17 [scriptable
, uuid(9285b984
-02d3
-46b4
-9514-7da8c471a747
)]
18 interface nsIFilePicker
: nsISupports
21 modeOpen
= 0, // Load a file or directory
22 modeSave
= 1, // Save a file or directory
23 modeGetFolder
= 2, // Select a folder/directory
24 modeOpenMultiple
= 3, // Load multiple files
27 cenum ResultCode
: 16 {
28 returnOK
= 0, // User hit Ok, process selection
29 returnCancel
= 1, // User hit cancel, ignore selection
30 returnReplace
= 2, // User acknowledged file already exists so ok to replace, process selection
33 const long filterAll
= 0x001; // *.*
34 const long filterHTML
= 0x002; // *.html; *.htm
35 const long filterText
= 0x004; // *.txt
36 const long filterImages
= 0x008; // *.jpe; *.jpg; *.jpeg; *.gif;
37 // *.png; *.bmp; *.ico; *.svg;
38 // *.svgz; *.tif; *.tiff; *.ai;
39 // *.drw; *.pct; *.psp; *.xcf;
40 // *.psd; *.raw; *.webp
41 const long filterXML
= 0x010; // *.xml
42 const long filterXUL
= 0x020; // *.xul
43 const long filterApps
= 0x040; // Applications (per-platform implementation)
44 const long filterAllowURLs
= 0x080; // Allow URLs
45 const long filterAudio
= 0x100; // *.aac; *.aif; *.flac; *.iff;
46 // *.m4a; *.m4b; *.mid; *.midi;
47 // *.mp3; *.mpa; *.mpc; *.oga;
48 // *.ogg; *.ra; *.ram; *.snd;
50 const long filterVideo
= 0x200; // *.avi; *.divx; *.flv; *.m4v;
51 // *.mkv; *.mov; *.mp4; *.mpeg;
52 // *.mpg; *.ogm; *.ogv; *.ogx;
53 // *.rm; *.rmvb; *.smil; *.webm;
55 const long filterPDF
= 0x400; // *.pdf;
57 cenum CaptureTarget
: 8 {
58 captureNone
= 0, // No capture target specified.
59 captureDefault
= 1, // Missing/invalid value default.
60 captureUser
= 2, // "user" capture target specified.
61 captureEnv
= 3, // "environment" capture target specified.
65 * Initialize the file picker widget. The file picker is not valid until this
68 * @param parent mozIDOMWindow parent. This dialog will be dependent
69 * on this parent. parent must be non-null.
70 * @param title The title for the file widget
71 * @param mode load, save, or get folder
74 void init
(in mozIDOMWindowProxy parent
, in AString title
, in nsIFilePicker_Mode mode
);
77 * Returns a Promise that resolves to true if the passed nsIFilePicker mode
78 * is supported on the current platform, and false otherwise. The Promise may
79 * reject if something unexpected occurs while trying to determine if the mode
83 * @return Promise<boolean>
86 Promise isModeSupported
(in nsIFilePicker_Mode mode
);
89 * Append to the filter list with things from the predefined list
91 * @param filters mask of filters i.e. (filterAll | filterHTML)
94 void appendFilters
(in long filterMask
);
99 * @param title name of the filter
100 * @param filter extensions to filter -- semicolon and space separated
103 void appendFilter
(in AString title
,
107 * Add a raw filter (eg, add a MIME type without transforming it to a list of
110 * @param filter a filter taken directly from the accept attribute
114 void appendRawFilter
(in AString filter
);
117 * The filename that should be suggested to the user as a default. This should
118 * include the extension.
120 * @throws NS_ERROR_FAILURE on attempts to get
122 attribute AString defaultString
;
125 * The extension that should be associated with files of the type we
126 * want to work with. On some platforms, this extension will be
127 * automatically appended to filenames the user enters, if needed.
129 attribute AString defaultExtension
;
132 * The filter which is currently selected in the File Picker dialog
134 * @return Returns the index (0 based) of the selected filter in the filter list.
136 attribute
long filterIndex
;
139 * Set the directory that the file open/save dialog initially displays
140 * Note that, if displaySpecialDirectory has been already set, this value will
143 * @param displayDirectory the name of the directory
146 attribute nsIFile displayDirectory
;
149 * Set the directory that the file open/save dialog initially displays using
150 * one of the special name as such as 'Desk', 'TmpD', and so on.
151 * Note that, if displayDirectory has been already set, this value will be
154 * @param displaySpecialDirectory the name of the special directory
157 attribute AString displaySpecialDirectory
;
161 * Get the nsIFile for the file or directory. A different file object
162 * may be returned by each invocation.
164 * @return Returns the file currently selected
166 readonly attribute nsIFile file
;
169 * Get the nsIURI for the file or directory.
171 * @return Returns the file currently selected
173 readonly attribute nsIURI fileURL
;
176 * Get the enumerator for the selected files
177 * only works in the modeOpenMultiple mode
179 * @return Returns the files currently selected
181 readonly attribute nsISimpleEnumerator files
;
184 * Get the DOM File or the DOM Directory
186 * @return Returns the file or directory currently selected DOM object.
188 readonly attribute nsISupports domFileOrDirectory
;
191 * Get the enumerator for the selected files or directories
192 * only works in the modeOpenMultiple mode
194 * @return Returns the files/directories currently selected as DOM object.
196 readonly attribute nsISimpleEnumerator domFileOrDirectoryEnumerator
;
199 * Controls whether the chosen file(s) should be added to the system's recent
200 * documents list. This attribute will be ignored if the system has no "Recent
201 * Docs" concept, or if the application is in private browsing mode (in which
202 * case the file will not be added). Defaults to true.
204 attribute
boolean addToRecentDocs
;
207 * Opens the file dialog asynchrounously.
208 * The passed in object's done method will be called upon completion.
210 void open
(in nsIFilePickerShownCallback aFilePickerShownCallback
);
213 * Closes the file dialog if open.
218 * The picker's mode, as set by the 'mode' argument passed to init()
219 * (one of the modeOpen et. al. constants specified above).
221 readonly attribute nsIFilePicker_Mode mode
;
224 * If set to non-empty string, the nsIFilePicker implementation
225 * may use okButtonLabel as the label for the button the user uses to accept
228 attribute AString okButtonLabel
;
231 * Implementation of HTMLInputElement's `capture` property.
233 * Not used by Firefox Desktop.
235 attribute nsIFilePicker_CaptureTarget capture
;
238 [scriptable
, function
, uuid(0d79adad
-b244
-49A5
-9997-2a8cad93fc44
)]
239 interface nsIFilePickerShownCallback
: nsISupports
242 * Callback which is called when a filepicker is shown and a result
245 * @param aResult One of returnOK, returnCancel, or returnReplace
247 void done
(in nsIFilePicker_ResultCode aResult
);