michael@0: /* -*- Mode: IDL; 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 file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/.
michael@0:  *
michael@0:  * The origin of this IDL file is:
michael@0:  * http://www.whatwg.org/specs/web-apps/current-work/#the-datatransfer-interface
michael@0:  */
michael@0: 
michael@0: [ChromeConstructor(DOMString eventType, boolean isExternal)]
michael@0: interface DataTransfer {
michael@0:            attribute DOMString dropEffect;
michael@0:            attribute DOMString effectAllowed;
michael@0: 
michael@0:   //readonly attribute DataTransferItemList items;
michael@0: 
michael@0:   [Throws]
michael@0:   void setDragImage(Element image, long x, long y);
michael@0: 
michael@0:   readonly attribute DOMStringList types;
michael@0:   [Throws]
michael@0:   DOMString getData(DOMString format);
michael@0:   [Throws]
michael@0:   void setData(DOMString format, DOMString data);
michael@0:   [Throws]
michael@0:   void clearData(optional DOMString format);
michael@0:   [Throws]
michael@0:   readonly attribute FileList? files;
michael@0: };
michael@0: 
michael@0: // Mozilla specific stuff
michael@0: partial interface DataTransfer {
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:   [Throws]
michael@0:   void addElement(Element 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:   [Throws]
michael@0:   DOMStringList mozTypesAt(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:   [Throws]
michael@0:   void mozClearDataAt(DOMString format, 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:   [Throws]
michael@0:   void mozSetDataAt(DOMString format, any data, 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:   [Throws]
michael@0:   any mozGetDataAt(DOMString format, 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 Node? mozSourceNode;
michael@0: };