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/.
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/
11 * Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C
12 * liability, trademark and document use rules apply.
18 InstrumentedProps=(computedStyleMap,onmousewheel,scrollIntoViewIfNeeded)]
19 interface Element : Node {
21 readonly attribute DOMString? namespaceURI;
23 readonly attribute DOMString? prefix;
25 readonly attribute DOMString localName;
27 // Not [Constant] because it depends on which document we're in
29 readonly attribute DOMString tagName;
32 attribute DOMString id;
34 attribute DOMString className;
35 [Constant, PutForwards=value]
36 readonly attribute DOMTokenList classList;
38 // https://drafts.csswg.org/css-shadow-parts/#idl
39 [SameObject, PutForwards=value]
40 readonly attribute DOMTokenList part;
43 readonly attribute NamedNodeMap attributes;
45 sequence<DOMString> getAttributeNames();
47 DOMString? getAttribute(DOMString name);
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);
57 undefined removeAttribute(DOMString name);
59 undefined removeAttributeNS(DOMString? namespace, DOMString localName);
61 boolean hasAttribute(DOMString name);
63 boolean hasAttributeNS(DOMString? namespace, DOMString localName);
65 boolean hasAttributes();
68 Element? closest(UTF8String selector);
71 boolean matches(UTF8String selector);
72 [Throws, Pure, BinaryName="matches"]
73 boolean webkitMatchesSelector(UTF8String selector);
76 HTMLCollection getElementsByTagName(DOMString localName);
78 HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
80 HTMLCollection getElementsByClassName(DOMString classNames);
83 Element? insertAdjacentElement(DOMString where, Element element); // historical
86 undefined insertAdjacentText(DOMString where, DOMString data); // historical
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.
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.
100 readonly attribute float fontSizeInflation;
103 * Returns the pseudo-element string if this element represents a
104 * pseudo-element, or null otherwise.
107 readonly attribute DOMString? implementedPseudoElement;
111 * Returns whether this element would be selected by the given selector
114 * https://dom.spec.whatwg.org/#dom-element-matches
116 [Throws, Pure, BinaryName="matches"]
117 boolean mozMatchesSelector(UTF8String selector);
119 // Pointer events methods.
121 undefined setPointerCapture(long pointerId);
123 undefined releasePointerCapture(long pointerId);
124 boolean hasPointerCapture(long pointerId);
126 // Proprietary extensions
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
135 [Deprecated=ElementSetCapture, Pref="dom.mouse_capture.enabled"]
136 undefined setCapture(optional boolean retargetToElement = false);
139 * If this element has captured the mouse, release the capture. If another
140 * element has captured the mouse, this method has no effect.
142 [Deprecated=ElementReleaseCapture, Pref="dom.mouse_capture.enabled"]
143 undefined releaseCapture();
146 * Chrome-only version of setCapture that works outside of a mousedown event.
149 undefined setCaptureAlways(optional boolean retargetToElement = false);
151 // Mozilla extensions
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);
163 [Func="nsContentUtils::IsCallerChromeOrElementTransformGettersEnabled"]
164 DOMMatrixReadOnly getTransformToAncestor(Element ancestor);
165 [Func="nsContentUtils::IsCallerChromeOrElementTransformGettersEnabled"]
166 DOMMatrixReadOnly getTransformToParent();
167 [Func="nsContentUtils::IsCallerChromeOrElementTransformGettersEnabled"]
168 DOMMatrixReadOnly getTransformToViewport();
171 // https://html.spec.whatwg.org/#focus-management-apis
172 dictionary FocusOptions {
173 boolean preventScroll = false;
174 boolean focusVisible;
177 interface mixin HTMLOrForeignElement {
178 [SameObject] readonly attribute DOMStringMap dataset;
180 // attribute DOMString nonce; // intentionally no [CEReactions]
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();
188 // https://drafts.csswg.org/cssom/#the-elementcssinlinestyle-mixin
189 interface mixin ElementCSSInlineStyle {
190 [SameObject, PutForwards=cssText]
191 readonly attribute CSSStyleDeclaration style;
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";
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;
210 // https://drafts.csswg.org/cssom-view/#extensions-to-the-element-interface
211 partial interface Element {
212 DOMRectList getClientRects();
213 DOMRect getBoundingClientRect();
215 boolean checkVisibility(optional CheckVisibilityOptions options = {});
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;
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();
239 readonly attribute long clientTop;
240 readonly attribute long clientLeft;
241 readonly attribute long clientWidth;
242 readonly attribute long clientHeight;
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;
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;
259 [Pref="layout.css.zoom.enabled"] readonly attribute double currentCSSZoom;
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);
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;
281 // https://dom.spec.whatwg.org/#element
282 partial interface Element {
285 ShadowRoot attachShadow(ShadowRootInit shadowRootInitDict);
286 [BinaryName="shadowRootByMode"]
287 readonly attribute ShadowRoot? shadowRoot;
289 [Func="Document::IsCallerChromeOrAddon", BinaryName="shadowRoot"]
290 readonly attribute ShadowRoot? openOrClosedShadowRoot;
292 [BinaryName="assignedSlotByMode"]
293 readonly attribute HTMLSlotElement? assignedSlot;
295 [ChromeOnly, BinaryName="assignedSlot"]
296 readonly attribute HTMLSlotElement? openOrClosedAssignedSlot;
298 [CEReactions, Unscopable, SetterThrows]
299 attribute DOMString slot;
302 Element includes ChildNode;
303 Element includes NonDocumentTypeChildNode;
304 Element includes ParentNode;
305 Element includes Animatable;
306 Element includes GeometryUtils;
307 Element includes ARIAMixin;
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();
317 attribute EventHandler onfullscreenchange;
318 attribute EventHandler onfullscreenerror;
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();
327 // Mozilla-specific additions to support devtools
328 partial interface Element {
329 // Support reporting of Flexbox properties
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
337 Flex? getAsFlexContainer();
339 // Support reporting of Grid properties
341 * If this element has a display:grid or display:inline-grid style,
342 * this property returns an object with computed values for grid
346 sequence<Grid> getGridFragments();
349 * Returns whether there are any grid fragments on this element.
352 boolean hasGridFragments();
355 * Returns a sequence of all the descendent elements of this element
356 * that have display:grid or display:inline-grid style and generate
360 sequence<Element> getElementsWithGrid();
363 * Set attribute on the Element with a customized Content-Security-Policy
364 * appropriate to devtools, which includes:
365 * style-src 'unsafe-inline'
367 [ChromeOnly, CEReactions, Throws]
368 undefined setAttributeDevtools(DOMString name, DOMString value);
369 [ChromeOnly, CEReactions, Throws]
370 undefined setAttributeDevtoolsNS(DOMString? namespace, DOMString name, DOMString value);
373 * Provide a direct way to determine if this Element has visible
374 * scrollbars. Flushes layout.
377 readonly attribute boolean hasVisibleScrollbars;
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
385 readonly attribute double clientHeightDouble;
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.
392 readonly attribute double firstLineBoxBSize;
396 // Sanitizer API, https://wicg.github.io/sanitizer-api/
397 dictionary SetHTMLOptions {
398 SanitizerConfig sanitizer;
401 partial interface Element {
402 [SecureContext, UseCounter, Throws, Pref="dom.security.setHTML.enabled"]
403 undefined setHTML(DOMString aInnerHTML, optional SetHTMLOptions options = {});
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);