Source code

Revision control

Other Tools

1
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2
/* This Source Code Form is subject to the terms of the Mozilla Public
3
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
4
* You can obtain one at http://mozilla.org/MPL/2.0/.
5
*
6
* The origin of this IDL file is:
8
*/
9
10
[Constructor]
11
interface DataTransfer {
12
attribute DOMString dropEffect;
13
attribute DOMString effectAllowed;
14
15
readonly attribute DataTransferItemList items;
16
17
void setDragImage(Element image, long x, long y);
18
19
// ReturnValueNeedsContainsHack on .types because lots of extension
20
// code was expecting .contains() back when it was a DOMStringList.
21
[Pure, Cached, Frozen, NeedsCallerType, ReturnValueNeedsContainsHack]
22
readonly attribute sequence<DOMString> types;
23
[Throws, NeedsSubjectPrincipal]
24
DOMString getData(DOMString format);
25
[Throws, NeedsSubjectPrincipal]
26
void setData(DOMString format, DOMString data);
27
[Throws, NeedsSubjectPrincipal]
28
void clearData(optional DOMString format);
29
[NeedsSubjectPrincipal]
30
readonly attribute FileList? files;
31
};
32
33
partial interface DataTransfer {
34
[Throws, Pref="dom.input.dirpicker", NeedsSubjectPrincipal]
35
Promise<sequence<(File or Directory)>> getFilesAndDirectories();
36
37
[Throws, Pref="dom.input.dirpicker", NeedsSubjectPrincipal]
38
Promise<sequence<File>> getFiles(optional boolean recursiveFlag = false);
39
};
40
41
// Mozilla specific stuff
42
partial interface DataTransfer {
43
/*
44
* Set the drag source. Usually you would not change this, but it will
45
* affect which node the drag and dragend events are fired at. The
46
* default target is the node that was dragged.
47
*
48
* @param element drag source to use
49
* @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
50
*/
51
[Throws, UseCounter]
52
void addElement(Element element);
53
54
/**
55
* The number of items being dragged.
56
*/
57
[Func="DataTransfer::MozAtAPIsEnabled"]
58
readonly attribute unsigned long mozItemCount;
59
60
/**
61
* Sets the drag cursor state. Primarily used to control the cursor during
62
* tab drags, but could be expanded to other uses. XXX Currently implemented
63
* on Win32 only.
64
*
65
* Possible values:
66
* auto - use default system behavior.
67
* default - set the cursor to an arrow during the drag operation.
68
*
69
* Values other than 'default' are indentical to setting mozCursor to
70
* 'auto'.
71
*/
72
[UseCounter]
73
attribute DOMString mozCursor;
74
75
/**
76
* Holds a list of the format types of the data that is stored for an item
77
* at the specified index. If the index is not in the range from 0 to
78
* itemCount - 1, an empty string list is returned.
79
*/
80
[Throws, NeedsCallerType, Func="DataTransfer::MozAtAPIsEnabled"]
81
DOMStringList mozTypesAt(unsigned long index);
82
83
/**
84
* Remove the data associated with the given format for an item at the
85
* specified index. The index is in the range from zero to itemCount - 1.
86
*
87
* If the last format for the item is removed, the entire item is removed,
88
* reducing the itemCount by one.
89
*
90
* If format is empty, then the data associated with all formats is removed.
91
* If the format is not found, then this method has no effect.
92
*
93
* @param format the format to remove
94
* @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount
95
* @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
96
*/
97
[Throws, NeedsSubjectPrincipal, Func="DataTransfer::MozAtAPIsEnabled"]
98
void mozClearDataAt(DOMString format, unsigned long index);
99
100
/*
101
* A data transfer may store multiple items, each at a given zero-based
102
* index. setDataAt may only be called with an index argument less than
103
* itemCount in which case an existing item is modified, or equal to
104
* itemCount in which case a new item is added, and the itemCount is
105
* incremented by one.
106
*
107
* Data should be added in order of preference, with the most specific
108
* format added first and the least specific format added last. If data of
109
* the given format already exists, it is replaced in the same position as
110
* the old data.
111
*
112
* The data should be either a string, a primitive boolean or number type
113
* (which will be converted into a string) or an nsISupports.
114
*
115
* @param format the format to add
116
* @param data the data to add
117
* @throws NS_ERROR_NULL_POINTER if the data is null
118
* @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater than itemCount
119
* @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
120
*/
121
[Throws, NeedsSubjectPrincipal, Func="DataTransfer::MozAtAPIsEnabled"]
122
void mozSetDataAt(DOMString format, any data, unsigned long index);
123
124
/**
125
* Retrieve the data associated with the given format for an item at the
126
* specified index, or null if it does not exist. The index should be in the
127
* range from zero to itemCount - 1.
128
*
129
* @param format the format of the data to look up
130
* @returns the data of the given format, or null if it doesn't exist.
131
* @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount
132
*/
133
[Throws, NeedsSubjectPrincipal, Func="DataTransfer::MozAtAPIsEnabled"]
134
any mozGetDataAt(DOMString format, unsigned long index);
135
136
/**
137
* Update the drag image. Arguments are the same as setDragImage. This is only
138
* valid within the parent chrome process.
139
*/
140
[ChromeOnly]
141
void updateDragImage(Element image, long x, long y);
142
143
/**
144
* Will be true when the user has cancelled the drag (typically by pressing
145
* Escape) and when the drag has been cancelled unexpectedly. This will be
146
* false otherwise, including when the drop has been rejected by its target.
147
* This property is only relevant for the dragend event.
148
*/
149
[UseCounter]
150
readonly attribute boolean mozUserCancelled;
151
152
/**
153
* The node that the mouse was pressed over to begin the drag. For external
154
* drags, or if the caller cannot access this node, this will be null.
155
*/
156
[UseCounter]
157
readonly attribute Node? mozSourceNode;
158
159
/**
160
* The URI spec of the triggering principal. This may be different than
161
* sourceNode's principal when sourceNode is xul:browser and the drag is
162
* triggered in a browsing context inside it.
163
*/
164
[ChromeOnly]
165
readonly attribute DOMString mozTriggeringPrincipalURISpec;
166
167
/**
168
* Copy the given DataTransfer for the given event. Used by testing code for
169
* creating emulated Drag and Drop events in the UI.
170
*
171
* NOTE: Don't expose a DataTransfer produced with this method to the web or
172
* use this for non-testing purposes. It can easily be used to get the
173
* DataTransfer into an invalid state, and is an unstable implementation
174
* detail of EventUtils.synthesizeDrag.
175
*/
176
[Throws, ChromeOnly]
177
DataTransfer mozCloneForEvent(DOMString event);
178
};