widget/nsIFilePicker.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is the Mozilla browser.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Stuart Parmenter <pavlov@netscape.com>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41
  42 interface nsILocalFile;
  43 interface nsIURI;
  44 interface nsIDOMWindow;
  45 interface nsISimpleEnumerator;
  46
  47 [scriptable, uuid(f2c0e216-5d07-4df4-bbcb-37683077ae7e)]
  48 interface nsIFilePicker : nsISupports
  49 {
  50   const short modeOpen        = 0;              // Load a file or directory
  51   const short modeSave        = 1;              // Save a file or directory
  52   const short modeGetFolder   = 2;              // Select a folder/directory
  53   const short modeOpenMultiple= 3;              // Load multiple files
  54
  55   const short returnOK        = 0;              // User hit Ok, process selection
  56   const short returnCancel    = 1;              // User hit cancel, ignore selection
  57   const short returnReplace   = 2;              // User acknowledged file already exists so ok to replace, process selection
  58
  59   const long filterAll        = 0x001;          // *.*
  60   const long filterHTML       = 0x002;          // *.html; *.htm
  61   const long filterText       = 0x004;          // *.txt
  62   const long filterImages     = 0x008;          // *.jpe; *.jpg; *.jpeg; *.gif;
  63                                                 // *.png; *.bmp; *.ico; *.svg;
  64                                                 // *.svgz; *.tif; *.tiff; *.ai;
  65                                                 // *.drw; *.pct; *.psp; *.xcf;
  66                                                 // *.psd; *.raw
  67   const long filterXML        = 0x010;          // *.xml
  68   const long filterXUL        = 0x020;          // *.xul
  69   const long filterApps       = 0x040;          // Applications (per-platform implementation)
  70   const long filterAllowURLs  = 0x080;          // Allow URLs
  71   const long filterAudio      = 0x100;          // *.aac; *.aif; *.flac; *.iff;
  72                                                 // *.m4a; *.m4b; *.mid; *.midi;
  73                                                 // *.mp3; *.mpa; *.mpc; *.oga;
  74                                                 // *.ogg; *.ra; *.ram; *.snd;
  75                                                 // *.wav; *.wma
  76   const long filterVideo      = 0x200;          // *.avi; *.divx; *.flv; *.m4v;
  77                                                 // *.mkv; *.mov; *.mp4; *.mpeg;
  78                                                 // *.mpg; *.ogm; *.ogv; *.ogx;
  79                                                 // *.rm; *.rmvb; *.smil; *.webm;
  80                                                 // *.wmv; *.xvid
  81
  82  /**
  83   * Initialize the file picker widget.  The file picker is not valid until this
  84   * method is called.
  85   *
  86   * @param      parent   nsIDOMWindow parent.  This dialog will be dependent
  87   *                      on this parent. parent must be non-null.
  88   * @param      title    The title for the file widget
  89   * @param      mode     load, save, or get folder
  90   *
  91   */
  92   void init(in nsIDOMWindow parent, in AString title, in short mode);
  93
  94  /**
  95   * Append to the  filter list with things from the predefined list
  96   *
  97   * @param      filters  mask of filters i.e. (filterAll | filterHTML)
  98   *
  99   */
 100   void appendFilters(in long filterMask);
 101
 102  /**
 103   * Add a filter
 104   *
 105   * @param      title    name of the filter
 106   * @param      filter   extensions to filter -- semicolon and space separated
 107   *
 108   */
 109   void appendFilter(in AString title,
 110                     in AString filter);
 111
 112  /**
 113   * The filename that should be suggested to the user as a default. This should
 114   * include the extension.
 115   *
 116   * @throws NS_ERROR_FAILURE on attempts to get
 117   */
 118   attribute AString defaultString;
 119
 120  /**
 121   * The extension that should be associated with files of the type we
 122   * want to work with.  On some platforms, this extension will be
 123   * automatically appended to filenames the user enters, if needed.
 124   */
 125   attribute AString defaultExtension;
 126
 127  /**
 128   * The filter which is currently selected in the File Picker dialog
 129   *
 130   * @return Returns the index (0 based) of the selected filter in the filter list.
 131   */
 132   attribute long filterIndex;
 133
 134  /**
 135   * Set the directory that the file open/save dialog initially displays
 136   *
 137   * @param      displayDirectory  the name of the directory
 138   *
 139   */
 140   attribute nsILocalFile displayDirectory;
 141
 142
 143  /**
 144   * Get the nsILocalFile for the file or directory.
 145   *
 146   * @return Returns the file currently selected
 147   */
 148   readonly attribute nsILocalFile file;
 149
 150  /**
 151   * Get the nsIURI for the file or directory.
 152   *
 153   * @return Returns the file currently selected
 154   */
 155   readonly attribute nsIURI fileURL;
 156
 157  /**
 158   * Get the enumerator for the selected files
 159   * only works in the modeOpenMultiple mode
 160   *
 161   * @return Returns the files currently selected
 162   */
 163   readonly attribute nsISimpleEnumerator files;
 164
 165  /**
 166   * Controls whether the chosen file(s) should be added to the system's recent
 167   * documents list. This attribute will be ignored if the system has no "Recent
 168   * Docs" concept, or if the application is in private browsing mode (in which
 169   * case the file will not be added). Defaults to true.
 170   */
 171   attribute boolean addToRecentDocs;
 172
 173  /**
 174   * Show File Dialog. The dialog is displayed modally.
 175   *
 176   * @return returnOK if the user selects OK, returnCancel if the user selects cancel
 177   *
 178   */
 179   short show();
 180 };