dom/webidl/Element.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://dom.spec.whatwg.org/#element and
   8  * http://domparsing.spec.whatwg.org/ and
   9  * http://dev.w3.org/csswg/cssom-view/ and
  10  * http://www.w3.org/TR/selectors-api/
  11  *
  12  * Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C
  13  * liability, trademark and document use rules apply.
  14  */
  15
  16 interface Element : Node {
  17 /*
  18   We haven't moved these from Node to Element like the spec wants.
  19
  20   [Throws]
  21   readonly attribute DOMString? namespaceURI;
  22   readonly attribute DOMString? prefix;
  23   readonly attribute DOMString localName;
  24 */
  25   // Not [Constant] because it depends on which document we're in
  26   [Pure]
  27   readonly attribute DOMString tagName;
  28
  29   [Pure]
  30            attribute DOMString id;
  31   [Pure]
  32            attribute DOMString className;
  33   [Constant]
  34   readonly attribute DOMTokenList classList;
  35
  36   [SameObject]
  37   readonly attribute NamedNodeMap attributes;
  38   [Pure]
  39   DOMString? getAttribute(DOMString name);
  40   [Pure]
  41   DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
  42   [Throws]
  43   void setAttribute(DOMString name, DOMString value);
  44   [Throws]
  45   void setAttributeNS(DOMString? namespace, DOMString name, DOMString value);
  46   [Throws]
  47   void removeAttribute(DOMString name);
  48   [Throws]
  49   void removeAttributeNS(DOMString? namespace, DOMString localName);
  50   [Pure]
  51   boolean hasAttribute(DOMString name);
  52   [Pure]
  53   boolean hasAttributeNS(DOMString? namespace, DOMString localName);
  54
  55   [Throws, Pure]
  56   boolean matches(DOMString selector);
  57
  58   [Pure]
  59   HTMLCollection getElementsByTagName(DOMString localName);
  60   [Throws, Pure]
  61   HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  62   [Pure]
  63   HTMLCollection getElementsByClassName(DOMString classNames);
  64
  65   /**
  66    * The ratio of font-size-inflated text font size to computed font
  67    * size for this element. This will query the element for its primary frame,
  68    * and then use this to get font size inflation information about the frame.
  69    * This will be 1.0 if font size inflation is not enabled, and -1.0 if an
  70    * error occurred during the retrieval of the font size inflation.
  71    *
  72    * @note The font size inflation ratio that is returned is actually the
  73    *       font size inflation data for the element's _primary frame_, not the
  74    *       element itself, but for most purposes, this should be sufficient.
  75    */
  76   [ChromeOnly]
  77   readonly attribute float fontSizeInflation;
  78
  79   // Mozilla specific stuff
  80   [Pure]
  81            attribute EventHandler onwheel;
  82
  83   // Selectors API
  84   /**
  85    * Returns whether this element would be selected by the given selector
  86    * string.
  87    *
  88    * See <http://dev.w3.org/2006/webapi/selectors-api2/#matchesselector>
  89    */
  90   [Throws, Pure]
  91   boolean mozMatchesSelector(DOMString selector);
  92
  93   // Pointer events methods.
  94   [Throws, Pref="dom.w3c_pointer_events.enabled"]
  95   void setPointerCapture(long pointerId);
  96
  97   [Throws, Pref="dom.w3c_pointer_events.enabled"]
  98   void releasePointerCapture(long pointerId);
  99
 100   // Proprietary extensions
 101   /**
 102    * Set this during a mousedown event to grab and retarget all mouse events
 103    * to this element until the mouse button is released or releaseCapture is
 104    * called. If retargetToElement is true, then all events are targetted at
 105    * this element. If false, events can also fire at descendants of this
 106    * element.
 107    *
 108    */
 109   void setCapture(optional boolean retargetToElement = false);
 110
 111   /**
 112    * If this element has captured the mouse, release the capture. If another
 113    * element has captured the mouse, this method has no effect.
 114    */
 115   void releaseCapture();
 116
 117   // Mozilla extensions
 118   /**
 119    * Requests that this element be made the full-screen element, as per the DOM
 120    * full-screen api.
 121    *
 122    * @see <https://wiki.mozilla.org/index.php?title=Gecko:FullScreenAPI>
 123    */
 124   void mozRequestFullScreen();
 125
 126   /**
 127    * Requests that this element be made the pointer-locked element, as per the DOM
 128    * pointer lock api.
 129    *
 130    * @see <http://dvcs.w3.org/hg/pointerlock/raw-file/default/index.html>
 131    */
 132   void mozRequestPointerLock();
 133
 134   // Obsolete methods.
 135   Attr? getAttributeNode(DOMString name);
 136   [Throws]
 137   Attr? setAttributeNode(Attr newAttr);
 138   [Throws]
 139   Attr? removeAttributeNode(Attr oldAttr);
 140   Attr? getAttributeNodeNS(DOMString? namespaceURI, DOMString localName);
 141   [Throws]
 142   Attr? setAttributeNodeNS(Attr newAttr);
 143
 144   [ChromeOnly]
 145   /**
 146    * Scrolls the element by (dx, dy) CSS pixels without doing any
 147    * layout flushing.
 148    */
 149   boolean scrollByNoFlush(long dx, long dy);
 150 };
 151
 152 // http://dev.w3.org/csswg/cssom-view/#extensions-to-the-element-interface
 153 partial interface Element {
 154   DOMRectList getClientRects();
 155   DOMRect getBoundingClientRect();
 156
 157   // scrolling
 158   void scrollIntoView();
 159   void scrollIntoView(boolean top, optional ScrollOptions options);
 160   // None of the CSSOM attributes are [Pure], because they flush
 161            attribute long scrollTop;   // scroll on setting
 162            attribute long scrollLeft;  // scroll on setting
 163   readonly attribute long scrollWidth;
 164   readonly attribute long scrollHeight;
 165
 166   readonly attribute long clientTop;
 167   readonly attribute long clientLeft;
 168   readonly attribute long clientWidth;
 169   readonly attribute long clientHeight;
 170
 171   // Mozilla specific stuff
 172   /* The maximum offset that the element can be scrolled to
 173      (i.e., the value that scrollLeft/scrollTop would be clamped to if they were
 174      set to arbitrarily large values. */
 175   readonly attribute long scrollTopMax;
 176   readonly attribute long scrollLeftMax;
 177 };
 178
 179 // http://dvcs.w3.org/hg/undomanager/raw-file/tip/undomanager.html
 180 partial interface Element {
 181   [Pref="dom.undo_manager.enabled"]
 182   readonly attribute UndoManager? undoManager;
 183   [SetterThrows,Pref="dom.undo_manager.enabled"]
 184   attribute boolean undoScope;
 185 };
 186
 187 // http://domparsing.spec.whatwg.org/#extensions-to-the-element-interface
 188 partial interface Element {
 189   [Pure,SetterThrows,TreatNullAs=EmptyString]
 190   attribute DOMString innerHTML;
 191   [Pure,SetterThrows,TreatNullAs=EmptyString]
 192   attribute DOMString outerHTML;
 193   [Throws]
 194   void insertAdjacentHTML(DOMString position, DOMString text);
 195 };
 196
 197 // http://www.w3.org/TR/selectors-api/#interface-definitions
 198 partial interface Element {
 199   [Throws, Pure]
 200   Element?  querySelector(DOMString selectors);
 201   [Throws, Pure]
 202   NodeList  querySelectorAll(DOMString selectors);
 203 };
 204
 205 // http://w3c.github.io/webcomponents/spec/shadow/#extensions-to-element-interface
 206 partial interface Element {
 207   [Throws,Func="nsDocument::IsWebComponentsEnabled"]
 208   ShadowRoot createShadowRoot();
 209   [Func="nsDocument::IsWebComponentsEnabled"]
 210   NodeList getDestinationInsertionPoints();
 211   [Func="nsDocument::IsWebComponentsEnabled"]
 212   readonly attribute ShadowRoot? shadowRoot;
 213 };
 214
 215 Element implements ChildNode;
 216 Element implements NonDocumentTypeChildNode;
 217 Element implements ParentNode;
 218 Element implements Animatable;