dom/webidl/DataTransfer.webidl

   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
  10 [ChromeConstructor(DOMString eventType, boolean isExternal)]
  11 interface DataTransfer {
  12            attribute DOMString dropEffect;
  13            attribute DOMString effectAllowed;
  14
  15   //readonly attribute DataTransferItemList items;
  16
  17   [Throws]
  18   void setDragImage(Element image, long x, long y);
  19
  20   readonly attribute DOMStringList types;
  21   [Throws]
  22   DOMString getData(DOMString format);
  23   [Throws]
  24   void setData(DOMString format, DOMString data);
  25   [Throws]
  26   void clearData(optional DOMString format);
  27   [Throws]
  28   readonly attribute FileList? files;
  29 };
  30
  31 // Mozilla specific stuff
  32 partial interface DataTransfer {
  33   /*
  34    * Set the drag source. Usually you would not change this, but it will
  35    * affect which node the drag and dragend events are fired at. The
  36    * default target is the node that was dragged.
  37    *
  38    * @param element drag source to use
  39    * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
  40    */
  41   [Throws]
  42   void addElement(Element element);
  43
  44   /**
  45    * The number of items being dragged.
  46    */
  47   readonly attribute unsigned long mozItemCount;
  48
  49   /**
  50    * Sets the drag cursor state. Primarily used to control the cursor during
  51    * tab drags, but could be expanded to other uses. XXX Currently implemented
  52    * on Win32 only.
  53    *
  54    * Possible values:
  55    *  auto - use default system behavior.
  56    *  default - set the cursor to an arrow during the drag operation.
  57    *
  58    * Values other than 'default' are indentical to setting mozCursor to
  59    * 'auto'.
  60    */
  61   attribute DOMString mozCursor;
  62
  63   /**
  64    * Holds a list of the format types of the data that is stored for an item
  65    * at the specified index. If the index is not in the range from 0 to
  66    * itemCount - 1, an empty string list is returned.
  67    */
  68   [Throws]
  69   DOMStringList mozTypesAt(unsigned long index);
  70
  71   /**
  72    * Remove the data associated with the given format for an item at the
  73    * specified index. The index is in the range from zero to itemCount - 1.
  74    *
  75    * If the last format for the item is removed, the entire item is removed,
  76    * reducing the itemCount by one.
  77    *
  78    * If format is empty, then the data associated with all formats is removed.
  79    * If the format is not found, then this method has no effect.
  80    *
  81    * @param format the format to remove
  82    * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount
  83    * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
  84    */
  85   [Throws]
  86   void mozClearDataAt(DOMString format, unsigned long index);
  87
  88   /*
  89    * A data transfer may store multiple items, each at a given zero-based
  90    * index. setDataAt may only be called with an index argument less than
  91    * itemCount in which case an existing item is modified, or equal to
  92    * itemCount in which case a new item is added, and the itemCount is
  93    * incremented by one.
  94    *
  95    * Data should be added in order of preference, with the most specific
  96    * format added first and the least specific format added last. If data of
  97    * the given format already exists, it is replaced in the same position as
  98    * the old data.
  99    *
 100    * The data should be either a string, a primitive boolean or number type
 101    * (which will be converted into a string) or an nsISupports.
 102    *
 103    * @param format the format to add
 104    * @param data the data to add
 105    * @throws NS_ERROR_NULL_POINTER if the data is null
 106    * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater than itemCount
 107    * @throws NO_MODIFICATION_ALLOWED_ERR if the item cannot be modified
 108    */
 109   [Throws]
 110   void mozSetDataAt(DOMString format, any data, unsigned long index);
 111
 112   /**
 113    * Retrieve the data associated with the given format for an item at the
 114    * specified index, or null if it does not exist. The index should be in the
 115    * range from zero to itemCount - 1.
 116    *
 117    * @param format the format of the data to look up
 118    * @returns the data of the given format, or null if it doesn't exist.
 119    * @throws NS_ERROR_DOM_INDEX_SIZE_ERR if index is greater or equal than itemCount
 120    */
 121   [Throws]
 122   any mozGetDataAt(DOMString format, unsigned long index);
 123
 124   /**
 125    * Will be true when the user has cancelled the drag (typically by pressing
 126    * Escape) and when the drag has been cancelled unexpectedly.  This will be
 127    * false otherwise, including when the drop has been rejected by its target.
 128    * This property is only relevant for the dragend event.
 129    */
 130   readonly attribute boolean mozUserCancelled;
 131
 132   /**
 133    * The node that the mouse was pressed over to begin the drag. For external
 134    * drags, or if the caller cannot access this node, this will be null.
 135    */
 136   readonly attribute Node? mozSourceNode;
 137 };