summaryrefslogtreecommitdiffstats
path: root/widget/nsIFilePicker.idl
blob: e9bdedfd4271cb6b4c15fbc34af58b0717109037 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIFile;
interface nsIURI;
interface mozIDOMWindowProxy;
interface nsISimpleEnumerator;
webidl BrowsingContext;

// Declared in this file, below.
interface nsIFilePickerShownCallback;

[scriptable, uuid(9285b984-02d3-46b4-9514-7da8c471a747)]
interface nsIFilePicker : nsISupports
{
  cenum Mode: 16 {
    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
  };

  cenum ResultCode: 16 {
    returnOK        = 0,                        // User hit Ok, process selection
    returnCancel    = 1,                        // User hit cancel, ignore selection
    returnReplace   = 2,                        // User acknowledged file already exists so ok to replace, process selection
  };

  const long filterAll        = 0x001;          // *.*
  const long filterHTML       = 0x002;          // *.html; *.htm
  const long filterText       = 0x004;          // *.txt
  const long filterImages     = 0x008;          // *.jpe; *.jpg; *.jpeg; *.gif;
                                                // *.png; *.bmp; *.ico; *.svg;
                                                // *.svgz; *.tif; *.tiff; *.ai;
                                                // *.drw; *.pct; *.psp; *.xcf;
                                                // *.psd; *.raw; *.webp; *.heic
  const long filterXML        = 0x010;          // *.xml
  const long filterXUL        = 0x020;          // *.xul
  const long filterApps       = 0x040;          // Applications (per-platform implementation)
  const long filterAllowURLs  = 0x080;          // Allow URLs
  const long filterAudio      = 0x100;          // *.aac; *.aif; *.flac; *.iff;
                                                // *.m4a; *.m4b; *.mid; *.midi;
                                                // *.mp3; *.mpa; *.mpc; *.oga;
                                                // *.ogg; *.ra; *.ram; *.snd;
                                                // *.wav; *.wma
  const long filterVideo      = 0x200;          // *.avi; *.divx; *.flv; *.m4v;
                                                // *.mkv; *.mov; *.mp4; *.mpeg;
                                                // *.mpg; *.ogm; *.ogv; *.ogx;
                                                // *.rm; *.rmvb; *.smil; *.webm;
                                                // *.wmv; *.xvid
  const long filterPDF        = 0x400;          // *.pdf;

  cenum CaptureTarget: 8 {
    captureNone     = 0,                        // No capture target specified.
    captureDefault  = 1,                        // Missing/invalid value default.
    captureUser     = 2,                        // "user" capture target specified.
    captureEnv      = 3,                        // "environment" capture target specified.
  };

 /**
  * Initialize the file picker widget.  The file picker is not valid until this
  * method is called.
  *
  * @param      parent   mozIDOMWindow parent.  This dialog will be dependent
  *                      on this parent. parent must be non-null.
  * @param      title    The title for the file widget
  * @param      mode     load, save, or get folder
  * @param      browsingContext [optional]
  *             The context in which the file picker is being shown. This is
  *             used for content analysis and can be omitted if chrome is
  *             showing the file picker.
  */
  void init(in mozIDOMWindowProxy parent,
            in AString title,
            in nsIFilePicker_Mode mode,
            [optional] in BrowsingContext browsingContext);

  /**
   * Returns a Promise that resolves to true if the passed nsIFilePicker mode
   * is supported on the current platform, and false otherwise. The Promise may
   * reject if something unexpected occurs while trying to determine if the mode
   * is supported.
   *
   * @param mode
   * @return Promise<boolean>
   */
  [implicit_jscontext]
  Promise isModeSupported(in nsIFilePicker_Mode mode);

 /**
  * Append to the  filter list with things from the predefined list
  *
  * @param      filters  mask of filters i.e. (filterAll | filterHTML)
  *
  */
  void appendFilters(in long filterMask);

 /**
  * Add a filter
  *
  * @param      title    name of the filter
  * @param      filter   extensions to filter -- semicolon and space separated
  *
  */
  void appendFilter(in AString title,
                    in AString filter);

  /**
   * Add a raw filter (eg, add a MIME type without transforming it to a list of
   * extensions).
   *
   * @param     filter   a filter taken directly from the accept attribute
   *                     without processing
   *
   */
  void appendRawFilter(in AString filter);

 /**
  * The filename that should be suggested to the user as a default. This should
  * include the extension.
  *
  * @throws NS_ERROR_FAILURE on attempts to get
  */
  attribute AString defaultString;

 /**
  * The extension that should be associated with files of the type we
  * want to work with.  On some platforms, this extension will be
  * automatically appended to filenames the user enters, if needed.
  */
  attribute AString defaultExtension;

 /**
  * The filter which is currently selected in the File Picker dialog
  *
  * @return Returns the index (0 based) of the selected filter in the filter list.
  */
  attribute long filterIndex;

 /**
  * Set the directory that the file open/save dialog initially displays
  * Note that, if displaySpecialDirectory has been already set, this value will
  * be ignored.
  *
  * @param      displayDirectory  the name of the directory
  *
  */
  attribute nsIFile displayDirectory;

 /**
  * Set the directory that the file open/save dialog initially displays using
  * one of the special name as such as 'Desk', 'TmpD', and so on.
  * Note that, if displayDirectory has been already set, this value will be
  * ignored.
  *
  * @param      displaySpecialDirectory  the name of the special directory
  *
  */
  attribute AString displaySpecialDirectory;


 /**
  * Get the nsIFile for the file or directory. A different file object
  * may be returned by each invocation.
  *
  * @return Returns the file currently selected
  */
  readonly attribute nsIFile file;

 /**
  * Get the nsIURI for the file or directory.
  *
  * @return Returns the file currently selected
  */
  readonly attribute nsIURI fileURL;

 /**
  * Get the enumerator for the selected files
  * only works in the modeOpenMultiple mode
  *
  * @return Returns the files currently selected
  */
  readonly attribute nsISimpleEnumerator files;

 /**
  * Get the DOM File or the DOM Directory
  *
  * @return Returns the file or directory currently selected DOM object.
  */
  readonly attribute nsISupports domFileOrDirectory;

 /**
  * Get the enumerator for the selected files or directories
  * only works in the modeOpenMultiple mode
  *
  * @return Returns the files/directories currently selected as DOM object.
  */
  readonly attribute nsISimpleEnumerator domFileOrDirectoryEnumerator;

 /**
  * Controls whether the chosen file(s) should be added to the system's recent
  * documents list. This attribute will be ignored if the system has no "Recent
  * Docs" concept, or if the application is in private browsing mode (in which
  * case the file will not be added). Defaults to true.
  */
  attribute boolean addToRecentDocs;

 /**
  * Opens the file dialog asynchrounously.
  * The passed in object's done method will be called upon completion.
  */
  void open(in nsIFilePickerShownCallback aFilePickerShownCallback);

 /**
  * Closes the file dialog if open.
  */
  void close();

 /**
  * The picker's mode, as set by the 'mode' argument passed to init()
  * (one of the modeOpen et. al. constants specified above).
  */
  readonly attribute nsIFilePicker_Mode mode;

  /**
   * If set to non-empty string, the nsIFilePicker implementation
   * may use okButtonLabel as the label for the button the user uses to accept
   * file selection.
   */
  attribute AString okButtonLabel;

  /**
   * Implementation of HTMLInputElement's `capture` property.
   *
   * Not used by Firefox Desktop.
   */
  attribute nsIFilePicker_CaptureTarget capture;
};

[scriptable, function, uuid(0d79adad-b244-49A5-9997-2a8cad93fc44)]
interface nsIFilePickerShownCallback : nsISupports
{
 /**
  * Callback which is called when a filepicker is shown and a result
  * is returned.
  *
  * @param aResult One of returnOK, returnCancel, or returnReplace
  */
  void done(in nsIFilePicker_ResultCode aResult);
};