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 webidl BrowsingContext;
  14
  15 // Declared in this file, below.
  16 interface nsIFilePickerShownCallback;
  17
  18 [scriptable, uuid(9285b984-02d3-46b4-9514-7da8c471a747)]
  19 interface nsIFilePicker : nsISupports
  20 {
  21   cenum Mode: 16 {
  22     modeOpen         = 0,                        // Load a file or directory
  23     modeSave         = 1,                        // Save a file or directory
  24     modeGetFolder    = 2,                        // Select a folder/directory
  25     modeOpenMultiple = 3,                        // Load multiple files
  26   };
  27
  28   cenum ResultCode: 16 {
  29     returnOK        = 0,                        // User hit Ok, process selection
  30     returnCancel    = 1,                        // User hit cancel, ignore selection
  31     returnReplace   = 2,                        // User acknowledged file already exists so ok to replace, process selection
  32   };
  33
  34   const long filterAll        = 0x001;          // *.*
  35   const long filterHTML       = 0x002;          // *.html; *.htm
  36   const long filterText       = 0x004;          // *.txt
  37   const long filterImages     = 0x008;          // *.jpe; *.jpg; *.jpeg; *.gif;
  38                                                 // *.png; *.bmp; *.ico; *.svg;
  39                                                 // *.svgz; *.tif; *.tiff; *.ai;
  40                                                 // *.drw; *.pct; *.psp; *.xcf;
  41                                                 // *.psd; *.raw; *.webp; *.heic
  42   const long filterXML        = 0x010;          // *.xml
  43   const long filterXUL        = 0x020;          // *.xul
  44   const long filterApps       = 0x040;          // Applications (per-platform implementation)
  45   const long filterAllowURLs  = 0x080;          // Allow URLs
  46   const long filterAudio      = 0x100;          // *.aac; *.aif; *.flac; *.iff;
  47                                                 // *.m4a; *.m4b; *.mid; *.midi;
  48                                                 // *.mp3; *.mpa; *.mpc; *.oga;
  49                                                 // *.ogg; *.ra; *.ram; *.snd;
  50                                                 // *.wav; *.wma
  51   const long filterVideo      = 0x200;          // *.avi; *.divx; *.flv; *.m4v;
  52                                                 // *.mkv; *.mov; *.mp4; *.mpeg;
  53                                                 // *.mpg; *.ogm; *.ogv; *.ogx;
  54                                                 // *.rm; *.rmvb; *.smil; *.webm;
  55                                                 // *.wmv; *.xvid
  56   const long filterPDF        = 0x400;          // *.pdf;
  57
  58   cenum CaptureTarget: 8 {
  59     captureNone     = 0,                        // No capture target specified.
  60     captureDefault  = 1,                        // Missing/invalid value default.
  61     captureUser     = 2,                        // "user" capture target specified.
  62     captureEnv      = 3,                        // "environment" capture target specified.
  63   };
  64
  65  /**
  66   * Initialize the file picker widget.  The file picker is not valid until this
  67   * method is called.
  68   *
  69   * @param      browsingContext   The context in which the file picker is being
  70   *                               shown, must be non-null.
  71   * @param      title             The title for the file widget
  72   * @param      mode              load, save, or get folder
  73   *
  74   */
  75   void init(in BrowsingContext browsingContext, in AString title, in nsIFilePicker_Mode mode);
  76
  77   /**
  78    * Returns a Promise that resolves to true if the passed nsIFilePicker mode
  79    * is supported on the current platform, and false otherwise. The Promise may
  80    * reject if something unexpected occurs while trying to determine if the mode
  81    * is supported.
  82    *
  83    * @param mode
  84    * @return Promise<boolean>
  85    */
  86   [implicit_jscontext]
  87   Promise isModeSupported(in nsIFilePicker_Mode mode);
  88
  89  /**
  90   * Append to the  filter list with things from the predefined list
  91   *
  92   * @param      filters  mask of filters i.e. (filterAll | filterHTML)
  93   *
  94   */
  95   void appendFilters(in long filterMask);
  96
  97  /**
  98   * Add a filter
  99   *
 100   * @param      title    name of the filter
 101   * @param      filter   extensions to filter -- semicolon and space separated
 102   *
 103   */
 104   void appendFilter(in AString title,
 105                     in AString filter);
 106
 107   /**
 108    * Add a raw filter (eg, add a MIME type without transforming it to a list of
 109    * extensions).
 110    *
 111    * @param     filter   a filter taken directly from the accept attribute
 112    *                     without processing
 113    *
 114    */
 115   void appendRawFilter(in AString filter);
 116
 117  /**
 118   * The filename that should be suggested to the user as a default. This should
 119   * include the extension.
 120   *
 121   * @throws NS_ERROR_FAILURE on attempts to get
 122   */
 123   attribute AString defaultString;
 124
 125  /**
 126   * The extension that should be associated with files of the type we
 127   * want to work with.  On some platforms, this extension will be
 128   * automatically appended to filenames the user enters, if needed.
 129   */
 130   attribute AString defaultExtension;
 131
 132  /**
 133   * The filter which is currently selected in the File Picker dialog
 134   *
 135   * @return Returns the index (0 based) of the selected filter in the filter list.
 136   */
 137   attribute long filterIndex;
 138
 139  /**
 140   * Set the directory that the file open/save dialog initially displays
 141   * Note that, if displaySpecialDirectory has been already set, this value will
 142   * be ignored.
 143   *
 144   * @param      displayDirectory  the name of the directory
 145   *
 146   */
 147   attribute nsIFile displayDirectory;
 148
 149  /**
 150   * Set the directory that the file open/save dialog initially displays using
 151   * one of the special name as such as 'Desk', 'TmpD', and so on.
 152   * Note that, if displayDirectory has been already set, this value will be
 153   * ignored.
 154   *
 155   * @param      displaySpecialDirectory  the name of the special directory
 156   *
 157   */
 158   attribute AString displaySpecialDirectory;
 159
 160
 161  /**
 162   * Get the nsIFile for the file or directory. A different file object
 163   * may be returned by each invocation.
 164   *
 165   * @return Returns the file currently selected
 166   */
 167   readonly attribute nsIFile file;
 168
 169  /**
 170   * Get the nsIURI for the file or directory.
 171   *
 172   * @return Returns the file currently selected
 173   */
 174   readonly attribute nsIURI fileURL;
 175
 176  /**
 177   * Get the enumerator for the selected files
 178   * only works in the modeOpenMultiple mode
 179   *
 180   * @return Returns the files currently selected
 181   */
 182   readonly attribute nsISimpleEnumerator files;
 183
 184  /**
 185   * Get the DOM File or the DOM Directory
 186   *
 187   * @return Returns the file or directory currently selected DOM object.
 188   */
 189   readonly attribute nsISupports domFileOrDirectory;
 190
 191  /**
 192   * Get the enumerator for the selected files or directories
 193   * only works in the modeOpenMultiple mode
 194   *
 195   * @return Returns the files/directories currently selected as DOM object.
 196   */
 197   readonly attribute nsISimpleEnumerator domFileOrDirectoryEnumerator;
 198
 199  /**
 200   * Controls whether the chosen file(s) should be added to the system's recent
 201   * documents list. This attribute will be ignored if the system has no "Recent
 202   * Docs" concept, or if the application is in private browsing mode (in which
 203   * case the file will not be added). Defaults to true.
 204   */
 205   attribute boolean addToRecentDocs;
 206
 207  /**
 208   * Opens the file dialog asynchrounously.
 209   * The passed in object's done method will be called upon completion.
 210   */
 211   void open(in nsIFilePickerShownCallback aFilePickerShownCallback);
 212
 213  /**
 214   * Closes the file dialog if open.
 215   */
 216   void close();
 217
 218  /**
 219   * The picker's mode, as set by the 'mode' argument passed to init()
 220   * (one of the modeOpen et. al. constants specified above).
 221   */
 222   readonly attribute nsIFilePicker_Mode mode;
 223
 224   /**
 225    * If set to non-empty string, the nsIFilePicker implementation
 226    * may use okButtonLabel as the label for the button the user uses to accept
 227    * file selection.
 228    */
 229   attribute AString okButtonLabel;
 230
 231   /**
 232    * Implementation of HTMLInputElement's `capture` property.
 233    *
 234    * Not used by Firefox Desktop.
 235    */
 236   attribute nsIFilePicker_CaptureTarget capture;
 237 };
 238
 239 [scriptable, function, uuid(0d79adad-b244-49A5-9997-2a8cad93fc44)]
 240 interface nsIFilePickerShownCallback : nsISupports
 241 {
 242  /**
 243   * Callback which is called when a filepicker is shown and a result
 244   * is returned.
 245   *
 246   * @param aResult One of returnOK, returnCancel, or returnReplace
 247   */
 248   void done(in nsIFilePicker_ResultCode aResult);
 249 };