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