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
  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   * Append to the  filter list with things from the predefined list
  78   *
  79   * @param      filters  mask of filters i.e. (filterAll | filterHTML)
  80   *
  81   */
  82   void appendFilters(in long filterMask);
  83
  84  /**
  85   * Add a filter
  86   *
  87   * @param      title    name of the filter
  88   * @param      filter   extensions to filter -- semicolon and space separated
  89   *
  90   */
  91   void appendFilter(in AString title,
  92                     in AString filter);
  93
  94   /**
  95    * Add a raw filter (eg, add a MIME type without transforming it to a list of
  96    * extensions).
  97    *
  98    * @param     filter   a filter taken directly from the accept attribute
  99    *                     without processing
 100    *
 101    */
 102   void appendRawFilter(in AString filter);
 103
 104  /**
 105   * The filename that should be suggested to the user as a default. This should
 106   * include the extension.
 107   *
 108   * @throws NS_ERROR_FAILURE on attempts to get
 109   */
 110   attribute AString defaultString;
 111
 112  /**
 113   * The extension that should be associated with files of the type we
 114   * want to work with.  On some platforms, this extension will be
 115   * automatically appended to filenames the user enters, if needed.
 116   */
 117   attribute AString defaultExtension;
 118
 119  /**
 120   * The filter which is currently selected in the File Picker dialog
 121   *
 122   * @return Returns the index (0 based) of the selected filter in the filter list.
 123   */
 124   attribute long filterIndex;
 125
 126  /**
 127   * Set the directory that the file open/save dialog initially displays
 128   * Note that, if displaySpecialDirectory has been already set, this value will
 129   * be ignored.
 130   *
 131   * @param      displayDirectory  the name of the directory
 132   *
 133   */
 134   attribute nsIFile displayDirectory;
 135
 136  /**
 137   * Set the directory that the file open/save dialog initially displays using
 138   * one of the special name as such as 'Desk', 'TmpD', and so on.
 139   * Note that, if displayDirectory has been already set, this value will be
 140   * ignored.
 141   *
 142   * @param      displaySpecialDirectory  the name of the special directory
 143   *
 144   */
 145   attribute AString displaySpecialDirectory;
 146
 147
 148  /**
 149   * Get the nsIFile for the file or directory. A different file object
 150   * may be returned by each invocation.
 151   *
 152   * @return Returns the file currently selected
 153   */
 154   readonly attribute nsIFile file;
 155
 156  /**
 157   * Get the nsIURI for the file or directory.
 158   *
 159   * @return Returns the file currently selected
 160   */
 161   readonly attribute nsIURI fileURL;
 162
 163  /**
 164   * Get the enumerator for the selected files
 165   * only works in the modeOpenMultiple mode
 166   *
 167   * @return Returns the files currently selected
 168   */
 169   readonly attribute nsISimpleEnumerator files;
 170
 171  /**
 172   * Get the DOM File or the DOM Directory
 173   *
 174   * @return Returns the file or directory currently selected DOM object.
 175   */
 176   readonly attribute nsISupports domFileOrDirectory;
 177
 178  /**
 179   * Get the enumerator for the selected files or directories
 180   * only works in the modeOpenMultiple mode
 181   *
 182   * @return Returns the files/directories currently selected as DOM object.
 183   */
 184   readonly attribute nsISimpleEnumerator domFileOrDirectoryEnumerator;
 185
 186  /**
 187   * Controls whether the chosen file(s) should be added to the system's recent
 188   * documents list. This attribute will be ignored if the system has no "Recent
 189   * Docs" concept, or if the application is in private browsing mode (in which
 190   * case the file will not be added). Defaults to true.
 191   */
 192   attribute boolean addToRecentDocs;
 193
 194  /**
 195   * Opens the file dialog asynchrounously.
 196   * The passed in object's done method will be called upon completion.
 197   */
 198   void open(in nsIFilePickerShownCallback aFilePickerShownCallback);
 199
 200  /**
 201   * The picker's mode, as set by the 'mode' argument passed to init()
 202   * (one of the modeOpen et. al. constants specified above).
 203   */
 204   readonly attribute nsIFilePicker_Mode mode;
 205
 206   /**
 207    * If set to non-empty string, the nsIFilePicker implementation
 208    * may use okButtonLabel as the label for the button the user uses to accept
 209    * file selection.
 210    */
 211   attribute AString okButtonLabel;
 212
 213   /**
 214    * Implementation of HTMLInputElement's `capture` property.
 215    *
 216    * Not used by Firefox Desktop.
 217    */
 218   attribute nsIFilePicker_CaptureTarget capture;
 219 };
 220
 221 [scriptable, function, uuid(0d79adad-b244-49A5-9997-2a8cad93fc44)]
 222 interface nsIFilePickerShownCallback : nsISupports
 223 {
 224  /**
 225   * Callback which is called when a filepicker is shown and a result
 226   * is returned.
 227   *
 228   * @param aResult One of returnOK, returnCancel, or returnReplace
 229   */
 230   void done(in nsIFilePicker_ResultCode aResult);
 231 };