dom/interfaces/events/nsIDOMDataTransfer.idl@7e26c7da4463
dom/interfaces/events/nsIDOMDataTransfer.idl
Wed, 31 Dec 2014 06:55:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:50 +0100
- changeset 2
- 7e26c7da4463
- permissions
- -rw-r--r--
Added tag UPSTREAM_283F7C6 for changeset ca08bd8f51b2
1 /* -*- Mode: C++; 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
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "domstubs.idl"
8 interface nsIVariant;
9 interface nsIDOMFileList;
11 [scriptable, builtinclass, uuid(c71180e3-298b-4fbb-9ccb-82c822474741)]
12 interface nsIDOMDataTransfer : nsISupports
13 {
14 /**
15 * The actual effect that will be used, and should always be one of the
16 * possible values of effectAllowed.
17 *
18 * For dragstart, drag and dragleave events, the dropEffect is initialized
19 * to none. Any value assigned to the dropEffect will be set, but the value
20 * isn't used for anything.
21 *
22 * For the dragenter and dragover events, the dropEffect will be initialized
23 * based on what action the user is requesting. How this is determined is
24 * platform specific, but typically the user can press modifier keys to
25 * adjust which action is desired. Within an event handler for the dragenter
26 * and dragover events, the dropEffect should be modified if the action the
27 * user is requesting is not the one that is desired.
28 *
29 * For the drop and dragend events, the dropEffect will be initialized to
30 * the action that was desired, which will be the value that the dropEffect
31 * had after the last dragenter or dragover event.
32 *
33 * Possible values:
34 * copy - a copy of the source item is made at the new location
35 * move - an item is moved to a new location
36 * link - a link is established to the source at the new location
37 * none - the item may not be dropped
38 *
39 * Assigning any other value has no effect and retains the old value.
40 */
41 attribute DOMString dropEffect;
43 /*
44 * Specifies the effects that are allowed for this drag. You may set this in
45 * the dragstart event to set the desired effects for the source, and within
46 * the dragenter and dragover events to set the desired effects for the
47 * target. The value is not used for other events.
48 *
49 * Possible values:
50 * copy - a copy of the source item is made at the new location
51 * move - an item is moved to a new location
52 * link - a link is established to the source at the new location
53 * copyLink, copyMove, linkMove, all - combinations of the above
54 * none - the item may not be dropped
55 * uninitialized - the default value when the effect has not been set,
56 * equivalent to all.
57 *
58 * Assigning any other value has no effect and retains the old value.
59 */
60 attribute DOMString effectAllowed;
62 /**
63 * Holds a list of all the local files available on this data transfer.
64 * A dataTransfer containing no files will return an empty list, and an
65 * invalid index access on the resulting file list will return null.
66 */
67 readonly attribute nsIDOMFileList files;
69 /**
70 * Holds a list of the format types of the data that is stored for the first
71 * item, in the same order the data was added. An empty list will be
72 * returned if no data was added.
73 */
74 readonly attribute nsISupports types;
76 /**
77 * Remove the data associated with a given format. If format is empty or not
78 * specified, the data associated with all formats is removed. If data for
79 * the specified format does not exist, or the data transfer contains no
80 * data, this method will have no effect.
81 */
82 void clearData([optional] in DOMString format);
84 /**
85 * Set the data for a given format. If data for the format does not exist,
86 * it is added at the end, such that the last item in the types list will be
87 * the new format. If data for the format already exists, the existing data
88 * is replaced in the same position. That is, the order of the types list is
89 * not changed.
90 *
91 * @throws NS_ERROR_NULL_POINTER if the data is null
92 */
93 void setData(in DOMString format, in DOMString data);
95 /**
96 * Retrieves the data for a given format, or an empty string if data for
97 * that format does not exist or the data transfer contains no data.
98 */
99 DOMString getData(in DOMString format);
101 /**
102 * Set the image to be used for dragging if a custom one is desired. Most of
103 * the time, this would not be set, as a default image is created from the
104 * node that was dragged.
105 *
106 * If the node is an HTML img element, an HTML canvas element or a XUL image
107 * element, the image data is used. Otherwise, image should be a visible
108 * node and the drag image will be created from this. If image is null, any
109 * custom drag image is cleared and the default is used instead.
110 *
111 * The coordinates specify the offset into the image where the mouse cursor
112 * should be. To center the image for instance, use values that are half the
113 * width and height.
114 *
115 * @param image a node to use
116 * @param x the horizontal offset
117 * @param y the vertical offset
118 * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
119 */
120 void setDragImage(in nsIDOMElement image, in long x, in long y);
122 /*
123 * Set the drag source. Usually you would not change this, but it will
124 * affect which node the drag and dragend events are fired at. The
125 * default target is the node that was dragged.
126 *
127 * @param element drag source to use
128 * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
129 */
130 void addElement(in nsIDOMElement element);
132 /**
133 * The number of items being dragged.
134 */
135 readonly attribute unsigned long mozItemCount;
137 /**
138 * Sets the drag cursor state. Primarily used to control the cursor during
139 * tab drags, but could be expanded to other uses. XXX Currently implemented
140 * on Win32 only.
141 *
142 * Possible values:
143 * auto - use default system behavior.
144 * default - set the cursor to an arrow during the drag operation.
145 *
146 * Values other than 'default' are indentical to setting mozCursor to
147 * 'auto'.
148 */
149 attribute DOMString mozCursor;
151 /**
152 * Holds a list of the format types of the data that is stored for an item
153 * at the specified index. If the index is not in the range from 0 to
154 * itemCount - 1, an empty string list is returned.
155 */
156 nsISupports mozTypesAt(in unsigned long index);
158 /**
159 * Remove the data associated with the given format for an item at the
160 * specified index. The index is in the range from zero to itemCount - 1.
161 *
162 * If the last format for the item is removed, the entire item is removed,
163 * reducing the itemCount by one.
164 *
165 * If format is empty, then the data associated with all formats is removed.
166 * If the format is not found, then this method has no effect.
167 *
168 * @param format the format to remove
169 * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount
170 * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
171 */
172 void mozClearDataAt(in DOMString format, in unsigned long index);
174 /*
175 * A data transfer may store multiple items, each at a given zero-based
176 * index. setDataAt may only be called with an index argument less than
177 * itemCount in which case an existing item is modified, or equal to
178 * itemCount in which case a new item is added, and the itemCount is
179 * incremented by one.
180 *
181 * Data should be added in order of preference, with the most specific
182 * format added first and the least specific format added last. If data of
183 * the given format already exists, it is replaced in the same position as
184 * the old data.
185 *
186 * The data should be either a string, a primitive boolean or number type
187 * (which will be converted into a string) or an nsISupports.
188 *
189 * @param format the format to add
190 * @param data the data to add
191 * @throws NS_ERROR_NULL_POINTER if the data is null
192 * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater than itemCount
193 * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
194 */
195 void mozSetDataAt(in DOMString format, in nsIVariant data, in unsigned long index);
197 /**
198 * Retrieve the data associated with the given format for an item at the
199 * specified index, or null if it does not exist. The index should be in the
200 * range from zero to itemCount - 1.
201 *
202 * @param format the format of the data to look up
203 * @returns the data of the given format, or null if it doesn't exist.
204 * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount
205 */
206 nsIVariant mozGetDataAt(in DOMString format, in unsigned long index);
208 /**
209 * Will be true when the user has cancelled the drag (typically by pressing
210 * Escape) and when the drag has been cancelled unexpectedly. This will be
211 * false otherwise, including when the drop has been rejected by its target.
212 * This property is only relevant for the dragend event.
213 */
214 readonly attribute boolean mozUserCancelled;
216 /**
217 * The node that the mouse was pressed over to begin the drag. For external
218 * drags, or if the caller cannot access this node, this will be null.
219 */
220 readonly attribute nsIDOMNode mozSourceNode;
222 /*
223 * Integer version of dropEffect, set to one of the constants in nsIDragService.
224 */
225 [noscript] attribute unsigned long dropEffectInt;
227 /*
228 * Integer version of effectAllowed, set to one or a combination of the
229 * constants in nsIDragService.
230 */
231 [noscript] attribute unsigned long effectAllowedInt;
232 };
