widget/public/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(d24ef0aa-d555-4117-84af-9cbbb7406909)]
  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        = 0x01;           // *.*
  60   const long filterHTML       = 0x02;           // *.html; *.htm
  61   const long filterText       = 0x04;           // *.txt
  62   const long filterImages     = 0x08;           // *.png; *.gif; *.jpg; *.jpeg
  63   const long filterXML        = 0x10;           // *.xml
  64   const long filterXUL        = 0x20;           // *.xul
  65   const long filterApps       = 0x40;           // Applications (per-platform implementation)
  66   const long filterAllowURLs  = 0x80;           // Allow URLs
  67
  68  /**
  69   * Initialize the file picker widget.  The file picker is not valid until this
  70   * method is called.
  71   *
  72   * @param      parent   nsIDOMWindow parent.  This dialog will be dependent
  73   *                      on this parent. parent must be non-null.
  74   * @param      title    The title for the file widget
  75   * @param      mode     load, save, or get folder
  76   *
  77   */
  78   void init(in nsIDOMWindow parent, in AString title, in short mode);
  79
  80  /**
  81   * Append to the  filter list with things from the predefined list
  82   *
  83   * @param      filters  mask of filters i.e. (filterAll | filterHTML)
  84   *
  85   */
  86   void appendFilters(in long filterMask);
  87
  88  /**
  89   * Add a filter
  90   *
  91   * @param      title    name of the filter
  92   * @param      filter   extensions to filter -- semicolon and space separated
  93   *
  94   */
  95   void appendFilter(in AString title,
  96                     in AString filter);
  97
  98  /**
  99   * The filename that should be suggested to the user as a default.
 100   *
 101   * @throws NS_ERROR_FAILURE on attempts to get
 102   */
 103   attribute AString defaultString;
 104
 105  /**
 106   * The extension that should be associated with files of the type we
 107   * want to work with.  On some platforms, this extension will be
 108   * automatically appended to filenames the user enters, if needed.
 109   */
 110   attribute AString defaultExtension;
 111
 112  /**
 113   * The filter which is currently selected in the File Picker dialog
 114   *
 115   * @return Returns the index (0 based) of the selected filter in the filter list.
 116   */
 117   attribute long filterIndex;
 118
 119  /**
 120   * Set the directory that the file open/save dialog initially displays
 121   *
 122   * @param      displayDirectory  the name of the directory
 123   *
 124   */
 125   attribute nsILocalFile displayDirectory;
 126
 127
 128  /**
 129   * Get the nsILocalFile for the file or directory.
 130   *
 131   * @return Returns the file currently selected
 132   */
 133   readonly attribute nsILocalFile file;
 134
 135  /**
 136   * Get the nsIURL for the file or directory.
 137   *
 138   * @return Returns the file currently selected
 139   */
 140   readonly attribute nsIURI fileURL;
 141
 142  /**
 143   * Get the enumerator for the selected files
 144   * only works in the modeOpenMultiple mode
 145   *
 146   * @return Returns the files currently selected
 147   */
 148   readonly attribute nsISimpleEnumerator files;
 149
 150  /**
 151   * Show File Dialog. The dialog is displayed modally.
 152   *
 153   * @return returnOK if the user selects OK, returnCancel if the user selects cancel
 154   *
 155   */
 156   short show();
 157 };