widget/nsIFilePicker.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   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/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface nsIFile;
  10 interface nsIURI;
  11 interface mozIDOMWindowProxy;
  12 interface nsISimpleEnumerator;
  13
  14 // Declared in this file, below.
  15 interface nsIFilePickerShownCallback;
  16
  17 [scriptable, uuid(9285b984-02d3-46b4-9514-7da8c471a747)]
  18 interface nsIFilePicker : nsISupports
  19 {
  20   cenum Mode: 16 {
  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
  25   };
  26
  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
  31   };
  32
  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; *.heic
  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;
  49                                                 // *.wav; *.wma
  50   const long filterVideo      = 0x200;          // *.avi; *.divx; *.flv; *.m4v;
  51                                                 // *.mkv; *.mov; *.mp4; *.mpeg;
  52                                                 // *.mpg; *.ogm; *.ogv; *.ogx;
  53                                                 // *.rm; *.rmvb; *.smil; *.webm;
  54                                                 // *.wmv; *.xvid
  55   const long filterPDF        = 0x400;          // *.pdf;
  56
  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.
  62   };
  63
  64  /**
  65   * Initialize the file picker widget.  The file picker is not valid until this
  66   * method is called.
  67   *
  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
  72   *
  73   */
  74   void init(in mozIDOMWindowProxy parent, in AString title, in nsIFilePicker_Mode mode);
  75
  76   /**
  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
  80    * is supported.
  81    *
  82    * @param mode
  83    * @return Promise<boolean>
  84    */
  85   [implicit_jscontext]
  86   Promise isModeSupported(in nsIFilePicker_Mode mode);
  87
  88  /**
  89   * Append to the  filter list with things from the predefined list
  90   *
  91   * @param      filters  mask of filters i.e. (filterAll | filterHTML)
  92   *
  93   */
  94   void appendFilters(in long filterMask);
  95
  96  /**
  97   * Add a filter
  98   *
  99   * @param      title    name of the filter
 100   * @param      filter   extensions to filter -- semicolon and space separated
 101   *
 102   */
 103   void appendFilter(in AString title,
 104                     in AString filter);
 105
 106   /**
 107    * Add a raw filter (eg, add a MIME type without transforming it to a list of
 108    * extensions).
 109    *
 110    * @param     filter   a filter taken directly from the accept attribute
 111    *                     without processing
 112    *
 113    */
 114   void appendRawFilter(in AString filter);
 115
 116  /**
 117   * The filename that should be suggested to the user as a default. This should
 118   * include the extension.
 119   *
 120   * @throws NS_ERROR_FAILURE on attempts to get
 121   */
 122   attribute AString defaultString;
 123
 124  /**
 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.
 128   */
 129   attribute AString defaultExtension;
 130
 131  /**
 132   * The filter which is currently selected in the File Picker dialog
 133   *
 134   * @return Returns the index (0 based) of the selected filter in the filter list.
 135   */
 136   attribute long filterIndex;
 137
 138  /**
 139   * Set the directory that the file open/save dialog initially displays
 140   * Note that, if displaySpecialDirectory has been already set, this value will
 141   * be ignored.
 142   *
 143   * @param      displayDirectory  the name of the directory
 144   *
 145   */
 146   attribute nsIFile displayDirectory;
 147
 148  /**
 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
 152   * ignored.
 153   *
 154   * @param      displaySpecialDirectory  the name of the special directory
 155   *
 156   */
 157   attribute AString displaySpecialDirectory;
 158
 159
 160  /**
 161   * Get the nsIFile for the file or directory. A different file object
 162   * may be returned by each invocation.
 163   *
 164   * @return Returns the file currently selected
 165   */
 166   readonly attribute nsIFile file;
 167
 168  /**
 169   * Get the nsIURI for the file or directory.
 170   *
 171   * @return Returns the file currently selected
 172   */
 173   readonly attribute nsIURI fileURL;
 174
 175  /**
 176   * Get the enumerator for the selected files
 177   * only works in the modeOpenMultiple mode
 178   *
 179   * @return Returns the files currently selected
 180   */
 181   readonly attribute nsISimpleEnumerator files;
 182
 183  /**
 184   * Get the DOM File or the DOM Directory
 185   *
 186   * @return Returns the file or directory currently selected DOM object.
 187   */
 188   readonly attribute nsISupports domFileOrDirectory;
 189
 190  /**
 191   * Get the enumerator for the selected files or directories
 192   * only works in the modeOpenMultiple mode
 193   *
 194   * @return Returns the files/directories currently selected as DOM object.
 195   */
 196   readonly attribute nsISimpleEnumerator domFileOrDirectoryEnumerator;
 197
 198  /**
 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.
 203   */
 204   attribute boolean addToRecentDocs;
 205
 206  /**
 207   * Opens the file dialog asynchrounously.
 208   * The passed in object's done method will be called upon completion.
 209   */
 210   void open(in nsIFilePickerShownCallback aFilePickerShownCallback);
 211
 212  /**
 213   * Closes the file dialog if open.
 214   */
 215   void close();
 216
 217  /**
 218   * The picker's mode, as set by the 'mode' argument passed to init()
 219   * (one of the modeOpen et. al. constants specified above).
 220   */
 221   readonly attribute nsIFilePicker_Mode mode;
 222
 223   /**
 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
 226    * file selection.
 227    */
 228   attribute AString okButtonLabel;
 229
 230   /**
 231    * Implementation of HTMLInputElement's `capture` property.
 232    *
 233    * Not used by Firefox Desktop.
 234    */
 235   attribute nsIFilePicker_CaptureTarget capture;
 236 };
 237
 238 [scriptable, function, uuid(0d79adad-b244-49A5-9997-2a8cad93fc44)]
 239 interface nsIFilePickerShownCallback : nsISupports
 240 {
 241  /**
 242   * Callback which is called when a filepicker is shown and a result
 243   * is returned.
 244   *
 245   * @param aResult One of returnOK, returnCancel, or returnReplace
 246   */
 247   void done(in nsIFilePicker_ResultCode aResult);
 248 };