1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/interfaces/events/nsIDOMDataTransfer.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,232 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "domstubs.idl"
1.10 +
1.11 +interface nsIVariant;
1.12 +interface nsIDOMFileList;
1.13 +
1.14 +[scriptable, builtinclass, uuid(c71180e3-298b-4fbb-9ccb-82c822474741)]
1.15 +interface nsIDOMDataTransfer : nsISupports
1.16 +{
1.17 + /**
1.18 + * The actual effect that will be used, and should always be one of the
1.19 + * possible values of effectAllowed.
1.20 + *
1.21 + * For dragstart, drag and dragleave events, the dropEffect is initialized
1.22 + * to none. Any value assigned to the dropEffect will be set, but the value
1.23 + * isn't used for anything.
1.24 + *
1.25 + * For the dragenter and dragover events, the dropEffect will be initialized
1.26 + * based on what action the user is requesting. How this is determined is
1.27 + * platform specific, but typically the user can press modifier keys to
1.28 + * adjust which action is desired. Within an event handler for the dragenter
1.29 + * and dragover events, the dropEffect should be modified if the action the
1.30 + * user is requesting is not the one that is desired.
1.31 + *
1.32 + * For the drop and dragend events, the dropEffect will be initialized to
1.33 + * the action that was desired, which will be the value that the dropEffect
1.34 + * had after the last dragenter or dragover event.
1.35 + *
1.36 + * Possible values:
1.37 + * copy - a copy of the source item is made at the new location
1.38 + * move - an item is moved to a new location
1.39 + * link - a link is established to the source at the new location
1.40 + * none - the item may not be dropped
1.41 + *
1.42 + * Assigning any other value has no effect and retains the old value.
1.43 + */
1.44 + attribute DOMString dropEffect;
1.45 +
1.46 + /*
1.47 + * Specifies the effects that are allowed for this drag. You may set this in
1.48 + * the dragstart event to set the desired effects for the source, and within
1.49 + * the dragenter and dragover events to set the desired effects for the
1.50 + * target. The value is not used for other events.
1.51 + *
1.52 + * Possible values:
1.53 + * copy - a copy of the source item is made at the new location
1.54 + * move - an item is moved to a new location
1.55 + * link - a link is established to the source at the new location
1.56 + * copyLink, copyMove, linkMove, all - combinations of the above
1.57 + * none - the item may not be dropped
1.58 + * uninitialized - the default value when the effect has not been set,
1.59 + * equivalent to all.
1.60 + *
1.61 + * Assigning any other value has no effect and retains the old value.
1.62 + */
1.63 + attribute DOMString effectAllowed;
1.64 +
1.65 + /**
1.66 + * Holds a list of all the local files available on this data transfer.
1.67 + * A dataTransfer containing no files will return an empty list, and an
1.68 + * invalid index access on the resulting file list will return null.
1.69 + */
1.70 + readonly attribute nsIDOMFileList files;
1.71 +
1.72 + /**
1.73 + * Holds a list of the format types of the data that is stored for the first
1.74 + * item, in the same order the data was added. An empty list will be
1.75 + * returned if no data was added.
1.76 + */
1.77 + readonly attribute nsISupports types;
1.78 +
1.79 + /**
1.80 + * Remove the data associated with a given format. If format is empty or not
1.81 + * specified, the data associated with all formats is removed. If data for
1.82 + * the specified format does not exist, or the data transfer contains no
1.83 + * data, this method will have no effect.
1.84 + */
1.85 + void clearData([optional] in DOMString format);
1.86 +
1.87 + /**
1.88 + * Set the data for a given format. If data for the format does not exist,
1.89 + * it is added at the end, such that the last item in the types list will be
1.90 + * the new format. If data for the format already exists, the existing data
1.91 + * is replaced in the same position. That is, the order of the types list is
1.92 + * not changed.
1.93 + *
1.94 + * @throws NS_ERROR_NULL_POINTER if the data is null
1.95 + */
1.96 + void setData(in DOMString format, in DOMString data);
1.97 +
1.98 + /**
1.99 + * Retrieves the data for a given format, or an empty string if data for
1.100 + * that format does not exist or the data transfer contains no data.
1.101 + */
1.102 + DOMString getData(in DOMString format);
1.103 +
1.104 + /**
1.105 + * Set the image to be used for dragging if a custom one is desired. Most of
1.106 + * the time, this would not be set, as a default image is created from the
1.107 + * node that was dragged.
1.108 + *
1.109 + * If the node is an HTML img element, an HTML canvas element or a XUL image
1.110 + * element, the image data is used. Otherwise, image should be a visible
1.111 + * node and the drag image will be created from this. If image is null, any
1.112 + * custom drag image is cleared and the default is used instead.
1.113 + *
1.114 + * The coordinates specify the offset into the image where the mouse cursor
1.115 + * should be. To center the image for instance, use values that are half the
1.116 + * width and height.
1.117 + *
1.118 + * @param image a node to use
1.119 + * @param x the horizontal offset
1.120 + * @param y the vertical offset
1.121 + * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
1.122 + */
1.123 + void setDragImage(in nsIDOMElement image, in long x, in long y);
1.124 +
1.125 + /*
1.126 + * Set the drag source. Usually you would not change this, but it will
1.127 + * affect which node the drag and dragend events are fired at. The
1.128 + * default target is the node that was dragged.
1.129 + *
1.130 + * @param element drag source to use
1.131 + * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
1.132 + */
1.133 + void addElement(in nsIDOMElement element);
1.134 +
1.135 + /**
1.136 + * The number of items being dragged.
1.137 + */
1.138 + readonly attribute unsigned long mozItemCount;
1.139 +
1.140 + /**
1.141 + * Sets the drag cursor state. Primarily used to control the cursor during
1.142 + * tab drags, but could be expanded to other uses. XXX Currently implemented
1.143 + * on Win32 only.
1.144 + *
1.145 + * Possible values:
1.146 + * auto - use default system behavior.
1.147 + * default - set the cursor to an arrow during the drag operation.
1.148 + *
1.149 + * Values other than 'default' are indentical to setting mozCursor to
1.150 + * 'auto'.
1.151 + */
1.152 + attribute DOMString mozCursor;
1.153 +
1.154 + /**
1.155 + * Holds a list of the format types of the data that is stored for an item
1.156 + * at the specified index. If the index is not in the range from 0 to
1.157 + * itemCount - 1, an empty string list is returned.
1.158 + */
1.159 + nsISupports mozTypesAt(in unsigned long index);
1.160 +
1.161 + /**
1.162 + * Remove the data associated with the given format for an item at the
1.163 + * specified index. The index is in the range from zero to itemCount - 1.
1.164 + *
1.165 + * If the last format for the item is removed, the entire item is removed,
1.166 + * reducing the itemCount by one.
1.167 + *
1.168 + * If format is empty, then the data associated with all formats is removed.
1.169 + * If the format is not found, then this method has no effect.
1.170 + *
1.171 + * @param format the format to remove
1.172 + * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount
1.173 + * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
1.174 + */
1.175 + void mozClearDataAt(in DOMString format, in unsigned long index);
1.176 +
1.177 + /*
1.178 + * A data transfer may store multiple items, each at a given zero-based
1.179 + * index. setDataAt may only be called with an index argument less than
1.180 + * itemCount in which case an existing item is modified, or equal to
1.181 + * itemCount in which case a new item is added, and the itemCount is
1.182 + * incremented by one.
1.183 + *
1.184 + * Data should be added in order of preference, with the most specific
1.185 + * format added first and the least specific format added last. If data of
1.186 + * the given format already exists, it is replaced in the same position as
1.187 + * the old data.
1.188 + *
1.189 + * The data should be either a string, a primitive boolean or number type
1.190 + * (which will be converted into a string) or an nsISupports.
1.191 + *
1.192 + * @param format the format to add
1.193 + * @param data the data to add
1.194 + * @throws NS_ERROR_NULL_POINTER if the data is null
1.195 + * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater than itemCount
1.196 + * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
1.197 + */
1.198 + void mozSetDataAt(in DOMString format, in nsIVariant data, in unsigned long index);
1.199 +
1.200 + /**
1.201 + * Retrieve the data associated with the given format for an item at the
1.202 + * specified index, or null if it does not exist. The index should be in the
1.203 + * range from zero to itemCount - 1.
1.204 + *
1.205 + * @param format the format of the data to look up
1.206 + * @returns the data of the given format, or null if it doesn't exist.
1.207 + * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount
1.208 + */
1.209 + nsIVariant mozGetDataAt(in DOMString format, in unsigned long index);
1.210 +
1.211 + /**
1.212 + * Will be true when the user has cancelled the drag (typically by pressing
1.213 + * Escape) and when the drag has been cancelled unexpectedly. This will be
1.214 + * false otherwise, including when the drop has been rejected by its target.
1.215 + * This property is only relevant for the dragend event.
1.216 + */
1.217 + readonly attribute boolean mozUserCancelled;
1.218 +
1.219 + /**
1.220 + * The node that the mouse was pressed over to begin the drag. For external
1.221 + * drags, or if the caller cannot access this node, this will be null.
1.222 + */
1.223 + readonly attribute nsIDOMNode mozSourceNode;
1.224 +
1.225 + /*
1.226 + * Integer version of dropEffect, set to one of the constants in nsIDragService.
1.227 + */
1.228 + [noscript] attribute unsigned long dropEffectInt;
1.229 +
1.230 + /*
1.231 + * Integer version of effectAllowed, set to one or a combination of the
1.232 + * constants in nsIDragService.
1.233 + */
1.234 + [noscript] attribute unsigned long effectAllowedInt;
1.235 +};
