Rename AtomicString to AtomString
[WebKit-https.git] / Source / WebCore / dom / Document.idl
1 /*
2  * Copyright (C) 2006, 2007, 2011, 2015 Apple Inc. All rights reserved.
3  * Copyright (C) 2006, 2007 Samuel Weinig <sam@webkit.org>
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Library General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Library General Public License for more details.
14  *
15  * You should have received a copy of the GNU Library General Public License
16  * along with this library; see the file COPYING.LIB.  If not, write to
17  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18  * Boston, MA 02110-1301, USA.
19  */
20
21 typedef (
22 #if defined(ENABLE_WEBGL) && ENABLE_WEBGL
23     WebGLRenderingContext or
24 #endif
25 #if defined(ENABLE_WEBGL2) && ENABLE_WEBGL2
26     WebGL2RenderingContext or
27 #endif
28 #if defined(ENABLE_WEBGPU) && ENABLE_WEBGPU
29     GPUCanvasContext or
30 #endif
31     ImageBitmapRenderingContext or 
32     CanvasRenderingContext2D) RenderingContext;
33
34 [
35     Constructor,
36     ConstructorCallWith=Document,
37     CustomToJSObject,
38     CustomHeapSnapshot,
39     DOMJIT,
40     ExportMacro=WEBCORE_EXPORT,
41     JSCustomHeader,
42     JSCustomMarkFunction,
43     JSGenerateToNativeObject,
44 ] interface Document : Node {
45     readonly attribute DOMImplementation implementation; // FIXME: Should be [SameObject].
46     [ImplementedAs=urlForBindings] readonly attribute USVString URL;
47     [ImplementedAs=urlForBindings] readonly attribute USVString documentURI;
48     readonly attribute USVString origin;
49     readonly attribute DOMString compatMode;
50     [ImplementedAs=characterSetWithUTF8Fallback] readonly attribute DOMString characterSet;
51     [ImplementedAs=characterSetWithUTF8Fallback] readonly attribute DOMString charset; // Historical alias of .characterSet,
52     [ImplementedAs=characterSetWithUTF8Fallback] readonly attribute DOMString inputEncoding; // Historical alias of .characterSet.
53     readonly attribute DOMString contentType;
54
55     readonly attribute DocumentType? doctype;
56     [DOMJIT=Getter] readonly attribute Element? documentElement;
57
58     HTMLCollection getElementsByTagName(DOMString qualifiedName);
59     HTMLCollection getElementsByTagNameNS(DOMString? namespaceURI, DOMString localName);
60     HTMLCollection getElementsByClassName(DOMString classNames);
61
62     [NewObject, MayThrowException, ImplementedAs=createElementForBindings] Element createElement(DOMString localName); // FIXME: missing options parameter.
63     [NewObject, MayThrowException] Element createElementNS(DOMString? namespaceURI, DOMString qualifiedName); // FIXME: missing options parameter.
64     [NewObject] DocumentFragment createDocumentFragment();
65     [NewObject] Text createTextNode(DOMString data);
66     [NewObject, MayThrowException] CDATASection createCDATASection(DOMString data);
67     [NewObject] Comment createComment(DOMString data);
68     [NewObject, MayThrowException] ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);
69
70     [CEReactions, MayThrowException, NewObject] Node importNode(Node node, optional boolean deep = false);
71     [CEReactions, MayThrowException] Node adoptNode(Node node);
72
73     [NewObject, MayThrowException] Attr createAttribute(DOMString localName);
74     [NewObject, MayThrowException] Attr createAttributeNS(DOMString? namespaceURI, DOMString qualifiedName);
75
76     [MayThrowException, NewObject] Event createEvent(DOMString type);
77
78     [NewObject] Range createRange();
79
80     // NodeFilter.SHOW_ALL = 0xFFFFFFFF.
81     [NewObject] NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
82     [NewObject] TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
83
84     // Extensions from HTML specification (https://html.spec.whatwg.org/#the-document-object).
85     [PutForwards=href, Unforgeable] readonly attribute Location? location;
86     attribute USVString domain;
87     readonly attribute USVString referrer;
88     attribute USVString cookie;
89     readonly attribute DOMString lastModified;
90     readonly attribute DocumentReadyState readyState;
91
92     // DOM tree accessors.
93     [CEReactions] attribute DOMString title;
94     [CEReactions] attribute DOMString dir;
95     [CEReactions, DOMJIT=Getter, ImplementedAs=bodyOrFrameset] attribute HTMLElement? body;
96     readonly attribute HTMLHeadElement? head;
97     readonly attribute HTMLCollection images; // Should be [SameObject].
98     readonly attribute HTMLCollection embeds; // Should be [SameObject].
99     readonly attribute HTMLCollection plugins; // Should be [SameObject].
100     readonly attribute HTMLCollection links; // Should be [SameObject].
101     readonly attribute HTMLCollection forms; // Should be [SameObject].
102     readonly attribute HTMLCollection scripts; // Should be [SameObject].
103     NodeList getElementsByName([AtomString] DOMString elementName);
104     readonly attribute HTMLScriptElement? currentScript; // FIXME: Should return a HTMLOrSVGScriptElement.
105
106     // dynamic markup insertion
107     // FIXME: The HTML spec says this should consult the "responsible document". We should ensure
108     // that the caller document matches those semantics. It is possible we should replace it with
109     // the existing 'incumbent document' concept.
110     [CEReactions, CallWith=ResponsibleDocument, ImplementedAs=openForBindings, MayThrowException] Document open(optional DOMString unused1, optional DOMString unused2); // both arguments are ignored.
111     [CallWith=ActiveWindow&FirstWindow, ImplementedAs=openForBindings, MayThrowException] WindowProxy open(USVString url, DOMString name, DOMString features);
112     [CEReactions, ImplementedAs=closeForBindings, MayThrowException] void close();
113     [CEReactions, CallWith=ResponsibleDocument, MayThrowException] void write(DOMString... text);
114     [CEReactions, CallWith=ResponsibleDocument, MayThrowException] void writeln(DOMString... text);
115
116     // User interaction.
117     [ImplementedAs=windowProxy] readonly attribute WindowProxy? defaultView;
118     boolean hasFocus();
119     [CEReactions] attribute DOMString designMode;
120     [CEReactions] boolean execCommand(DOMString commandId, optional boolean showUI = false, optional DOMString? value = null); // FIXME: value should not be nullable.
121     boolean queryCommandEnabled(DOMString commandId);
122     boolean queryCommandIndeterm(DOMString commandId);
123     boolean queryCommandState(DOMString commandId);
124     boolean queryCommandSupported(DOMString commandId);
125     DOMString queryCommandValue(DOMString commandId);
126     [EnabledAtRuntime=UndoManagerAPI] readonly attribute UndoManager undoManager;
127
128     // Special event handler IDL attributes that only apply to Document objects.
129     [LenientThis] attribute EventHandler onreadystatechange;
130
131     // Extensions from the CSSOM-View specification (https://drafts.csswg.org/cssom-view/#extensions-to-the-document-interface).
132     [ImplementedAs=scrollingElementForAPI] readonly attribute Element? scrollingElement;
133
134     // Extensions from Selection API (https://www.w3.org/TR/selection-api/#extensions-to-document-interface).
135     // FIXME: Should likely be moved to DocumentOrShadowRoot.
136     DOMSelection? getSelection();
137
138     // XPath extensions (https://www.w3.org/TR/DOM-Level-3-XPath/xpath.html#XPathEvaluator).
139     [MayThrowException] XPathExpression createExpression(optional DOMString expression = "undefined", optional XPathNSResolver? resolver); // FIXME: Using "undefined" as default parameter value is wrong.
140     XPathNSResolver createNSResolver(Node? nodeResolver);
141     [MayThrowException] XPathResult evaluate(optional DOMString expression = "undefined", optional Node? contextNode, optional XPathNSResolver? resolver, optional unsigned short type = 0, optional XPathResult? inResult); // FIXME: Using "undefined" as default parameter value is wrong.
142
143     // Extensions from Pointer Lock API (https://www.w3.org/TR/pointerlock/#extensions-to-the-document-interface).
144     [NotEnumerable, Conditional=POINTER_LOCK] attribute EventHandler onpointerlockchange; // FIXME: Should be enumerable.
145     [NotEnumerable, Conditional=POINTER_LOCK] attribute EventHandler onpointerlockerror; // FIXME: Should be enumerable.
146     [Conditional=POINTER_LOCK] void exitPointerLock();
147
148     // Extensions from CSS Font Loading API (https://drafts.csswg.org/css-font-loading/#font-face-source).
149     // FIXME: Should be in a separate FontFaceSource interface.
150     readonly attribute FontFaceSet fonts;
151
152     // Extensions from Page visibility API (https://www.w3.org/TR/page-visibility/#sec-document-interface).
153     readonly attribute boolean hidden;
154     readonly attribute VisibilityState visibilityState;
155     attribute EventHandler onvisibilitychange;
156
157     // FIXME: Those have been dropped from the DOM specification.
158     readonly attribute DOMString? xmlEncoding;
159     attribute DOMString? xmlVersion;
160     attribute boolean xmlStandalone;
161
162     // FIXME: Blink has already dropped this (https://groups.google.com/a/chromium.org/forum/#!topic/blink-dev/s3ezjTuC8ig).
163     // And it's just a stub that always returns null, so we can probably remove it some time soon.
164     CSSStyleDeclaration? getOverrideStyle(optional Element? element = null, optional DOMString pseudoElement = "undefined");
165
166     // FIXME: Should be moved to GlobalEventHandlers (http://w3c.github.io/selection-api/#extensions-to-globaleventhandlers).
167     [NotEnumerable] attribute EventHandler onselectstart; // FIXME: Should be enumerable.
168     [NotEnumerable] attribute EventHandler onselectionchange; // FIXME: Should be enumerable.
169
170     // Non standard: It has been superseeded by caretPositionFromPoint which we do not implement yet.
171     Range caretRangeFromPoint(optional long x = 0, optional long y = 0);
172
173     // FIXME: This is not standard and has been dropped from Blink already.
174     RenderingContext? getCSSCanvasContext(DOMString contextId, DOMString name, long width, long height);
175
176     // Obsolete features from https://html.spec.whatwg.org/multipage/obsolete.html
177
178     [CEReactions] attribute [TreatNullAs=EmptyString] DOMString fgColor;
179     [CEReactions, ImplementedAs=linkColorForBindings] attribute [TreatNullAs=EmptyString] DOMString linkColor;
180     [CEReactions] attribute [TreatNullAs=EmptyString] DOMString vlinkColor;
181     [CEReactions] attribute [TreatNullAs=EmptyString] DOMString alinkColor;
182     [CEReactions] attribute [TreatNullAs=EmptyString] DOMString bgColor;
183
184     readonly attribute HTMLCollection anchors; /* [SameObject] */
185     readonly attribute HTMLCollection applets; /* [SameObject] */
186
187     void clear();
188     void captureEvents();
189     void releaseEvents();
190
191     [Replaceable] readonly attribute HTMLAllCollection all; /* [SameObject] */
192
193     [EnabledAtRuntime=WebAnimations] readonly attribute DocumentTimeline timeline;
194     [EnabledAtRuntime=WebAnimations] sequence<WebAnimation> getAnimations();
195 };
196
197 enum DocumentReadyState { "loading", "interactive", "complete" };
198
199 Document implements DocumentAndElementEventHandlers;
200 Document implements ParentNode;
201 Document implements NonElementParentNode;
202 Document implements DocumentOrShadowRoot;
203 Document implements GlobalEventHandlers;