DataTransfer.webidl (6868B)
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: 7 * http://www.whatwg.org/specs/web-apps/current-work/#the-datatransfer-interface 8 */ 9 interface PolicyContainer; 10 11 [Exposed=Window] 12 interface DataTransfer { 13 constructor(); 14 15 attribute DOMString dropEffect; 16 attribute DOMString effectAllowed; 17 18 readonly attribute DataTransferItemList items; 19 20 undefined setDragImage(Element image, long x, long y); 21 22 [Frozen, Cached, Pure, NeedsCallerType] 23 readonly attribute sequence<DOMString> types; 24 [Throws, NeedsSubjectPrincipal] 25 DOMString getData(DOMString format); 26 [Throws, NeedsSubjectPrincipal] 27 undefined setData(DOMString format, DOMString data); 28 [Throws, NeedsSubjectPrincipal] 29 undefined clearData(optional DOMString format); 30 [NeedsSubjectPrincipal] 31 readonly attribute FileList? files; 32 }; 33 34 // Mozilla specific stuff 35 partial interface DataTransfer { 36 /* 37 * Set the drag source. Usually you would not change this, but it will 38 * affect which node the drag and dragend events are fired at. The 39 * default target is the node that was dragged. 40 * 41 * @param element drag source to use 42 * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified 43 */ 44 [Throws, UseCounter] 45 undefined addElement(Element element); 46 47 /** 48 * The number of items being dragged. 49 */ 50 [ChromeOnly] 51 readonly attribute unsigned long mozItemCount; 52 53 /** 54 * Sets the drag cursor state. Primarily used to control the cursor during 55 * tab drags, but could be expanded to other uses. XXX Currently implemented 56 * on Win32 only. 57 * 58 * Possible values: 59 * auto - use default system behavior. 60 * default - set the cursor to an arrow during the drag operation. 61 * 62 * Values other than 'default' are indentical to setting mozCursor to 63 * 'auto'. 64 */ 65 [UseCounter] 66 attribute DOMString mozCursor; 67 68 /** 69 * Holds a list of the format types of the data that is stored for an item 70 * at the specified index. If the index is not in the range from 0 to 71 * itemCount - 1, an empty string list is returned. 72 */ 73 [Throws, ChromeOnly] 74 DOMStringList mozTypesAt(unsigned long index); 75 76 /** 77 * Remove the data associated with the given format for an item at the 78 * specified index. The index is in the range from zero to itemCount - 1. 79 * 80 * If the last format for the item is removed, the entire item is removed, 81 * reducing the itemCount by one. 82 * 83 * If format is empty, then the data associated with all formats is removed. 84 * If the format is not found, then this method has no effect. 85 * 86 * @param format the format to remove 87 * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount 88 * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified 89 */ 90 [Throws, ChromeOnly] 91 undefined mozClearDataAt(DOMString format, unsigned long index); 92 93 /* 94 * A data transfer may store multiple items, each at a given zero-based 95 * index. setDataAt may only be called with an index argument less than 96 * itemCount in which case an existing item is modified, or equal to 97 * itemCount in which case a new item is added, and the itemCount is 98 * incremented by one. 99 * 100 * Data should be added in order of preference, with the most specific 101 * format added first and the least specific format added last. If data of 102 * the given format already exists, it is replaced in the same position as 103 * the old data. 104 * 105 * The data should be either a string, a primitive boolean or number type 106 * (which will be converted into a string) or an nsISupports. 107 * 108 * @param format the format to add 109 * @param data the data to add 110 * @throws NS_ERROR_NULL_POINTER if the data is null 111 * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater than itemCount 112 * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified 113 */ 114 [Throws, ChromeOnly] 115 undefined mozSetDataAt(DOMString format, any data, unsigned long index); 116 117 /** 118 * Retrieve the data associated with the given format for an item at the 119 * specified index, or null if it does not exist. The index should be in the 120 * range from zero to itemCount - 1. 121 * 122 * @param format the format of the data to look up 123 * @returns the data of the given format, or null if it doesn't exist. 124 * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount 125 */ 126 [Throws, ChromeOnly] 127 any mozGetDataAt(DOMString format, unsigned long index); 128 129 /** 130 * Update the drag image. Arguments are the same as setDragImage. This is only 131 * valid within the parent chrome process. 132 */ 133 [ChromeOnly] 134 undefined updateDragImage(Element image, long x, long y); 135 136 /** 137 * Will be true when the user has cancelled the drag (typically by pressing 138 * Escape) and when the drag has been cancelled unexpectedly. This will be 139 * false otherwise, including when the drop has been rejected by its target. 140 * This property is only relevant for the dragend event. 141 */ 142 [UseCounter] 143 readonly attribute boolean mozUserCancelled; 144 145 /** 146 * The node that the mouse was pressed over to begin the drag. For external 147 * drags, or if the caller cannot access this node, this will be null. 148 */ 149 [UseCounter] 150 readonly attribute Node? mozSourceNode; 151 152 /** 153 * The top-level window context that mouse was pressed over to begin the drag. 154 * For external drags, this will be null. 155 */ 156 [ChromeOnly] 157 readonly attribute WindowContext? sourceTopWindowContext; 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 [ChromeOnly] 168 readonly attribute PolicyContainer? policyContainer; 169 170 /** 171 * Copy the given DataTransfer for the given event. Used by testing code for 172 * creating emulated Drag and Drop events in the UI. 173 * 174 * NOTE: Don't expose a DataTransfer produced with this method to the web or 175 * use this for non-testing purposes. It can easily be used to get the 176 * DataTransfer into an invalid state, and is an unstable implementation 177 * detail of EventUtils.synthesizeDrag. 178 */ 179 [Throws, ChromeOnly] 180 DataTransfer mozCloneForEvent(DOMString event); 181 182 /** 183 * Whether to show the "fail" animation that returns a dragged item 184 * to its source. Only works on macOS, and has to be set early in the drag 185 * on that platform. 186 * Defaults to true. 187 */ 188 [ChromeOnly] 189 attribute boolean mozShowFailAnimation; 190 };