gecko-dev/widget/public/nsITransferable.idl

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is Mozilla Communicator.
 * 
 * The Initial Developer of the Original Code is Netscape Communications
 * Corp.  Portions created by Netscape are Copyright (C) 1999 Netscape 
 * Communications Corp.  All Rights Reserved.
 * 
 * Contributor(s): 
 *   Mike Pinkerton
 */

#include "nsISupports.idl"
#include "nsISupportsArray.idl"
#include "nsIFormatConverter.idl"


%{ C++

// these probably shouldn't live here, but in some central repository shared
// by the entire app.
#define kTextMime      "text/plain"
#define kUnicodeMime   "text/unicode"
#define kHTMLMime      "text/html"
#define kAOLMailMime   "AOLMAIL"
#define kPNGImageMime  "image/png"
#define kJPEGImageMime "image/jpg"
#define kGIFImageMime  "image/gif"
#define kFileMime      "application/x-moz-file"
#define kURLMime       "text/x-moz-url"
#define kNativeImageMime "application/x-moz-nativeimage"
#define kNativeHTMLMime "application/x-moz-nativehtml"

%}


[scriptable, uuid(8B5314BC-DB01-11d2-96CE-0060B0FB9956)]
interface nsITransferable : nsISupports
{
  /**
    * Computes a list of flavors (mime types as nsISupportsCString) that the transferable 
    * can export, either through intrinsic knowledge or output data converters.
    *
    * @param  aDataFlavorList fills list with supported flavors. This is a copy of
    *          the internal list, so it may be edited w/out affecting the transferable.
    */
  nsISupportsArray flavorsTransferableCanExport ( ) ;

  /**
    * Given a flavor retrieve the data. 
    *
    * @param  aFlavor (in parameter) the flavor of data to retrieve
    * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
    * @param  aDataLen the length of the data
    */
  void getTransferData ( in string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ;

  /**
    * Returns the best flavor in the transferable, given those that have
    * been added to it with |AddFlavor()|
    *
    * @param  aFlavor (out parameter) the flavor of data that was retrieved
    * @param  aData the data. Some variant of class in nsISupportsPrimitives.idl
    * @param  aDataLen the length of the data
    */
  void getAnyTransferData ( out string aFlavor, out nsISupports aData, out unsigned long aDataLen ) ;

  /**
    * Returns true if the data is large.
    */
  boolean isLargeDataSet ( ) ;
  

    ///////////////////////////////
    // Setter part of interface 
    ///////////////////////////////

  /**
    * Computes a list of flavors (mime types as nsISupportsCString) that the transferable can
    * accept into it, either through intrinsic knowledge or input data converters.
    *
    * @param  outFlavorList fills list with supported flavors. This is a copy of
    *          the internal list, so it may be edited w/out affecting the transferable.
    */
  nsISupportsArray flavorsTransferableCanImport ( ) ;

  /**
    * Sets the data in the transferable with the specified flavor. The transferable
    * will maintain its own copy the data, so it is not necessary to do that beforehand.
    *
    * @param  aFlavor the flavor of data that is being set
    * @param  aData the data, some variant of class in nsISupportsPrimitives.idl
    * @param  aDataLen the length of the data
    */
  void setTransferData ( in string aFlavor, in nsISupports aData, in unsigned long aDataLen ) ;

  /**
    * Add the data flavor, indicating that this transferable 
    * can receive this type of flavor
    *
    * @param  aDataFlavor a new data flavor to handle
    */
  void addDataFlavor ( in string aDataFlavor ) ;

  /**
    * Removes the data flavor matching the given one (string compare) and the data
    * that goes along with it.
    *
    * @param  aDataFlavor a data flavor to remove
    */
  void removeDataFlavor ( in string aDataFlavor ) ;

  attribute nsIFormatConverter converter;

};