nsITransferable 编辑

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 knowledgeor 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

• An instance of a class based upon nsISupportsPrimitives
• An nsIFile
• An nsIFlavorDataProvider

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

• nsIFlavorDataProvider
• nsISupportsPrimitives
• nsIFormatConverter