Add document.defineCustomElement
[WebKit.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 [
22     Constructor,
23     ConstructorCallWith=ScriptExecutionContext,
24     CustomToJSObject,
25     JSCustomHeader,
26     JSGenerateToNativeObject,
27 ] interface Document : Node {
28
29     // DOM Level 1 Core
30     readonly attribute DocumentType doctype;
31     readonly attribute DOMImplementation implementation;
32     readonly attribute Element documentElement;
33
34     [NewObject, RaisesException] Element createElement(DOMString tagName);
35     [NewObject] DocumentFragment   createDocumentFragment();
36     [NewObject] Text createTextNode([Default=Undefined] optional DOMString data);
37     [NewObject] Comment createComment([Default=Undefined] optional DOMString data);
38     [NewObject, RaisesException] CDATASection createCDATASection([Default=Undefined] optional DOMString data);
39     [ObjCLegacyUnnamedParameters, NewObject, RaisesException] ProcessingInstruction createProcessingInstruction([Default=Undefined] optional DOMString target,
40                                                                                  [Default=Undefined] optional DOMString data);
41     [NewObject, RaisesException] Attr createAttribute([Default=Undefined] optional DOMString name);
42
43 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
44     [RaisesException] EntityReference createEntityReference([Default=Undefined] optional DOMString name);
45 #endif
46
47 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
48     [ImplementedAs=getElementsByTagNameForObjC] NodeList getElementsByTagName([Default=Undefined] optional DOMString tagname);
49 #else
50     HTMLCollection getElementsByTagName([Default=Undefined] optional DOMString tagname);
51 #endif
52
53     // Introduced in DOM Level 2:
54
55     [ObjCLegacyUnnamedParameters, NewObject, RaisesException] Node importNode([Default=Undefined] optional Node importedNode,
56                     optional boolean deep);
57     [ObjCLegacyUnnamedParameters, NewObject, RaisesException] Element createElementNS([TreatNullAs=NullString,Default=Undefined] optional DOMString namespaceURI,
58                             [TreatNullAs=NullString,Default=Undefined] optional DOMString qualifiedName);
59     [ObjCLegacyUnnamedParameters, NewObject, RaisesException] Attr createAttributeNS([TreatNullAs=NullString,Default=Undefined] optional DOMString namespaceURI,
60                                                                           [TreatNullAs=NullString,Default=Undefined] optional DOMString qualifiedName);
61
62 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
63     [ObjCLegacyUnnamedParameters, ImplementedAs=getElementsByTagNameNSForObjC] NodeList getElementsByTagNameNS([TreatNullAs=NullString,Default=Undefined] optional DOMString namespaceURI, [Default=Undefined] optional DOMString localName);
64 #else
65     HTMLCollection getElementsByTagNameNS([TreatNullAs=NullString,Default=Undefined] optional DOMString namespaceURI, [Default=Undefined] optional DOMString localName);
66 #endif
67
68     // DOM Level 3 Core
69
70     [ImplementedAs=characterSetWithUTF8Fallback] readonly attribute DOMString inputEncoding;
71
72     [TreatReturnedNullStringAs=Null] readonly attribute DOMString xmlEncoding;
73     [TreatReturnedNullStringAs=Null, TreatNullAs=NullString, SetterRaisesException] attribute DOMString xmlVersion;
74     [SetterRaisesException] attribute boolean xmlStandalone;
75
76     [RaisesException] Node               adoptNode([Default=Undefined] optional Node source);
77
78 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C || defined(LANGUAGE_GOBJECT) && LANGUAGE_GOBJECT
79     // document.documentURI was writable in DOM3 Core, but is read-only in DOM4
80     // (see http://www.w3.org/TR/2011/WD-dom-20110915/#document). We need to keep
81     // the writable version around for Objective C clients, but are moving to
82     // read-only for other clients.
83              [TreatReturnedNullStringAs=Null, TreatNullAs=NullString] attribute DOMString documentURI;
84 #else
85     [TreatReturnedNullStringAs=Null] readonly attribute DOMString documentURI;
86 #endif
87
88     // DOM Level 2 Events (DocumentEvents interface)
89
90     [RaisesException, NewObject] Event              createEvent([Default=Undefined] optional DOMString eventType);
91
92     // DOM Level 2 Tranversal and Range (DocumentRange interface)
93
94     [NewObject] Range              createRange();
95
96     // DOM Level 2 Tranversal and Range (DocumentTraversal interface)
97
98 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C || defined(LANGUAGE_GOBJECT) && LANGUAGE_GOBJECT
99     [ObjCLegacyUnnamedParameters, RaisesException] NodeIterator createNodeIterator(Node root,
100         optional unsigned long whatToShow = 0xFFFFFFFF,
101         optional NodeFilter? filter,
102         optional boolean expandEntityReferences);
103     [ObjCLegacyUnnamedParameters, RaisesException] TreeWalker createTreeWalker(Node root,
104         optional unsigned long whatToShow = 0xFFFFFFFF,
105         optional NodeFilter? filter,
106         optional boolean expandEntityReferences);
107 #else
108     [RaisesException, NewObject] NodeIterator createNodeIterator(Node root,
109         optional unsigned long whatToShow = 0xFFFFFFFF,
110         optional NodeFilter? filter);
111     [RaisesException, NewObject] TreeWalker createTreeWalker(Node root,
112         optional unsigned long whatToShow = 0xFFFFFFFF,
113         optional NodeFilter? filter);
114 #endif
115
116     // DOM Level 2 Abstract Views (DocumentView interface)
117
118     readonly attribute DOMWindow defaultView;
119
120     // DOM Level 2 Style (DocumentStyle interface)
121
122     readonly attribute StyleSheetList styleSheets;
123
124     // DOM Level 2 Style (DocumentCSS interface)
125
126     [ObjCLegacyUnnamedParameters] CSSStyleDeclaration getOverrideStyle([Default=Undefined] optional Element element,
127                                                         [Default=Undefined] optional DOMString pseudoElement);
128
129     readonly attribute DOMString contentType;
130
131     // DOM Level 3 XPath (XPathEvaluator interface)
132     [ObjCLegacyUnnamedParameters, RaisesException] XPathExpression createExpression([Default=Undefined] optional DOMString expression,
133                                                     [Default=Undefined] optional XPathNSResolver resolver);
134     XPathNSResolver    createNSResolver(Node nodeResolver);
135     [ObjCLegacyUnnamedParameters, RaisesException] XPathResult evaluate([Default=Undefined] optional DOMString expression,
136                                                   [Default=Undefined] optional Node contextNode,
137                                                   [Default=Undefined] optional XPathNSResolver resolver,
138                                                   [Default=Undefined] optional unsigned short type,
139                                                   [Default=Undefined] optional XPathResult inResult);
140
141     // Common extensions
142     boolean            execCommand([Default=Undefined] optional DOMString command,
143                                    [Default=Undefined] optional boolean userInterface,
144                                    [TreatNullAs=NullString, TreatUndefinedAs=NullString, Default=Undefined] optional DOMString value);
145
146 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
147     // FIXME: remove the these two versions once optional is implemented for Objective-C.
148     boolean            execCommand(DOMString command,
149                                    boolean userInterface);
150     boolean            execCommand(DOMString command);
151 #endif
152
153     boolean            queryCommandEnabled([Default=Undefined] optional DOMString command);
154     boolean            queryCommandIndeterm([Default=Undefined] optional DOMString command);
155     boolean            queryCommandState([Default=Undefined] optional DOMString command);
156     boolean            queryCommandSupported([Default=Undefined] optional DOMString command);
157     DOMString          queryCommandValue([Default=Undefined] optional DOMString command);
158
159     // Moved down from HTMLDocument
160
161              [TreatNullAs=NullString] attribute DOMString title;
162     readonly attribute DOMString referrer;
163 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
164     [TreatNullAs=NullString, SetterRaisesException] attribute DOMString domain;
165 #else
166     readonly attribute DOMString domain;
167 #endif
168     readonly attribute DOMString URL;
169
170     [TreatNullAs=NullString, GetterRaisesException, SetterRaisesException] attribute DOMString cookie;
171
172     [SetterRaisesException, ImplementedAs=bodyOrFrameset, StrictTypeChecking] attribute HTMLElement body;
173
174     readonly attribute HTMLHeadElement head;
175     readonly attribute HTMLCollection images;
176     readonly attribute HTMLCollection applets;
177     readonly attribute HTMLCollection links;
178     readonly attribute HTMLCollection forms;
179     readonly attribute HTMLCollection anchors;
180     readonly attribute DOMString lastModified;
181
182     NodeList getElementsByName([Default=Undefined,AtomicString] optional DOMString elementName);
183
184 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
185     [PutForwards=href, Unforgeable] readonly attribute Location? location;
186 #endif
187
188     // IE extensions
189
190              [TreatReturnedNullStringAs=Undefined, TreatNullAs=NullString] attribute DOMString charset;
191     [TreatReturnedNullStringAs=Undefined] readonly attribute DOMString defaultCharset;
192     [TreatReturnedNullStringAs=Undefined] readonly attribute DOMString readyState;
193
194     Element            elementFromPoint([Default=Undefined] optional long x, 
195                                         [Default=Undefined] optional long y);
196     Range              caretRangeFromPoint([Default=Undefined] optional long x, 
197                                            [Default=Undefined] optional long y);
198
199     // Mozilla extensions
200 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
201     DOMSelection       getSelection();
202 #endif
203     [ImplementedAs=characterSetWithUTF8Fallback] readonly attribute DOMString characterSet;
204
205     // WebKit extensions
206
207     [TreatReturnedNullStringAs=Null] readonly attribute DOMString preferredStylesheetSet;
208              [TreatReturnedNullStringAs=Null, TreatNullAs=NullString] attribute DOMString selectedStylesheetSet;
209
210 #if !defined(LANGUAGE_JAVASCRIPT) || !LANGUAGE_JAVASCRIPT
211     CSSStyleDeclaration createCSSStyleDeclaration();
212 #endif
213
214 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
215     // DOM Level 2 Style Interface
216     [ObjCLegacyUnnamedParameters, ObjCUseDefaultView] CSSStyleDeclaration getComputedStyle(Element element,
217                                                                   DOMString pseudoElement);
218
219     // WebKit extension
220     // FIXME: remove the first version once optional is implemented for Objective-C.
221     [ObjCUseDefaultView] CSSRuleList getMatchedCSSRules(Element element,
222                                               DOMString pseudoElement);
223     [ObjCUseDefaultView] CSSRuleList getMatchedCSSRules(Element element,
224                                               DOMString pseudoElement,
225                                               optional boolean authorOnly);
226                                               
227 #endif
228
229 #if !defined(LANGUAGE_OBJECTIVE_C) || !LANGUAGE_OBJECTIVE_C
230     CanvasRenderingContext getCSSCanvasContext(DOMString contextId, DOMString name, long width, long height);
231 #endif
232
233     // HTML 5
234 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
235     [ImplementedAs=getElementsByClassNameForObjC] NodeList getElementsByClassName([Default=Undefined] optional DOMString classNames);
236 #else
237     HTMLCollection getElementsByClassName([Default=Undefined] optional DOMString classNames);
238 #endif
239
240     readonly attribute Element activeElement;
241     boolean hasFocus();
242
243     readonly attribute DOMString compatMode;
244
245 #if defined(ENABLE_FULLSCREEN_API) && ENABLE_FULLSCREEN_API
246     // Mozilla version
247     readonly attribute boolean webkitIsFullScreen;
248     readonly attribute boolean webkitFullScreenKeyboardInputAllowed;
249     readonly attribute Element webkitCurrentFullScreenElement;
250     void webkitCancelFullScreen();
251
252     // W3C version
253     readonly attribute boolean webkitFullscreenEnabled;
254     readonly attribute Element webkitFullscreenElement;
255     void webkitExitFullscreen();
256 #endif
257
258     [Conditional=POINTER_LOCK] void exitPointerLock();
259     [Conditional=POINTER_LOCK] readonly attribute Element pointerLockElement;
260
261     [Conditional=CSS_REGIONS] DOMNamedFlowCollection webkitGetNamedFlows();
262
263 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
264     [Conditional=FONT_LOAD_EVENTS] readonly attribute FontLoader fonts;
265 #endif
266
267 #if defined(ENABLE_IOS_TOUCH_EVENTS) && ENABLE_IOS_TOUCH_EVENTS
268 #include <WebKitAdditions/DocumentIOS.idl>
269 #elif defined(ENABLE_TOUCH_EVENTS) && ENABLE_TOUCH_EVENTS
270     [NewObject, RaisesException] Touch createTouch([Default=Undefined] optional DOMWindow window,
271                                                      [Default=Undefined] optional EventTarget target,
272                                                      [Default=Undefined] optional long identifier,
273                                                      [Default=Undefined] optional long pageX,
274                                                      [Default=Undefined] optional long pageY,
275                                                      [Default=Undefined] optional long screenX,
276                                                      [Default=Undefined] optional long screenY,
277                                                      [Default=Undefined] optional long webkitRadiusX,
278                                                      [Default=Undefined] optional long webkitRadiusY,
279                                                      [Default=Undefined] optional unrestricted float webkitRotationAngle,
280                                                      [Default=Undefined] optional unrestricted float webkitForce);
281     [NewObject, Custom, RaisesException] TouchList createTouchList();
282 #endif
283
284 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
285     [Custom, RaisesException, Conditional=CUSTOM_ELEMENTS]
286     void defineCustomElement(DOMString tagName, CustomElementInterface elementInterface);
287 #endif
288
289     // Page visibility API.
290     readonly attribute DOMString visibilityState;
291     readonly attribute boolean hidden;
292
293     // Security Policy API: http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html#script-interfaces
294     [Conditional=CSP_NEXT] readonly attribute DOMSecurityPolicy securityPolicy;
295
296     // currentscript API: http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-document-currentscript
297     readonly attribute HTMLScriptElement currentScript;
298
299     // http://www.w3.org/TR/2014/WD-dom-20140204/#dom-document-origin
300     readonly attribute DOMString origin;
301
302     // http://dev.w3.org/csswg/cssom-view/#dom-document-scrollingelement
303     readonly attribute Element scrollingElement;
304
305
306     // Event Handlers
307
308     // Unique to Element and Document
309     // FIXME: Should these be exposed on Window as well (and therefore moved to GlobalEventHandlers.idl)?
310     [NotEnumerable] attribute EventHandler onbeforecopy;
311     [NotEnumerable] attribute EventHandler onbeforecut;
312     [NotEnumerable] attribute EventHandler onbeforepaste;
313     [NotEnumerable] attribute EventHandler oncopy;
314     [NotEnumerable] attribute EventHandler oncut;
315     [NotEnumerable] attribute EventHandler onpaste;
316     [NotEnumerable] attribute EventHandler onselectstart;
317     [NotEnumerable, Conditional=FULLSCREEN_API] attribute EventHandler onwebkitfullscreenchange;
318     [NotEnumerable, Conditional=FULLSCREEN_API] attribute EventHandler onwebkitfullscreenerror;
319
320     // Unique to Document and HTMLBodyElement
321     [NotEnumerable] attribute EventHandler onselectionchange;
322
323     // Unique to Document
324     [NotEnumerable] attribute EventHandler onreadystatechange;
325     [NotEnumerable, Conditional=CSP_NEXT] attribute EventHandler onsecuritypolicyviolation;
326     [NotEnumerable, Conditional=POINTER_LOCK] attribute EventHandler onpointerlockchange;
327     [NotEnumerable, Conditional=POINTER_LOCK] attribute EventHandler onpointerlockerror;
328 };
329
330 Document implements ParentNode;
331 Document implements NonElementParentNode;
332 Document implements GlobalEventHandlers;