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