XUL:Specs:TransferData: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
 
Line 18: Line 18:
*Clipboard operations are only available for privileged applications, apart from built in behaviour of widgets or shortcut keys.
*Clipboard operations are only available for privileged applications, apart from built in behaviour of widgets or shortcut keys.


==Plan==
<breadcrumbs></breadcrumbs>


At the moment, I'm thinking of a top-level JS API for various UI components. The APIs should be designed for JS usage (or at least scripting usage), rather than C++ usage so the arguments should be scriptable rather than XPCOM types.
= DataTransferItem =


Sticking thse APIs below here so I can remember them. They are just based on the existing C++ drag service, clipboard and transferable interfaces, as a start.
A DataTransferItem holds data to be used for inter-application transfer,
such as the data being dragged during a drag and drop operation or the data
on the clipboard. The data may be provided in multiple formats, where each
format is a MIME type, such as text/plain or image/png. Multiple formats are
used to provide data in more specific formats for those applications that
can receive them, and more general formats for applications that can only
handle certain formats.


<pre>
The format text/plain should be used for string data. For compatability,
interface nsITransferLazyData : nsISupports
the format text/unicode is equivalent to text/plain. Data stored in either
{
will be retrievable in either format as well.
  nsIVariant getData(in AString aFlavor, in nsITransferData aTransferable);
}


interface nsITransferData : nsISupports
The data may be any object, stored as an nsIVariant. In script, nsIVariant
{
objects may hold any type of data, and will automatically convert between the
  /**
script type and the nsIVariant. For instance, a string may supplied directly
  * Retrieve the data for a particular flavor. If an empty string is supplied
to the methods below which accept an nsIVariant as an argument.
  * for the flavor, return the best one.
  */
  nsIVariant getData(in AString flavor);


  void getFlavors([array, size_is(length)] out AString flavors, out unsigned long length);
Generally, only objects that implement nsISupports and strings are stored.
Other primitive formats such as boolean and integer are converted to strings
when stored.


  void addData(in AString flavor, nsIVariant data);
Data may be added to the DataTransferItem using the addData method. Data
is stored in the order that it is added. Thus, data of formats with greater
specificity should be added first while data that is more general should be
added last. Generally, text/plain string data is the most likely format a
drop target will be able to support at minimum, so this format should be
added last.


  void addLazyData(in AString flavor, nsITransferLazyData lazydata);
All data added to the DataTransferItem is stored with the principal of the caller
adding the data. Code with lower privileges that cannot access objects of that
principal will not be able to access or change the data, and a security exception
will be thrown. For example, if a privileged application adds data, an ordinary
web page will not be able to access data via that flavor, however, it may add
data of other flavors.


  void removeData(in AString flavor);
More information about formats may be found in [[DataTransferItem:Formats]].
}


interface nsIClipboardJS : nsISupports
= Methods =
{
  nsITransferData getDataTransfer(in AString flavor);
  void setDataTransfer(in AString flavor, nsITransferData data);


  nsIVariant getData(in AString flavor);
== hasData ==
  void setData(in AString flavor, nsIVariant data);
}


interface nsIDragJS : nsISupports
<code>boolean hasData ( string format )</code>
{
  void startDrag(in nsIDOMNode sourceNode, PRInt32 action);


  void startDragTransfer(in nsIDOMNode sourceNode,
Determine whether data of the given format is present. Returns true if the
                        [array, size_is(length)] items,
DataTransferItems contains data of the given format, or false otherwise.
                        unsigned long length,
 
                        PRInt32 action);
'''Parameters'''
}
 
</pre>
<code>format</code>
: the format of the data to look up. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.
 
 
== getData ==
 
<code>nsIVariant getData ( string format )</code>
 
Retrieve the data for a particular format, or null if data of that format doesn't exist.
 
'''Parameters'''
 
<code>format</code>
: the format of the data to retrieve. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.
 
 
== getDataInSet ==
 
<code>nsIVariant getDataInSet ( string formats, out string foundFormat )</code>
 
Retrieve the data from a set of formats, or null if it doesn't exist. The set of formats is supplied in the formats argument, and is a space separated list of formats to look for. This method will return the data corresponding to the first format that is found, or null if the data was not found. The found format is set in the out argument format.
 
If the formats argument is an empty string, then the first data of any format is returned.
 
This method is most useful when the caller wants to retrieve the best data given a set of formats that the caller knows can be supported.
 
'''Parameters'''
 
<code>format</code>
: the format of the data to retrieve. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.
<code>foundFormat</code>
: foundFormat will be set to the first format that will be found, or an empty string if no data was found
 
 
== setData ==
 
<code>nsIVariant setData ( string format , nsIVariant data )</code>
 
Add data to the transferable of the given format. Data should be added in order of preference, with the most specific format first and the least specific format last. If data of the given format already exists, it is replaced in the same position as the old data.
 
If data implements nsIFlavorDataProvider, the real data will be requested through the flavor data provider only when it is accessed. This would be used when the data is large or when it would be a lengthy computation to compute it.
 
'''Parameters'''
 
<code>format</code>
: the format of the data to add. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.
<code>data</code>
: the data to add. If this is null, a null pointer exception will be thrown.
 
 
== removeData ==
 
<code>void removeData ( string format )</code>
 
Remove the data associated with the given format. If data for that format is not contained within the DataTransferItem, a DOM_NOT_FOUND_ERR exception will be thrown.
 
'''Parameters'''
 
<code>formats</code>
: the format of the data to remove. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.
 
 
== allowAnyAccess ==
 
<code>[noscript] void allowAnyAccess ( )</code>
 
Indicate that any caller may access the data contained within the transferable, and not just those with appropriate principals. This effectively clears the principals that were stored with the data. This is called when dropping the data.
 
This non-scriptable method is used by the drag and drop code to allow the data to be accessed within a drop event.
 
= Properties =
 
== transferable ==
 
<code>nsITransferable transferable</code>
 
Converts the data into an nsITransferable to be used for drag and drop or clipboard operations. Usually, you don't need to call this yourself.
 
== formats ==
 
<code>DOMStringList formats</code>
 
Holds a list of the formats of the data that is stored, in the same order the data was added.
 
= See Also =
 
[[DataTransfer]] - used to hold a collection of DataTransferItem objects for drag and drop or clipboard use.
 
= History =
 
This interface was added in Mozilla 1.9.

Revision as of 23:11, 27 October 2006

Current State

  • Clipboard and drag/drop APIs require too much code, and don't really do much of the hard work for you.

Requirements

  • Should be able to do clipboard and drag/drop operations without complex code.
  • Need drag/drop APIs that are unprivileged
  • Need to have an event which is fired on the drag source when a drag is cancelled and when a drop is done on another application
  • Drag images showing what is being dragged, for example icons or treecells.
  • Shouldn't have to serialize and deserialize DOM nodes or other objects when moving between the same application.

The WhatWG defines some drag and drop functionality, based on the IE model. It mostly concerns the way the drag/drop events are fired. Need clarfication on it, but it seems that only strings can be specified as the dragged data.

Security

  • An application should only be able to retrieve items being dragged from the same origin domain. This means that a drag can occur between different domains. For different domains, the drag data is only available to a different domain after the drop.
  • Clipboard operations are only available for privileged applications, apart from built in behaviour of widgets or shortcut keys.

<breadcrumbs></breadcrumbs>

DataTransferItem

A DataTransferItem holds data to be used for inter-application transfer, such as the data being dragged during a drag and drop operation or the data on the clipboard. The data may be provided in multiple formats, where each format is a MIME type, such as text/plain or image/png. Multiple formats are used to provide data in more specific formats for those applications that can receive them, and more general formats for applications that can only handle certain formats.

The format text/plain should be used for string data. For compatability, the format text/unicode is equivalent to text/plain. Data stored in either will be retrievable in either format as well.

The data may be any object, stored as an nsIVariant. In script, nsIVariant objects may hold any type of data, and will automatically convert between the script type and the nsIVariant. For instance, a string may supplied directly to the methods below which accept an nsIVariant as an argument.

Generally, only objects that implement nsISupports and strings are stored. Other primitive formats such as boolean and integer are converted to strings when stored.

Data may be added to the DataTransferItem using the addData method. Data is stored in the order that it is added. Thus, data of formats with greater specificity should be added first while data that is more general should be added last. Generally, text/plain string data is the most likely format a drop target will be able to support at minimum, so this format should be added last.

All data added to the DataTransferItem is stored with the principal of the caller adding the data. Code with lower privileges that cannot access objects of that principal will not be able to access or change the data, and a security exception will be thrown. For example, if a privileged application adds data, an ordinary web page will not be able to access data via that flavor, however, it may add data of other flavors.

More information about formats may be found in DataTransferItem:Formats.

Methods

hasData

boolean hasData ( string format )

Determine whether data of the given format is present. Returns true if the DataTransferItems contains data of the given format, or false otherwise.

Parameters

format

the format of the data to look up. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.


getData

nsIVariant getData ( string format )

Retrieve the data for a particular format, or null if data of that format doesn't exist.

Parameters

format

the format of the data to retrieve. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.


getDataInSet

nsIVariant getDataInSet ( string formats, out string foundFormat )

Retrieve the data from a set of formats, or null if it doesn't exist. The set of formats is supplied in the formats argument, and is a space separated list of formats to look for. This method will return the data corresponding to the first format that is found, or null if the data was not found. The found format is set in the out argument format.

If the formats argument is an empty string, then the first data of any format is returned.

This method is most useful when the caller wants to retrieve the best data given a set of formats that the caller knows can be supported.

Parameters

format

the format of the data to retrieve. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.

foundFormat

foundFormat will be set to the first format that will be found, or an empty string if no data was found


setData

nsIVariant setData ( string format , nsIVariant data )

Add data to the transferable of the given format. Data should be added in order of preference, with the most specific format first and the least specific format last. If data of the given format already exists, it is replaced in the same position as the old data.

If data implements nsIFlavorDataProvider, the real data will be requested through the flavor data provider only when it is accessed. This would be used when the data is large or when it would be a lengthy computation to compute it.

Parameters

format

the format of the data to add. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.

data

the data to add. If this is null, a null pointer exception will be thrown.


removeData

void removeData ( string format )

Remove the data associated with the given format. If data for that format is not contained within the DataTransferItem, a DOM_NOT_FOUND_ERR exception will be thrown.

Parameters

formats

the format of the data to remove. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.


allowAnyAccess

[noscript] void allowAnyAccess ( )

Indicate that any caller may access the data contained within the transferable, and not just those with appropriate principals. This effectively clears the principals that were stored with the data. This is called when dropping the data.

This non-scriptable method is used by the drag and drop code to allow the data to be accessed within a drop event.

Properties

transferable

nsITransferable transferable

Converts the data into an nsITransferable to be used for drag and drop or clipboard operations. Usually, you don't need to call this yourself.

formats

DOMStringList formats

Holds a list of the formats of the data that is stored, in the same order the data was added.

See Also

DataTransfer - used to hold a collection of DataTransferItem objects for drag and drop or clipboard use.

History

This interface was added in Mozilla 1.9.

Retrieved from "https://wiki.allizom.org/index.php?title=XUL:Specs:TransferData&oldid=39596"