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
16interface Element : Node {
17  [Constant]
18  readonly attribute DOMString? namespaceURI;
19  [Constant]
20  readonly attribute DOMString? prefix;
21  [Constant]
22  readonly attribute DOMString localName;
23
24  // Not [Constant] because it depends on which document we're in
25  [Pure]
26  readonly attribute DOMString tagName;
27
28  [CEReactions, Pure]
29           attribute DOMString id;
30  [CEReactions, Pure]
31           attribute DOMString className;
32  [Constant, PutForwards=value]
33  readonly attribute DOMTokenList classList;
34
35  [SameObject]
36  readonly attribute NamedNodeMap attributes;
37  [Pure]
38  sequence<DOMString> getAttributeNames();
39  [Pure]
40  DOMString? getAttribute(DOMString name);
41  [Pure]
42  DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
43  [CEReactions, NeedsSubjectPrincipal=NonSystem, Throws]
44  boolean toggleAttribute(DOMString name, optional boolean force);
45  [CEReactions, NeedsSubjectPrincipal=NonSystem, Throws]
46  void setAttribute(DOMString name, DOMString value);
47  [CEReactions, NeedsSubjectPrincipal=NonSystem, Throws]
48  void setAttributeNS(DOMString? namespace, DOMString name, DOMString value);
49  [CEReactions, Throws]
50  void removeAttribute(DOMString name);
51  [CEReactions, Throws]
52  void removeAttributeNS(DOMString? namespace, DOMString localName);
53  [Pure]
54  boolean hasAttribute(DOMString name);
55  [Pure]
56  boolean hasAttributeNS(DOMString? namespace, DOMString localName);
57  [Pure]
58  boolean hasAttributes();
59
60  [Throws, Pure]
61  Element? closest(DOMString selector);
62
63  [Throws, Pure]
64  boolean matches(DOMString selector);
65  [Throws, Pure, BinaryName="matches"]
66  boolean webkitMatchesSelector(DOMString selector);
67
68  [Pure]
69  HTMLCollection getElementsByTagName(DOMString localName);
70  [Throws, Pure]
71  HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
72  [Pure]
73  HTMLCollection getElementsByClassName(DOMString classNames);
74  [ChromeOnly, Pure]
75  sequence<Element> getElementsWithGrid();
76
77  [CEReactions, Throws, Pure]
78  Element? insertAdjacentElement(DOMString where, Element element); // historical
79
80  [Throws]
81  void insertAdjacentText(DOMString where, DOMString data); // historical
82
83  /**
84   * The ratio of font-size-inflated text font size to computed font
85   * size for this element. This will query the element for its primary frame,
86   * and then use this to get font size inflation information about the frame.
87   * This will be 1.0 if font size inflation is not enabled, and -1.0 if an
88   * error occurred during the retrieval of the font size inflation.
89   *
90   * @note The font size inflation ratio that is returned is actually the
91   *       font size inflation data for the element's _primary frame_, not the
92   *       element itself, but for most purposes, this should be sufficient.
93   */
94  [ChromeOnly]
95  readonly attribute float fontSizeInflation;
96
97  // Selectors API
98
99  // Pointer events methods.
100  [Throws, Pref="dom.w3c_pointer_events.enabled"]
101  void setPointerCapture(long pointerId);
102
103  [Throws, Pref="dom.w3c_pointer_events.enabled"]
104  void releasePointerCapture(long pointerId);
105
106  [Pref="dom.w3c_pointer_events.enabled"]
107  boolean hasPointerCapture(long pointerId);
108
109  // Proprietary extensions
110  /**
111   * Set this during a mousedown event to grab and retarget all mouse events
112   * to this element until the mouse button is released or releaseCapture is
113   * called. If retargetToElement is true, then all events are targetted at
114   * this element. If false, events can also fire at descendants of this
115   * element.
116   *
117   */
118  void setCapture(optional boolean retargetToElement = false);
119
120  /**
121   * If this element has captured the mouse, release the capture. If another
122   * element has captured the mouse, this method has no effect.
123   */
124  void releaseCapture();
125
126  /*
127   * Chrome-only version of setCapture that works outside of a mousedown event.
128   */
129  [ChromeOnly]
130  void setCaptureAlways(optional boolean retargetToElement = false);
131
132  // Obsolete methods.
133  Attr? getAttributeNode(DOMString name);
134  [CEReactions, Throws]
135  Attr? setAttributeNode(Attr newAttr);
136  [CEReactions, Throws]
137  Attr? removeAttributeNode(Attr oldAttr);
138  Attr? getAttributeNodeNS(DOMString? namespaceURI, DOMString localName);
139  [CEReactions, Throws]
140  Attr? setAttributeNodeNS(Attr newAttr);
141
142  [ChromeOnly]
143  /**
144   * Scrolls the element by (dx, dy) CSS pixels without doing any
145   * layout flushing.
146   */
147  boolean scrollByNoFlush(long dx, long dy);
148
149  // Support reporting of Flexbox properties
150  /**
151   * If this element has a display:flex or display:inline-flex style,
152   * this property returns an object with computed values for flex
153   * properties, as well as a property that exposes the flex lines
154   * in this container.
155   */
156  [ChromeOnly, Pure]
157  Flex? getAsFlexContainer();
158
159  // Support reporting of Grid properties
160  /**
161   * If this element has a display:grid or display:inline-grid style,
162   * this property returns an object with computed values for grid
163   * tracks and lines.
164   */
165  [ChromeOnly, Pure]
166  sequence<Grid> getGridFragments();
167
168  [ChromeOnly]
169  DOMMatrixReadOnly getTransformToAncestor(Element ancestor);
170  [ChromeOnly]
171  DOMMatrixReadOnly getTransformToParent();
172  [ChromeOnly]
173  DOMMatrixReadOnly getTransformToViewport();
174};
175
176// http://dev.w3.org/csswg/cssom-view/
177enum ScrollLogicalPosition { "start", "center", "end", "nearest" };
178dictionary ScrollIntoViewOptions : ScrollOptions {
179  ScrollLogicalPosition block = "start";
180  ScrollLogicalPosition inline = "nearest";
181};
182
183// http://dev.w3.org/csswg/cssom-view/#extensions-to-the-element-interface
184partial interface Element {
185  DOMRectList getClientRects();
186  DOMRect getBoundingClientRect();
187
188  // scrolling
189  void scrollIntoView(optional (boolean or ScrollIntoViewOptions) arg);
190  // None of the CSSOM attributes are [Pure], because they flush
191           attribute long scrollTop;   // scroll on setting
192           attribute long scrollLeft;  // scroll on setting
193  readonly attribute long scrollWidth;
194  readonly attribute long scrollHeight;
195
196  void scroll(unrestricted double x, unrestricted double y);
197  void scroll(optional ScrollToOptions options);
198  void scrollTo(unrestricted double x, unrestricted double y);
199  void scrollTo(optional ScrollToOptions options);
200  void scrollBy(unrestricted double x, unrestricted double y);
201  void scrollBy(optional ScrollToOptions options);
202
203  readonly attribute long clientTop;
204  readonly attribute long clientLeft;
205  readonly attribute long clientWidth;
206  readonly attribute long clientHeight;
207};
208
209// http://domparsing.spec.whatwg.org/#extensions-to-the-element-interface
210partial interface Element {
211  [CEReactions, SetterNeedsSubjectPrincipal=NonSystem, Pure, SetterThrows, GetterCanOOM, TreatNullAs=EmptyString]
212  attribute DOMString innerHTML;
213  [CEReactions, Pure,SetterThrows,TreatNullAs=EmptyString]
214  attribute DOMString outerHTML;
215  [CEReactions, Throws]
216  void insertAdjacentHTML(DOMString position, DOMString text);
217};
218
219// http://www.w3.org/TR/selectors-api/#interface-definitions
220partial interface Element {
221  [Throws, Pure]
222  Element?  querySelector(DOMString selectors);
223  [Throws, Pure]
224  NodeList  querySelectorAll(DOMString selectors);
225};
226
227// https://dom.spec.whatwg.org/#dictdef-shadowrootinit
228dictionary ShadowRootInit {
229  required ShadowRootMode mode;
230};
231
232// https://dom.spec.whatwg.org/#element
233partial interface Element {
234  // Shadow DOM v1
235  [Throws, Func="nsDocument::IsShadowDOMEnabled"]
236  ShadowRoot attachShadow(ShadowRootInit shadowRootInitDict);
237  [BinaryName="shadowRootByMode", Func="nsDocument::IsShadowDOMEnabled"]
238  readonly attribute ShadowRoot? shadowRoot;
239
240  [ChromeOnly, Func="nsDocument::IsShadowDOMEnabled", BinaryName="shadowRoot"]
241  readonly attribute ShadowRoot? openOrClosedShadowRoot;
242
243  [BinaryName="assignedSlotByMode", Func="nsDocument::IsShadowDOMEnabled"]
244  readonly attribute HTMLSlotElement? assignedSlot;
245  [CEReactions, Unscopable, SetterThrows, Func="nsDocument::IsShadowDOMEnabled"]
246           attribute DOMString slot;
247};
248
249Element includes ChildNode;
250Element includes NonDocumentTypeChildNode;
251Element includes ParentNode;
252Element includes Animatable;
253Element includes GeometryUtils;
254
255// https://fullscreen.spec.whatwg.org/#api
256partial interface Element {
257  [Throws, Func="nsDocument::IsUnprefixedFullscreenEnabled", NeedsCallerType]
258  void requestFullscreen();
259};
260
261// https://w3c.github.io/pointerlock/#extensions-to-the-element-interface
262partial interface Element {
263  [NeedsCallerType]
264  void requestPointerLock();
265};
266