chromium/src/third_party/blink/renderer/core/dom/element.idl

/*
 * Copyright (C) 2006, 2007, 2009 Apple Inc. All rights reserved.
 * Copyright (C) 2006 Samuel Weinig <sam.weinig@gmail.com>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public License
 * along with this library; see the file COPYING.LIB.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 */

// See
// https://docs.google.com/document/d/1VnvAqeWFG9JFZfgG5evBqrLGDZYRE5w6G5jEDORekPY
// for details.
enum NativeScrollBehavior { "disable-native-scroll", "perform-before-native-scroll", "perform-after-native-scroll" };
callback ScrollStateCallback = void (ScrollState scrollState);

// https://dom.spec.whatwg.org/#interface-element

[
    Exposed=Window
] interface Element : Node {
    readonly attribute DOMString? namespaceURI;
    readonly attribute DOMString? prefix;
    readonly attribute DOMString localName;
    [Affects=Nothing] readonly attribute DOMString tagName;

    [Affects=Nothing, CEReactions, Reflect] attribute DOMString id;
    [Affects=Nothing, CEReactions, Reflect=class] attribute DOMString className;
    [Affects=Nothing, SameObject, PerWorldBindings, PutForwards=value] readonly attribute DOMTokenList classList;
    [Unscopable, CEReactions, Reflect] attribute DOMString slot;

    [Affects=Nothing] boolean hasAttributes();
    [Affects=Nothing, SameObject, PerWorldBindings, ImplementedAs=attributesForBindings] readonly attribute NamedNodeMap attributes;
    [Affects=Nothing] sequence<DOMString> getAttributeNames();
    [Affects=Nothing] DOMString? getAttribute(DOMString name);
    [Affects=Nothing] DOMString? getAttributeNS(DOMString? namespaceURI, DOMString localName);
    [RaisesException, CEReactions] void setAttribute(DOMString name, TrustedString value);
    [RaisesException, CEReactions] void setAttributeNS(DOMString? namespaceURI, DOMString name, TrustedString value);
    [CEReactions] void removeAttribute(DOMString name);
    [CEReactions] void removeAttributeNS(DOMString? namespaceURI, DOMString localName);
    [RaisesException, CEReactions] boolean toggleAttribute(DOMString qualifiedName, optional boolean force);
    [Affects=Nothing] boolean hasAttribute(DOMString name);
    [Affects=Nothing] boolean hasAttributeNS(DOMString? namespaceURI, DOMString localName);

    Attr? getAttributeNode(DOMString name);
    Attr? getAttributeNodeNS(DOMString? namespaceURI, DOMString localName);
    [RaisesException, CEReactions] Attr? setAttributeNode(Attr attr);
    [RaisesException, CEReactions] Attr? setAttributeNodeNS(Attr attr);
    [RaisesException, CEReactions] Attr removeAttributeNode(Attr attr);

    [RuntimeEnabled=EditContext] attribute EditContext? editContext;

    [RaisesException, MeasureAs=ElementAttachShadow] ShadowRoot attachShadow(ShadowRootInit shadowRootInitDict);
    [Affects=Nothing, PerWorldBindings, ImplementedAs=OpenShadowRoot] readonly attribute ShadowRoot? shadowRoot;

    [RaisesException] Element? closest(DOMString selectors);
    [RaisesException] boolean matches(DOMString selectors);
    [RaisesException, ImplementedAs=matches, MeasureAs=ElementPrefixedMatchesSelector] boolean webkitMatchesSelector(DOMString selectors); // historical alias of .matches

    [Affects=Nothing] HTMLCollection getElementsByTagName(DOMString localName);
    [Affects=Nothing] HTMLCollection getElementsByTagNameNS(DOMString? namespaceURI, DOMString localName);
    [Affects=Nothing] HTMLCollection getElementsByClassName(DOMString classNames);

    [RaisesException, CEReactions] Element? insertAdjacentElement(DOMString where, Element element);
    [RaisesException] void insertAdjacentText(DOMString where, DOMString data);

    // CSS Shadow Parts
    // https://drafts.csswg.org/css-shadow-parts/#idl
    [Affects=Nothing, SameObject, PerWorldBindings, PutForwards=value] readonly attribute DOMTokenList part;

    // Pointer Events
    // https://w3c.github.io/pointerevents/#extensions-to-the-element-interface
    [RaisesException] void setPointerCapture (long pointerId);
    [RaisesException] void releasePointerCapture (long pointerId);
    boolean hasPointerCapture (long pointerId);

    // Mixin Slotable
    // https://dom.spec.whatwg.org/#mixin-slotable
    [ImplementedAs=assignedSlotForBinding] readonly attribute HTMLSlotElement? assignedSlot;

    // DOM Parsing and Serialization
    // https://w3c.github.io/DOM-Parsing/#extensions-to-the-element-interface
    //
    // TODO(mkwst): Write a spec for the `TrustedHTML` variants.
    // TODO(lyf): Change the type to `[TreatNullAs=xxx] HTMLString` after
    // https://crbug.com/1058762 has been fixed.
    [Affects=Nothing, CEReactions, RuntimeCallStatsCounter=ElementInnerHTML, RaisesException=Setter] attribute [TreatNullAs=EmptyString, StringContext=TrustedHTML] DOMString innerHTML;
    [Affects=Nothing, CEReactions, RaisesException=Setter] attribute [TreatNullAs=EmptyString, StringContext=TrustedHTML] DOMString outerHTML;
    [CEReactions, RaisesException] void insertAdjacentHTML(DOMString position, HTMLString text);

    // Declarative Shadow DOM getInnerHTML() function.
    [Affects=Nothing, RuntimeEnabled=DeclarativeShadowDOM, RuntimeCallStatsCounter=ElementGetInnerHTML] HTMLString getInnerHTML(optional GetInnerHTMLOptions options = {});

    // Pointer Lock
    // https://w3c.github.io/pointerlock/#extensions-to-the-element-interface
    // This function returns void unless the Runtime Enabled Feature |PointerLockOptions| is enabled then it returns Promise<void>.
    [MeasureAs=ElementRequestPointerLock, CallWith=ScriptState, RaisesException] any requestPointerLock(optional PointerLockOptions options = {});

    // CSSOM View Module
    // https://drafts.csswg.org/cssom-view/#extension-to-the-element-interface
    [Measure] DOMRectList getClientRects();
    [Affects=Nothing, Measure, RuntimeCallStatsCounter=ElementGetBoundingClientRect] DOMRect getBoundingClientRect();

    // TODO(sunyunjia): Add default value for scrollIntoView() once
    // crbug.com/734599 is fixed.
    void scrollIntoView(optional (ScrollIntoViewOptions or boolean) arg = {});
    [ImplementedAs=scrollTo] void scroll(optional ScrollToOptions options = {});
    [ImplementedAs=scrollTo] void scroll(unrestricted double x, unrestricted double y);
    void scrollTo(optional ScrollToOptions options = {});
    void scrollTo(unrestricted double x, unrestricted double y);
    void scrollBy(optional ScrollToOptions options = {});
    void scrollBy(unrestricted double x, unrestricted double y);
    [Affects=Nothing] attribute unrestricted double scrollTop;
    [Affects=Nothing] attribute unrestricted double scrollLeft;
    [Affects=Nothing] readonly attribute long scrollWidth;
    [Affects=Nothing] readonly attribute long scrollHeight;
    [Affects=Nothing] readonly attribute long clientTop;
    [Affects=Nothing] readonly attribute long clientLeft;
    [Affects=Nothing] readonly attribute long clientWidth;
    [Affects=Nothing] readonly attribute long clientHeight;

    // Typed OM
    // https://drafts.css-houdini.org/css-typed-om/#inline-stylepropertymap-objects
    [SameObject, MeasureAs=CSSTypedOMStylePropertyMap] readonly attribute StylePropertyMap attributeStyleMap;

    // Non-standard API
    [MeasureAs=ElementScrollIntoViewIfNeeded] void scrollIntoViewIfNeeded(optional boolean centerIfNeeded);

    // Experimental accessibility API
    [RuntimeEnabled=ComputedAccessibilityInfo] readonly attribute DOMString? computedRole;
    [RuntimeEnabled=ComputedAccessibilityInfo] readonly attribute DOMString? computedName;

    // Accessibility Object Model
    [RuntimeEnabled=AccessibilityObjectModel] readonly attribute AccessibleNode? accessibleNode;

    // Event handler attributes
    attribute EventHandler onbeforecopy;
    attribute EventHandler onbeforecut;
    attribute EventHandler onbeforepaste;
    attribute EventHandler onsearch;
    [RuntimeEnabled=BeforeMatchEvent] attribute EventHandler onbeforematch;

    // Element Timing
    [Affects=Nothing, CEReactions, Reflect=elementtiming] attribute DOMString elementTiming;
};

Element includes ParentNode;
Element includes ChildNode;
Element includes NonDocumentTypeChildNode;