widget/nsITransferable.idlScriptable
A container for typed data that can be transferred from one place or owner to another, possibly involving format conversion. These objects are used during drag-and-drop operations.
Inherits from: nsISupports Last changed in Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10)

Implemented by: @mozilla.org/widget/transferable;1. To create an instance, use:

var transferable = Components.classes["@mozilla.org/widget/transferable;1"]
                   .createInstance(Components.interfaces.nsITransferable);

It's important to note that a flavor, which specifies a type of data the transferable supports, is represented by a null-terminated string indicating the MIME type of the format supported by the flavor.

Method overview

void addDataFlavor( in string aDataFlavor );
nsISupportsArray flavorsTransferableCanExport( );
nsISupportsArray flavorsTransferableCanImport( );
void getAnyTransferData( out string aFlavor, out nsISupports aData, out unsigned long aDataLen );
void getTransferData( in string aFlavor, out nsISupports aData, out unsigned long aDataLen );
void init(in nsILoadContext aContext);
boolean isLargeDataSet( );
void removeDataFlavor( in string aDataFlavor );
void setTransferData( in string aFlavor, in nsISupports aData, in unsigned long aDataLen );

Attributes

Attribute Type Description
converter nsIFormatConverter An nsIFormatConverter instance which implements the code needed to convert data into and out of the transferable given the supported flavors.
isPrivateData boolean Although this is not a read-only attribute, you should generally avoid changing it, since doing so may cause it not to actually reflect the status of the context in which the transferable was created. Native code only!
requestingNode nsIDOMNode

The source DOM Node this transferable was created from. Native code only!

Note: Currently, this can only be used on Windows (in order to support network principal information in drag operations).

Constants

kFlavorHasDataProvider

(that title needs to be better)

Constant Value Description
kFlavorHasDataProvider 0 A description is needed here.

Common MIME types

Some of these need better descriptions, especially the Mozilla-specific ones.

Constant Value Description
kTextMime text/plain Plain text.
kUnicodeMime text/unicode Unicode text.
kMozTextInternal text/x-moz-text-internal Text data that isn't meant to be used by non-Mozilla code.
kHTMLMime text/html HTML.
kAOLMailMime AOLMAIL AOL mail. Need details.
kPNGImageMime image/png PNG image.
kJPEGImageMime image/jpeg JPEG image.
kJPGImageMime image/jpg JPEG image.
kGIFImageMime image/gif GIF image.
kFileMime application/x-moz-file An arbitrary file (is this an nsIFile?)
kURLMime text/x-moz-url A Mozilla URL object; this is a text string containing the URL, a newline (\n), then the title of the page.
kURLDataMime text/x-moz-url-data A string containing only a URL.
kURLDescriptionMime text/x-moz-url-desc A string containing only a description.
kURLPrivateMime text/x-moz-url-priv The same as kURLDataMIme, except intended for private use only.
kNativeImageMime application/x-moz-nativeimage An image in Gecko's native internal image storage format.
kNativeHTMLMime application/x-moz-nativehtml HTML in Gecko's native internal storage format.
kHTMLContext text/_moz_htmlcontext Along with kHTMLInfo, this is used to provide the context for a fragment of HTML source. Contains the serialized ancestor elements.
kHTMLInfo text/_moz_htmlinfo Along with kHTMLContext, this is used to provide the context for a fragment of HTML source. Contains numbers identifying where in the context the fragment came from.
kFilePromiseURLMime application/x-moz-file-promise-url The source URL for a file promise.
kFilePromiseDestFilename application/x-moz-file-promise-dest-filename The destination URL for a file promise.
kFilePromiseMime application/x-moz-file-promise A dataless flavor used to interact with the operating system during file drags.
kFilePromiseDirectoryMime application/x-moz-file-promise-dir A synthetic flavor which is added to the transferable once the destination directory for a file drag is known.

Methods

addDataFlavor()

Adds a new data flavor, indicating that this transferable can receive the type of data represented by the specified flavor string.

void addDataFlavor(
  in string aDataFlavor
);
Parameters
aDataFlavor
A string defining a new data flavor that the transferable supports.

flavorsTransferableCanExport()

Returns a list of flavors (mime types as nsISupportsCString) that the transferable can export, either through intrinsic knowledge or output data converters.

nsISupportsArray flavorsTransferableCanExport();
Parameters

None.

Return value

Missing Description

flavorsTransferableCanImport()

Computes a list of flavors (MIME types as nsISupportsCString) that the transferable can accept into it, either through intrinsic knowledge or input data converters.

nsISupportsArray flavorsTransferableCanImport();
Parameters

None.

Return value

Missing Description

getAnyTransferData()

Returns the best flavor in the transferable, given those that have been added to it with addDataFlavor().

void getAnyTransferData(
  out string aFlavor,
  out nsISupports aData,
  out unsigned long aDataLen
);
Parameters
aFlavor
On return, contains the flavor of data that was retrieved.
aData
On return, this is the data itself, which is an instance of a class based upon nsISupportsPrimitives.
aDataLen
On return, this value contains the size of the returned data.

getTransferData()

Returns the transfer data for a given flavor.

void getTransferData(
  in string aFlavor,
  out nsISupports aData,
  out unsigned long aDataLen
);
Parameters
aFlavor
The flavor of data to retrieve.
aData
On return, this is the data itself, which is an instance of a class based upon nsISupportsPrimitives.
aDataLen
On return, this value contains the size of the returned data.

init()

Initializes a transferable object. This should be called on all transferable objects. Failure to do so will result in fatal assertions in debug builds.

void init(
  in nsILoadContext aContext
);
Parameters
aContext
The load context associated with the transferable object. This can be set to null if a load context is not available.
Remarks

The load context is used to track whether the transferable is storing privacy-sensitive information. For example, we try to delete data that you copy to the clipboard when you close a Private Browsing window.

To get the appropriate load context in JavaScript callers, one needs to get to the document that the transferable corresponds to, and then get the load context from the document like this:

var loadContext = doc.defaultView.QueryInterface(Ci.nsIInterfaceRequestor)
                  .getInterface(Ci.nsIWebNavigation)
                  .QueryInterface(Ci.nsILoadContext);

In C++ callers, if you have the corresponding document, you can just call nsIDocument.GetLoadContext() to get to the load context object.

isLargeDataSet()

Returns true if the data is large.

boolean isLargeDataSet();
Parameters
None.
Return value

true if the data is large; otherwise, the result is false.

removeDataFlavor()

Removes the data flavor matching the given one (as determined by a string comparison), along with the corresponding data.

void removeDataFlavor(
  in string aDataFlavor
);
Parameters
aDataFlavor
The data flavor to remove.

setTransferData()

Sets the data in the transferable with the specified flavor. The transferable maintains its own copy of the data, so you can safely discard the original after making this call, if you wish.

void setTransferData(
  in string aFlavor,
  in nsISupports aData,
  in unsigned long aDataLen
);
Parameters
aFlavor
The flavor of data that is being set.
aData
The data.
aDataLen
The length of the data, or 0 if aData is an nsIFlavorDataProvider.

See also