widget/nsITransferable.idl

   1 /* -*- Mode: IDL; 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 #include "nsISupportsArray.idl"
   9 #include "nsIFormatConverter.idl"
  10
  11
  12 %{ C++
  13
  14 // these probably shouldn't live here, but in some central repository shared
  15 // by the entire app.
  16 #define kTextMime                   "text/plain"
  17 #define kUnicodeMime                "text/unicode"
  18 #define kMozTextInternal          "text/x-moz-text-internal"  // text data which isn't suppoed to be parsed by other apps.
  19 #define kHTMLMime                   "text/html"
  20 #define kAOLMailMime                "AOLMAIL"
  21 #define kPNGImageMime               "image/png"
  22 #define kJPEGImageMime              "image/jpeg"
  23 #define kJPGImageMime               "image/jpg"
  24 #define kGIFImageMime               "image/gif"
  25 #define kFileMime                   "application/x-moz-file"
  26
  27 #define kURLMime                    "text/x-moz-url"        // data contains url\ntitle
  28 #define kURLDataMime                "text/x-moz-url-data"   // data contains url only
  29 #define kURLDescriptionMime         "text/x-moz-url-desc"   // data contains description
  30 #define kURLPrivateMime             "text/x-moz-url-priv"   // same as kURLDataMime but for private uses
  31 #define kNativeImageMime            "application/x-moz-nativeimage"
  32 #define kNativeHTMLMime             "application/x-moz-nativehtml"
  33
  34 // These are used to indicate the context for a fragment of HTML source, such
  35 // that some parent structure and style can be preserved. kHTMLContext
  36 // contains the serialized ancestor elements, whereas kHTMLInfo are numbers
  37 // identifying where in the context the fragment was from.
  38 #define kHTMLContext   "text/_moz_htmlcontext"
  39 #define kHTMLInfo      "text/_moz_htmlinfo"
  40
  41 // the source URL for a file promise
  42 #define kFilePromiseURLMime         "application/x-moz-file-promise-url"
  43 // the destination filename for a file promise
  44 #define kFilePromiseDestFilename    "application/x-moz-file-promise-dest-filename"
  45 // a dataless flavor used to interact with the OS during file drags
  46 #define kFilePromiseMime            "application/x-moz-file-promise"
  47 // a synthetic flavor, put into the transferable once we know the destination directory of a file drag
  48 #define kFilePromiseDirectoryMime   "application/x-moz-file-promise-dir"
  49
  50 %}
  51
  52
  53 /**
  54   * nsIFlavorDataProvider allows a flavor to 'promise' data later,
  55   * supplying the data lazily.
  56   *
  57   * To use it, call setTransferData, passing the flavor string,
  58   * a nsIFlavorDataProvider QI'd to nsISupports, and a data size of 0.
  59   *
  60   * When someone calls getTransferData later, if the data size is
  61   * stored as 0, the nsISupports will be QI'd to nsIFlavorDataProvider,
  62   * and its getFlavorData called.
  63   *
  64   */
  65 interface nsITransferable;
  66 interface nsILoadContext;
  67
  68 [scriptable, uuid(7E225E5F-711C-11D7-9FAE-000393636592)]
  69 interface nsIFlavorDataProvider : nsISupports
  70 {
  71
  72   /**
  73     * Retrieve the data from this data provider.
  74     *
  75     * @param  aTransferable (in parameter) the transferable we're being called for.
  76     * @param  aFlavor (in parameter) the flavor of data to retrieve
  77     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
  78     * @param  aDataLen the length of the data
  79     */
  80   void getFlavorData(in nsITransferable aTransferable, in string aFlavor, out nsISupports aData, out unsigned long aDataLen);
  81 };
  82
  83
  84 [scriptable, uuid(5a611a60-e5b5-11e1-aff1-0800200c9a66)]
  85 interface nsITransferable : nsISupports
  86 {
  87   const long kFlavorHasDataProvider = 0;
  88
  89   /**
  90    * Initializes a transferable object.  This should be called on all
  91    * transferable objects.  Failure to do so will result in fatal assertions in
  92    * debug builds.
  93    *
  94    * @param aContext the load context associated with the transferable object.
  95    *        This can be set to null if a load context is not available.
  96    */
  97   void init(in nsILoadContext aContext);
  98
  99   /**
 100     * Computes a list of flavors (mime types as nsISupportsCString) that the transferable
 101     * can export, either through intrinsic knowledge or output data converters.
 102     *
 103     * @param  aDataFlavorList fills list with supported flavors. This is a copy of
 104     *          the internal list, so it may be edited w/out affecting the transferable.
 105     */
 106   nsISupportsArray flavorsTransferableCanExport ( ) ;
 107
 108   /**
 109     * Given a flavor retrieve the data.
 110     *
 111     * @param  aFlavor (in parameter) the flavor of data to retrieve
 112     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
 113     * @param  aDataLen the length of the data
 114     */
 115   void getTransferData ( in string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ;
 116
 117   /**
 118     * Returns the best flavor in the transferable, given those that have
 119     * been added to it with |AddFlavor()|
 120     *
 121     * @param  aFlavor (out parameter) the flavor of data that was retrieved
 122     * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
 123     * @param  aDataLen the length of the data
 124     */
 125   void getAnyTransferData ( out string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ;
 126
 127   /**
 128     * Returns true if the data is large.
 129     */
 130   boolean isLargeDataSet ( ) ;
 131
 132
 133     ///////////////////////////////
 134     // Setter part of interface
 135     ///////////////////////////////
 136
 137   /**
 138     * Computes a list of flavors (mime types as nsISupportsCString) that the transferable can
 139     * accept into it, either through intrinsic knowledge or input data converters.
 140     *
 141     * @param  outFlavorList fills list with supported flavors. This is a copy of
 142     *          the internal list, so it may be edited w/out affecting the transferable.
 143     */
 144   nsISupportsArray flavorsTransferableCanImport ( ) ;
 145
 146   /**
 147     * Sets the data in the transferable with the specified flavor. The transferable
 148     * will maintain its own copy the data, so it is not necessary to do that beforehand.
 149     *
 150     * @param  aFlavor the flavor of data that is being set
 151     * @param  aData the data, either some variant of class in nsISupportsPrimitives.idl,
 152     *         an nsIFile, or an nsIFlavorDataProvider (see above)
 153     * @param  aDataLen the length of the data, or 0 if passing a nsIFlavorDataProvider
 154     */
 155   void setTransferData ( in string aFlavor, in nsISupports aData, in unsigned long aDataLen ) ;
 156
 157   /**
 158     * Add the data flavor, indicating that this transferable
 159     * can receive this type of flavor
 160     *
 161     * @param  aDataFlavor a new data flavor to handle
 162     */
 163   void addDataFlavor ( in string aDataFlavor ) ;
 164
 165   /**
 166     * Removes the data flavor matching the given one (string compare) and the data
 167     * that goes along with it.
 168     *
 169     * @param  aDataFlavor a data flavor to remove
 170     */
 171   void removeDataFlavor ( in string aDataFlavor ) ;
 172
 173   attribute nsIFormatConverter converter;
 174
 175   /**
 176    * Use of the SetIsPrivateData() method generated by isPrivateData attribute should
 177    * be avoided as much as possible because the value set may not reflect the status
 178    * of the context in which the transferable was created.
 179    */
 180   [noscript] attribute boolean isPrivateData;
 181
 182 };
 183