XUL:Specs:TransferData: Difference between revisions

Jump to navigation Jump to search

XUL:Specs:TransferData (view source)

Revision as of 23:11, 27 October 2006

4,369 bytes added ,  27 October 2006
→‎Plan
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.
Enn
287

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/39596"

Navigation menu