michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "domstubs.idl" michael@0: michael@0: interface nsIVariant; michael@0: interface nsIDOMFileList; michael@0: michael@0: [scriptable, builtinclass, uuid(c71180e3-298b-4fbb-9ccb-82c822474741)] michael@0: interface nsIDOMDataTransfer : nsISupports michael@0: { michael@0: /** michael@0: * The actual effect that will be used, and should always be one of the michael@0: * possible values of effectAllowed. michael@0: * michael@0: * For dragstart, drag and dragleave events, the dropEffect is initialized michael@0: * to none. Any value assigned to the dropEffect will be set, but the value michael@0: * isn't used for anything. michael@0: * michael@0: * For the dragenter and dragover events, the dropEffect will be initialized michael@0: * based on what action the user is requesting. How this is determined is michael@0: * platform specific, but typically the user can press modifier keys to michael@0: * adjust which action is desired. Within an event handler for the dragenter michael@0: * and dragover events, the dropEffect should be modified if the action the michael@0: * user is requesting is not the one that is desired. michael@0: * michael@0: * For the drop and dragend events, the dropEffect will be initialized to michael@0: * the action that was desired, which will be the value that the dropEffect michael@0: * had after the last dragenter or dragover event. michael@0: * michael@0: * Possible values: michael@0: * copy - a copy of the source item is made at the new location michael@0: * move - an item is moved to a new location michael@0: * link - a link is established to the source at the new location michael@0: * none - the item may not be dropped michael@0: * michael@0: * Assigning any other value has no effect and retains the old value. michael@0: */ michael@0: attribute DOMString dropEffect; michael@0: michael@0: /* michael@0: * Specifies the effects that are allowed for this drag. You may set this in michael@0: * the dragstart event to set the desired effects for the source, and within michael@0: * the dragenter and dragover events to set the desired effects for the michael@0: * target. The value is not used for other events. michael@0: * michael@0: * Possible values: michael@0: * copy - a copy of the source item is made at the new location michael@0: * move - an item is moved to a new location michael@0: * link - a link is established to the source at the new location michael@0: * copyLink, copyMove, linkMove, all - combinations of the above michael@0: * none - the item may not be dropped michael@0: * uninitialized - the default value when the effect has not been set, michael@0: * equivalent to all. michael@0: * michael@0: * Assigning any other value has no effect and retains the old value. michael@0: */ michael@0: attribute DOMString effectAllowed; michael@0: michael@0: /** michael@0: * Holds a list of all the local files available on this data transfer. michael@0: * A dataTransfer containing no files will return an empty list, and an michael@0: * invalid index access on the resulting file list will return null. michael@0: */ michael@0: readonly attribute nsIDOMFileList files; michael@0: michael@0: /** michael@0: * Holds a list of the format types of the data that is stored for the first michael@0: * item, in the same order the data was added. An empty list will be michael@0: * returned if no data was added. michael@0: */ michael@0: readonly attribute nsISupports types; michael@0: michael@0: /** michael@0: * Remove the data associated with a given format. If format is empty or not michael@0: * specified, the data associated with all formats is removed. If data for michael@0: * the specified format does not exist, or the data transfer contains no michael@0: * data, this method will have no effect. michael@0: */ michael@0: void clearData([optional] in DOMString format); michael@0: michael@0: /** michael@0: * Set the data for a given format. If data for the format does not exist, michael@0: * it is added at the end, such that the last item in the types list will be michael@0: * the new format. If data for the format already exists, the existing data michael@0: * is replaced in the same position. That is, the order of the types list is michael@0: * not changed. michael@0: * michael@0: * @throws NS_ERROR_NULL_POINTER if the data is null michael@0: */ michael@0: void setData(in DOMString format, in DOMString data); michael@0: michael@0: /** michael@0: * Retrieves the data for a given format, or an empty string if data for michael@0: * that format does not exist or the data transfer contains no data. michael@0: */ michael@0: DOMString getData(in DOMString format); michael@0: michael@0: /** michael@0: * Set the image to be used for dragging if a custom one is desired. Most of michael@0: * the time, this would not be set, as a default image is created from the michael@0: * node that was dragged. michael@0: * michael@0: * If the node is an HTML img element, an HTML canvas element or a XUL image michael@0: * element, the image data is used. Otherwise, image should be a visible michael@0: * node and the drag image will be created from this. If image is null, any michael@0: * custom drag image is cleared and the default is used instead. michael@0: * michael@0: * The coordinates specify the offset into the image where the mouse cursor michael@0: * should be. To center the image for instance, use values that are half the michael@0: * width and height. michael@0: * michael@0: * @param image a node to use michael@0: * @param x the horizontal offset michael@0: * @param y the vertical offset michael@0: * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified michael@0: */ michael@0: void setDragImage(in nsIDOMElement image, in long x, in long y); michael@0: michael@0: /* michael@0: * Set the drag source. Usually you would not change this, but it will michael@0: * affect which node the drag and dragend events are fired at. The michael@0: * default target is the node that was dragged. michael@0: * michael@0: * @param element drag source to use michael@0: * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified michael@0: */ michael@0: void addElement(in nsIDOMElement element); michael@0: michael@0: /** michael@0: * The number of items being dragged. michael@0: */ michael@0: readonly attribute unsigned long mozItemCount; michael@0: michael@0: /** michael@0: * Sets the drag cursor state. Primarily used to control the cursor during michael@0: * tab drags, but could be expanded to other uses. XXX Currently implemented michael@0: * on Win32 only. michael@0: * michael@0: * Possible values: michael@0: * auto - use default system behavior. michael@0: * default - set the cursor to an arrow during the drag operation. michael@0: * michael@0: * Values other than 'default' are indentical to setting mozCursor to michael@0: * 'auto'. michael@0: */ michael@0: attribute DOMString mozCursor; michael@0: michael@0: /** michael@0: * Holds a list of the format types of the data that is stored for an item michael@0: * at the specified index. If the index is not in the range from 0 to michael@0: * itemCount - 1, an empty string list is returned. michael@0: */ michael@0: nsISupports mozTypesAt(in unsigned long index); michael@0: michael@0: /** michael@0: * Remove the data associated with the given format for an item at the michael@0: * specified index. The index is in the range from zero to itemCount - 1. michael@0: * michael@0: * If the last format for the item is removed, the entire item is removed, michael@0: * reducing the itemCount by one. michael@0: * michael@0: * If format is empty, then the data associated with all formats is removed. michael@0: * If the format is not found, then this method has no effect. michael@0: * michael@0: * @param format the format to remove michael@0: * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount michael@0: * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified michael@0: */ michael@0: void mozClearDataAt(in DOMString format, in unsigned long index); michael@0: michael@0: /* michael@0: * A data transfer may store multiple items, each at a given zero-based michael@0: * index. setDataAt may only be called with an index argument less than michael@0: * itemCount in which case an existing item is modified, or equal to michael@0: * itemCount in which case a new item is added, and the itemCount is michael@0: * incremented by one. michael@0: * michael@0: * Data should be added in order of preference, with the most specific michael@0: * format added first and the least specific format added last. If data of michael@0: * the given format already exists, it is replaced in the same position as michael@0: * the old data. michael@0: * michael@0: * The data should be either a string, a primitive boolean or number type michael@0: * (which will be converted into a string) or an nsISupports. michael@0: * michael@0: * @param format the format to add michael@0: * @param data the data to add michael@0: * @throws NS_ERROR_NULL_POINTER if the data is null michael@0: * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater than itemCount michael@0: * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified michael@0: */ michael@0: void mozSetDataAt(in DOMString format, in nsIVariant data, in unsigned long index); michael@0: michael@0: /** michael@0: * Retrieve the data associated with the given format for an item at the michael@0: * specified index, or null if it does not exist. The index should be in the michael@0: * range from zero to itemCount - 1. michael@0: * michael@0: * @param format the format of the data to look up michael@0: * @returns the data of the given format, or null if it doesn't exist. michael@0: * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount michael@0: */ michael@0: nsIVariant mozGetDataAt(in DOMString format, in unsigned long index); michael@0: michael@0: /** michael@0: * Will be true when the user has cancelled the drag (typically by pressing michael@0: * Escape) and when the drag has been cancelled unexpectedly. This will be michael@0: * false otherwise, including when the drop has been rejected by its target. michael@0: * This property is only relevant for the dragend event. michael@0: */ michael@0: readonly attribute boolean mozUserCancelled; michael@0: michael@0: /** michael@0: * The node that the mouse was pressed over to begin the drag. For external michael@0: * drags, or if the caller cannot access this node, this will be null. michael@0: */ michael@0: readonly attribute nsIDOMNode mozSourceNode; michael@0: michael@0: /* michael@0: * Integer version of dropEffect, set to one of the constants in nsIDragService. michael@0: */ michael@0: [noscript] attribute unsigned long dropEffectInt; michael@0: michael@0: /* michael@0: * Integer version of effectAllowed, set to one or a combination of the michael@0: * constants in nsIDragService. michael@0: */ michael@0: [noscript] attribute unsigned long effectAllowedInt; michael@0: };