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 [Exposed=Window]
  17 interface Element : Node {
  18   [Constant]
  19   readonly attribute DOMString? namespaceURI;
  20   [Constant]
  21   readonly attribute DOMString? prefix;
  22   [Constant]
  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   [CEReactions, Pure]
  30            attribute DOMString id;
  31   [CEReactions, Pure]
  32            attribute DOMString className;
  33   [Constant, PutForwards=value]
  34   readonly attribute DOMTokenList classList;
  35
  36   // https://drafts.csswg.org/css-shadow-parts/#idl
  37   [SameObject, PutForwards=value]
  38   readonly attribute DOMTokenList part;
  39
  40   [SameObject]
  41   readonly attribute NamedNodeMap attributes;
  42   [Pure]
  43   sequence<DOMString> getAttributeNames();
  44   [Pure]
  45   DOMString? getAttribute(DOMString name);
  46   [Pure]
  47   DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
  48   [CEReactions, NeedsSubjectPrincipal=NonSystem, Throws]
  49   boolean toggleAttribute(DOMString name, optional boolean force);
  50   [CEReactions, NeedsSubjectPrincipal=NonSystem, Throws]
  51   void setAttribute(DOMString name, DOMString value);
  52   [CEReactions, NeedsSubjectPrincipal=NonSystem, Throws]
  53   void setAttributeNS(DOMString? namespace, DOMString name, DOMString value);
  54   [CEReactions, Throws]
  55   void removeAttribute(DOMString name);
  56   [CEReactions, Throws]
  57   void removeAttributeNS(DOMString? namespace, DOMString localName);
  58   [Pure]
  59   boolean hasAttribute(DOMString name);
  60   [Pure]
  61   boolean hasAttributeNS(DOMString? namespace, DOMString localName);
  62   [Pure]
  63   boolean hasAttributes();
  64
  65   [Throws, Pure]
  66   Element? closest(DOMString selector);
  67
  68   [Throws, Pure]
  69   boolean matches(DOMString selector);
  70   [Throws, Pure, BinaryName="matches"]
  71   boolean webkitMatchesSelector(DOMString selector);
  72
  73   [Pure]
  74   HTMLCollection getElementsByTagName(DOMString localName);
  75   [Throws, Pure]
  76   HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  77   [Pure]
  78   HTMLCollection getElementsByClassName(DOMString classNames);
  79
  80   [CEReactions, Throws]
  81   Element? insertAdjacentElement(DOMString where, Element element); // historical
  82
  83   [Throws]
  84   void insertAdjacentText(DOMString where, DOMString data); // historical
  85
  86   /**
  87    * The ratio of font-size-inflated text font size to computed font
  88    * size for this element. This will query the element for its primary frame,
  89    * and then use this to get font size inflation information about the frame.
  90    * This will be 1.0 if font size inflation is not enabled, and -1.0 if an
  91    * error occurred during the retrieval of the font size inflation.
  92    *
  93    * @note The font size inflation ratio that is returned is actually the
  94    *       font size inflation data for the element's _primary frame_, not the
  95    *       element itself, but for most purposes, this should be sufficient.
  96    */
  97   [ChromeOnly]
  98   readonly attribute float fontSizeInflation;
  99
 100   /**
 101    * Returns the pseudo-element string if this element represents a
 102    * pseudo-element, or null otherwise.
 103    */
 104   [ChromeOnly]
 105   readonly attribute DOMString? implementedPseudoElement;
 106
 107   // Selectors API
 108   /**
 109    * Returns whether this element would be selected by the given selector
 110    * string.
 111    *
 112    * See <http://dev.w3.org/2006/webapi/selectors-api2/#matchesselector>
 113    */
 114   [Throws, Pure, BinaryName="matches"]
 115   boolean mozMatchesSelector(DOMString selector);
 116
 117   // Pointer events methods.
 118   [Throws, Pref="dom.w3c_pointer_events.enabled"]
 119   void setPointerCapture(long pointerId);
 120
 121   [Throws, Pref="dom.w3c_pointer_events.enabled"]
 122   void releasePointerCapture(long pointerId);
 123
 124   [Pref="dom.w3c_pointer_events.enabled"]
 125   boolean hasPointerCapture(long pointerId);
 126
 127   // Proprietary extensions
 128   /**
 129    * Set this during a mousedown event to grab and retarget all mouse events
 130    * to this element until the mouse button is released or releaseCapture is
 131    * called. If retargetToElement is true, then all events are targetted at
 132    * this element. If false, events can also fire at descendants of this
 133    * element.
 134    *
 135    */
 136   [UseCounter]
 137   void setCapture(optional boolean retargetToElement = false);
 138
 139   /**
 140    * If this element has captured the mouse, release the capture. If another
 141    * element has captured the mouse, this method has no effect.
 142    */
 143   [UseCounter]
 144   void releaseCapture();
 145
 146   /*
 147    * Chrome-only version of setCapture that works outside of a mousedown event.
 148    */
 149   [ChromeOnly]
 150   void setCaptureAlways(optional boolean retargetToElement = false);
 151
 152   // Mozilla extensions
 153
 154   // Obsolete methods.
 155   Attr? getAttributeNode(DOMString name);
 156   [CEReactions, Throws]
 157   Attr? setAttributeNode(Attr newAttr);
 158   [CEReactions, Throws]
 159   Attr? removeAttributeNode(Attr oldAttr);
 160   Attr? getAttributeNodeNS(DOMString? namespaceURI, DOMString localName);
 161   [CEReactions, Throws]
 162   Attr? setAttributeNodeNS(Attr newAttr);
 163
 164   [Func="nsContentUtils::IsCallerChromeOrElementTransformGettersEnabled"]
 165   DOMMatrixReadOnly getTransformToAncestor(Element ancestor);
 166   [Func="nsContentUtils::IsCallerChromeOrElementTransformGettersEnabled"]
 167   DOMMatrixReadOnly getTransformToParent();
 168   [Func="nsContentUtils::IsCallerChromeOrElementTransformGettersEnabled"]
 169   DOMMatrixReadOnly getTransformToViewport();
 170 };
 171
 172 // https://html.spec.whatwg.org/#focus-management-apis
 173 dictionary FocusOptions {
 174   boolean preventScroll = false;
 175 };
 176
 177 interface mixin HTMLOrForeignElement {
 178   [SameObject] readonly attribute DOMStringMap dataset;
 179   // See bug 1389421
 180   // attribute DOMString nonce; // intentionally no [CEReactions]
 181
 182   // See bug 1575154
 183   // [CEReactions] attribute boolean autofocus;
 184   [CEReactions, SetterThrows, Pure] attribute long tabIndex;
 185   [Throws, NeedsCallerType] void focus(optional FocusOptions options = {});
 186   [Throws] void blur();
 187 };
 188
 189 // https://drafts.csswg.org/cssom/#the-elementcssinlinestyle-mixin
 190 interface mixin ElementCSSInlineStyle {
 191   [SameObject, PutForwards=cssText]
 192   readonly attribute CSSStyleDeclaration style;
 193 };
 194
 195 // http://dev.w3.org/csswg/cssom-view/
 196 enum ScrollLogicalPosition { "start", "center", "end", "nearest" };
 197 dictionary ScrollIntoViewOptions : ScrollOptions {
 198   ScrollLogicalPosition block = "start";
 199   ScrollLogicalPosition inline = "nearest";
 200 };
 201
 202 // http://dev.w3.org/csswg/cssom-view/#extensions-to-the-element-interface
 203 partial interface Element {
 204   DOMRectList getClientRects();
 205   DOMRect getBoundingClientRect();
 206
 207   // scrolling
 208   void scrollIntoView(optional (boolean or ScrollIntoViewOptions) arg = {});
 209   // None of the CSSOM attributes are [Pure], because they flush
 210            attribute long scrollTop;   // scroll on setting
 211            attribute long scrollLeft;  // scroll on setting
 212   readonly attribute long scrollWidth;
 213   readonly attribute long scrollHeight;
 214
 215   void scroll(unrestricted double x, unrestricted double y);
 216   void scroll(optional ScrollToOptions options = {});
 217   void scrollTo(unrestricted double x, unrestricted double y);
 218   void scrollTo(optional ScrollToOptions options = {});
 219   void scrollBy(unrestricted double x, unrestricted double y);
 220   void scrollBy(optional ScrollToOptions options = {});
 221   // mozScrollSnap is used by chrome to perform scroll snapping after the
 222   // user performs actions that may affect scroll position
 223   // mozScrollSnap is deprecated, to be replaced by a web accessible API, such
 224   // as an extension to the ScrollOptions dictionary.  See bug 1137937.
 225   [ChromeOnly] void mozScrollSnap();
 226
 227   readonly attribute long clientTop;
 228   readonly attribute long clientLeft;
 229   readonly attribute long clientWidth;
 230   readonly attribute long clientHeight;
 231
 232   // Mozilla specific stuff
 233   /* The minimum/maximum offset that the element can be scrolled to
 234      (i.e., the value that scrollLeft/scrollTop would be clamped to if they were
 235      set to arbitrarily large values. */
 236   [ChromeOnly] readonly attribute long scrollTopMin;
 237                readonly attribute long scrollTopMax;
 238   [ChromeOnly] readonly attribute long scrollLeftMin;
 239                readonly attribute long scrollLeftMax;
 240 };
 241
 242 // http://domparsing.spec.whatwg.org/#extensions-to-the-element-interface
 243 partial interface Element {
 244   [CEReactions, SetterNeedsSubjectPrincipal=NonSystem, Pure, SetterThrows, GetterCanOOM]
 245   attribute [TreatNullAs=EmptyString] DOMString innerHTML;
 246   [CEReactions, Pure, SetterThrows]
 247   attribute [TreatNullAs=EmptyString] DOMString outerHTML;
 248   [CEReactions, Throws]
 249   void insertAdjacentHTML(DOMString position, DOMString text);
 250 };
 251
 252 // http://www.w3.org/TR/selectors-api/#interface-definitions
 253 partial interface Element {
 254   [Throws, Pure]
 255   Element?  querySelector(DOMString selectors);
 256   [Throws, Pure]
 257   NodeList  querySelectorAll(DOMString selectors);
 258 };
 259
 260 // https://dom.spec.whatwg.org/#dictdef-shadowrootinit
 261 dictionary ShadowRootInit {
 262   required ShadowRootMode mode;
 263 };
 264
 265 // https://dom.spec.whatwg.org/#element
 266 partial interface Element {
 267   // Shadow DOM v1
 268   [Throws, UseCounter]
 269   ShadowRoot attachShadow(ShadowRootInit shadowRootInitDict);
 270   [BinaryName="shadowRootByMode"]
 271   readonly attribute ShadowRoot? shadowRoot;
 272
 273   [Func="Document::IsCallerChromeOrAddon", BinaryName="shadowRoot"]
 274   readonly attribute ShadowRoot? openOrClosedShadowRoot;
 275
 276   [BinaryName="assignedSlotByMode"]
 277   readonly attribute HTMLSlotElement? assignedSlot;
 278
 279   [ChromeOnly, BinaryName="assignedSlot"]
 280   readonly attribute HTMLSlotElement? openOrClosedAssignedSlot;
 281
 282   [CEReactions, Unscopable, SetterThrows]
 283            attribute DOMString slot;
 284 };
 285
 286 Element includes ChildNode;
 287 Element includes NonDocumentTypeChildNode;
 288 Element includes ParentNode;
 289 Element includes Animatable;
 290 Element includes GeometryUtils;
 291 Element includes AccessibilityRole;
 292 Element includes AriaAttributes;
 293
 294 // https://fullscreen.spec.whatwg.org/#api
 295 partial interface Element {
 296   [Throws, NeedsCallerType]
 297   Promise<void> requestFullscreen();
 298   [Throws, BinaryName="requestFullscreen", NeedsCallerType, Deprecated="MozRequestFullScreenDeprecatedPrefix"]
 299   Promise<void> mozRequestFullScreen();
 300
 301   // Events handlers
 302   attribute EventHandler onfullscreenchange;
 303   attribute EventHandler onfullscreenerror;
 304 };
 305
 306 // https://w3c.github.io/pointerlock/#extensions-to-the-element-interface
 307 partial interface Element {
 308   [NeedsCallerType, Pref="dom.pointer-lock.enabled"]
 309   void requestPointerLock();
 310 };
 311
 312 // Mozilla-specific additions to support devtools
 313 partial interface Element {
 314   // Support reporting of Flexbox properties
 315   /**
 316    * If this element has a display:flex or display:inline-flex style,
 317    * this property returns an object with computed values for flex
 318    * properties, as well as a property that exposes the flex lines
 319    * in this container.
 320    */
 321   [ChromeOnly, Pure]
 322   Flex? getAsFlexContainer();
 323
 324   // Support reporting of Grid properties
 325   /**
 326    * If this element has a display:grid or display:inline-grid style,
 327    * this property returns an object with computed values for grid
 328    * tracks and lines.
 329    */
 330   [ChromeOnly, Pure]
 331   sequence<Grid> getGridFragments();
 332
 333   /**
 334    * Returns whether there are any grid fragments on this element.
 335    */
 336   [ChromeOnly, Pure]
 337   boolean hasGridFragments();
 338
 339   /**
 340    * Returns a sequence of all the descendent elements of this element
 341    * that have display:grid or display:inline-grid style and generate
 342    * a frame.
 343    */
 344   [ChromeOnly, Pure]
 345   sequence<Element> getElementsWithGrid();
 346
 347   /**
 348    * Set attribute on the Element with a customized Content-Security-Policy
 349    * appropriate to devtools, which includes:
 350    * style-src 'unsafe-inline'
 351    */
 352   [ChromeOnly, CEReactions, Throws]
 353   void setAttributeDevtools(DOMString name, DOMString value);
 354   [ChromeOnly, CEReactions, Throws]
 355   void setAttributeDevtoolsNS(DOMString? namespace, DOMString name, DOMString value);
 356
 357   /**
 358    * Provide a direct way to determine if this Element has visible
 359    * scrollbars. Flushes layout.
 360    */
 361   [ChromeOnly]
 362   readonly attribute boolean hasVisibleScrollbars;
 363 };
 364
 365 // These variables are used in vtt.js, they are used for positioning vtt cues.
 366 partial interface Element {
 367   // These two attributes are a double version of the clientHeight and the
 368   // clientWidth.
 369   [ChromeOnly]
 370   readonly attribute double clientHeightDouble;
 371   [ChromeOnly]
 372   readonly attribute double clientWidthDouble;
 373   // This attribute returns the block size of the first line box under the different
 374   // writing directions. If the direction is horizontal, it represents box's
 375   // height. If the direction is vertical, it represents box's width.
 376   [ChromeOnly]
 377   readonly attribute double firstLineBoxBSize;
 378 };