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