This article needs a technical review. How you can help.
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 |
|
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 |
|
The source DOM 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()
Requires Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10)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
nullif 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
aDatais annsIFlavorDataProvider.