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