widget/public/nsITransferable.idl

   1 /* -*- Mode: IDL; 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 Mozilla Communicator.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corp.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Mike Pinkerton
  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 #include "nsISupportsArray.idl"
  42 #include "nsIFormatConverter.idl"
  43
  44
  45 %{ C++
  46
  47 // these probably shouldn't live here, but in some central repository shared
  48 // by the entire app.
  49 #define kTextMime                   "text/plain"
  50 #define kUnicodeMime                "text/unicode"
  51 #define kMozTextInternal          "text/x-moz-text-internal"  // text data which isn't suppoed to be parsed by other apps.
  52 #define kHTMLMime                   "text/html"
  53 #define kAOLMailMime                "AOLMAIL"
  54 #define kPNGImageMime               "image/png"
  55 #define kJPEGImageMime              "image/jpg"
  56 #define kGIFImageMime               "image/gif"
  57 #define kFileMime                   "application/x-moz-file"
  58
  59 #define kURLMime                    "text/x-moz-url"        // data contains url\ntitle
  60 #define kURLDataMime                "text/x-moz-url-data"   // data contains url only
  61 #define kURLDescriptionMime         "text/x-moz-url-desc"   // data contains description
  62 #define kURLPrivateMime             "text/x-moz-url-priv"   // same as kURLDataMime but for private uses
  63 #define kNativeImageMime            "application/x-moz-nativeimage"
  64 #define kNativeHTMLMime             "application/x-moz-nativehtml"
  65
  66 // the source URL for a file promise
  67 #define kFilePromiseURLMime         "application/x-moz-file-promise-url"
  68 // the destination filename for a file promise
  69 #define kFilePromiseDestFilename    "application/x-moz-file-promise-dest-filename"
  70 // a dataless flavor used to interact with the OS during file drags
  71 #define kFilePromiseMime            "application/x-moz-file-promise"
  72 // a synthetic flavor, put into the transferable once we know the destination directory of a file drag
  73 #define kFilePromiseDirectoryMime   "application/x-moz-file-promise-dir"
  74
  75 %}
  76
  77
  78 /**
  79   * nsIFlavorDataProvider allows a flavor to 'promise' data later,
  80   * supplying the data lazily.
  81   *
  82   * To use it, call setTransferData, passing the flavor string,
  83   * a nsIFlavorDataProvider QI'd to nsISupports, and a data size of 0.
  84   *
  85   * When someone calls getTransferData later, if the data size is
  86   * stored as 0, the nsISupports will be QI'd to nsIFlavorDataProvider,
  87   * and its getFlavorData called.
  88   *
  89   */
  90 interface nsITransferable;
  91
  92 [scriptable, uuid(7E225E5F-711C-11D7-9FAE-000393636592)]
  93 interface nsIFlavorDataProvider : nsISupports
  94 {
  95
  96   /**
  97     * Retrieve the data from this data provider.
  98     *
  99     * @param  aTransferable (in parameter) the transferable we're being called for.
 100     * @param  aFlavor (in parameter) the flavor of data to retrieve
 101     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
 102     * @param  aDataLen the length of the data
 103     */
 104   void getFlavorData(in nsITransferable aTransferable, in string aFlavor, out nsISupports aData, out unsigned long aDataLen);
 105 };
 106
 107
 108 [scriptable, uuid(8B5314BC-DB01-11d2-96CE-0060B0FB9956)]
 109 interface nsITransferable : nsISupports
 110 {
 111   const long kFlavorHasDataProvider = 0;
 112
 113   /**
 114     * Computes a list of flavors (mime types as nsISupportsCString) that the transferable
 115     * can export, either through intrinsic knowledge or output data converters.
 116     *
 117     * @param  aDataFlavorList fills list with supported flavors. This is a copy of
 118     *          the internal list, so it may be edited w/out affecting the transferable.
 119     */
 120   nsISupportsArray flavorsTransferableCanExport ( ) ;
 121
 122   /**
 123     * Given a flavor retrieve the data.
 124     *
 125     * @param  aFlavor (in parameter) the flavor of data to retrieve
 126     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
 127     * @param  aDataLen the length of the data
 128     */
 129   void getTransferData ( in string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ;
 130
 131   /**
 132     * Returns the best flavor in the transferable, given those that have
 133     * been added to it with |AddFlavor()|
 134     *
 135     * @param  aFlavor (out parameter) the flavor of data that was retrieved
 136     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
 137     * @param  aDataLen the length of the data
 138     */
 139   void getAnyTransferData ( out string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ;
 140
 141   /**
 142     * Returns true if the data is large.
 143     */
 144   boolean isLargeDataSet ( ) ;
 145
 146
 147     ///////////////////////////////
 148     // Setter part of interface
 149     ///////////////////////////////
 150
 151   /**
 152     * Computes a list of flavors (mime types as nsISupportsCString) that the transferable can
 153     * accept into it, either through intrinsic knowledge or input data converters.
 154     *
 155     * @param  outFlavorList fills list with supported flavors. This is a copy of
 156     *          the internal list, so it may be edited w/out affecting the transferable.
 157     */
 158   nsISupportsArray flavorsTransferableCanImport ( ) ;
 159
 160   /**
 161     * Sets the data in the transferable with the specified flavor. The transferable
 162     * will maintain its own copy the data, so it is not necessary to do that beforehand.
 163     *
 164     * @param  aFlavor the flavor of data that is being set
 165     * @param  aData the data, either some variant of class in nsISupportsPrimitives.idl,
 166     *         an nsIFile, or an nsIFlavorDataProvider (see above)
 167     * @param  aDataLen the length of the data, or 0 if passing a nsIFlavorDataProvider
 168     */
 169   void setTransferData ( in string aFlavor, in nsISupports aData, in unsigned long aDataLen ) ;
 170
 171   /**
 172     * Add the data flavor, indicating that this transferable
 173     * can receive this type of flavor
 174     *
 175     * @param  aDataFlavor a new data flavor to handle
 176     */
 177   void addDataFlavor ( in string aDataFlavor ) ;
 178
 179   /**
 180     * Removes the data flavor matching the given one (string compare) and the data
 181     * that goes along with it.
 182     *
 183     * @param  aDataFlavor a data flavor to remove
 184     */
 185   void removeDataFlavor ( in string aDataFlavor ) ;
 186
 187   attribute nsIFormatConverter converter;
 188
 189 };
 190