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