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

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;

    // 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);

    [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, CustomElementCallbacks] void setAttribute(DOMString name, TrustedString value);
    [RaisesException, CEReactions, CustomElementCallbacks] void setAttributeNS(DOMString? namespaceURI, DOMString name, DOMString value);
    [CEReactions, CustomElementCallbacks] void removeAttribute(DOMString name);
    [CEReactions, CustomElementCallbacks] void removeAttributeNS(DOMString? namespaceURI, DOMString localName);
    [Affects=Nothing] boolean hasAttribute(DOMString name);
    [Affects=Nothing] boolean hasAttributeNS(DOMString? namespaceURI, DOMString localName);
    [RaisesException] boolean toggleAttribute(DOMString qualifiedName, optional boolean force);

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

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

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

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

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

    // 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.
    [Affects=Nothing, CEReactions, CustomElementCallbacks, Custom=Setter, RuntimeCallStatsCounter=ElementInnerHTML] attribute HTMLString innerHTML;
    [Affects=Nothing, CEReactions, CustomElementCallbacks, Custom=Setter] attribute HTMLString outerHTML;
    [CEReactions, CustomElementCallbacks, RaisesException] void insertAdjacentHTML(DOMString position, HTMLString text);

    // Pointer Lock
    // https://w3c.github.io/pointerlock/#extensions-to-the-element-interface
    [MeasureAs=ElementRequestPointerLock] void requestPointerLock();

    // 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);
    [RuntimeEnabled=CSSOMSmoothScroll, ImplementedAs=scrollTo] void scroll(optional ScrollToOptions options);
    [RuntimeEnabled=CSSOMSmoothScroll, ImplementedAs=scrollTo] void scroll(unrestricted double x, unrestricted double y);
    [RuntimeEnabled=CSSOMSmoothScroll] void scrollTo(optional ScrollToOptions options);
    [RuntimeEnabled=CSSOMSmoothScroll] void scrollTo(unrestricted double x, unrestricted double y);
    [RuntimeEnabled=CSSOMSmoothScroll] void scrollBy(optional ScrollToOptions options);
    [RuntimeEnabled=CSSOMSmoothScroll] 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;

    // Scroll Customization API. See crbug.com/410974 for details.
    [RuntimeEnabled=ScrollCustomization] void setApplyScroll(ScrollStateCallback scrollStateCallback, NativeScrollBehavior nativeScrollBehavior);
    [RuntimeEnabled=ScrollCustomization] void setDistributeScroll(ScrollStateCallback scrollStateCallback, NativeScrollBehavior nativeScrollBehavior);

    // 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);
    [RuntimeEnabled=ShadowDOMV0, RaisesException, DeprecateAs=ElementCreateShadowRoot] ShadowRoot createShadowRoot();
    [RuntimeEnabled=ShadowDOMV0] NodeList getDestinationInsertionPoints();

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

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

    [RuntimeEnabled=InvisibleDOM, CEReactions, CustomElementCallbacks, Reflect, ReflectOnly=("static","invisible"), ReflectEmpty="invisible", ReflectInvalid="invisible"] attribute DOMString invisible;

    // Event handler attributes
    attribute EventHandler onbeforecopy;
    attribute EventHandler onbeforecut;
    attribute EventHandler onbeforepaste;
    attribute EventHandler oncopy;
    attribute EventHandler oncut;
    attribute EventHandler onpaste;
    attribute EventHandler onsearch;
    attribute EventHandler onselectstart;
};

Element implements ParentNode;
Element implements ChildNode;
Element implements NonDocumentTypeChildNode;