1c0e42ca95c97e80bbd9b3dcc768e2a7eb55a976
[WebKit-https.git] / Source / WebCore / dom / Document.idl
1 /*
2  * Copyright (C) 2006, 2007, 2011 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     CustomToJSObject,
23     JSGenerateToNativeObject,
24     JSInlineGetOwnPropertySlot
25 ] interface Document : Node {
26
27     // DOM Level 1 Core
28     readonly attribute DocumentType doctype;
29     readonly attribute DOMImplementation implementation;
30     readonly attribute Element documentElement;
31
32     [ReturnNewObject]
33     Element createElement([TreatNullAs=NullString,Default=Undefined] optional DOMString tagName)
34         raises (DOMException);
35     DocumentFragment   createDocumentFragment();
36     [ReturnNewObject] Text createTextNode([Default=Undefined] optional DOMString data);
37     [ReturnNewObject] Comment createComment([Default=Undefined] optional DOMString data);
38     [ReturnNewObject] CDATASection createCDATASection([Default=Undefined] optional DOMString data)
39         raises(DOMException);
40     [ObjCLegacyUnnamedParameters, ReturnNewObject] ProcessingInstruction createProcessingInstruction([Default=Undefined] optional DOMString target,
41                                                                                  [Default=Undefined] optional DOMString data)
42         raises (DOMException);
43     [ReturnNewObject] Attr createAttribute([Default=Undefined] optional DOMString name)
44         raises (DOMException);
45     [ReturnNewObject] EntityReference createEntityReference([Default=Undefined] optional DOMString name)
46         raises(DOMException);
47     NodeList getElementsByTagName([Default=Undefined] optional DOMString tagname);
48
49     // Introduced in DOM Level 2:
50
51     [ObjCLegacyUnnamedParameters, ReturnNewObject]
52     Node importNode([Default=Undefined] optional Node importedNode,
53                     optional boolean deep)
54         raises (DOMException);
55     [ObjCLegacyUnnamedParameters, ReturnNewObject]
56     Element createElementNS([TreatNullAs=NullString,Default=Undefined] optional DOMString namespaceURI,
57                             [TreatNullAs=NullString,Default=Undefined] optional DOMString qualifiedName)
58         raises (DOMException);
59     [ObjCLegacyUnnamedParameters, ReturnNewObject] Attr createAttributeNS([TreatNullAs=NullString,Default=Undefined] optional DOMString namespaceURI,
60                                                                           [TreatNullAs=NullString,Default=Undefined] optional DOMString qualifiedName)
61         raises (DOMException);
62     [ObjCLegacyUnnamedParameters] NodeList getElementsByTagNameNS([TreatNullAs=NullString,Default=Undefined] optional DOMString namespaceURI,
63                                                    [Default=Undefined] optional DOMString localName);
64     Element getElementById([Default=Undefined] optional DOMString elementId);
65
66     // DOM Level 3 Core
67
68     [TreatReturnedNullStringAs=Null] readonly attribute DOMString inputEncoding;
69
70     [TreatReturnedNullStringAs=Null] readonly attribute DOMString xmlEncoding;
71              [TreatReturnedNullStringAs=Null, TreatNullAs=NullString] attribute DOMString xmlVersion
72                 setter raises (DOMException);
73              attribute boolean xmlStandalone
74                 setter raises (DOMException);
75
76     Node               adoptNode([Default=Undefined] optional Node source)
77         raises (DOMException);
78
79 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C || defined(LANGUAGE_GOBJECT) && LANGUAGE_GOBJECT
80     // document.documentURI was writable in DOM3 Core, but is read-only in DOM4
81     // (see http://www.w3.org/TR/2011/WD-dom-20110915/#document). We need to keep
82     // the writable version around for Objective C clients, but are moving to
83     // read-only for other clients.
84              [TreatReturnedNullStringAs=Null, TreatNullAs=NullString] attribute DOMString documentURI;
85 #else
86     [TreatReturnedNullStringAs=Null] readonly attribute DOMString documentURI;
87 #endif
88
89     // DOM Level 2 Events (DocumentEvents interface)
90
91     Event              createEvent([Default=Undefined] optional DOMString eventType)
92         raises(DOMException);
93
94     // DOM Level 2 Tranversal and Range (DocumentRange interface)
95
96     Range              createRange();
97
98     // DOM Level 2 Tranversal and Range (DocumentTraversal interface)
99
100     [ObjCLegacyUnnamedParameters] NodeIterator createNodeIterator([Default=Undefined] optional Node root,
101                                                    [Default=Undefined] optional unsigned long whatToShow,
102                                                    [Default=Undefined] optional NodeFilter filter,
103                                                    [Default=Undefined] optional boolean expandEntityReferences)
104         raises(DOMException);
105     [ObjCLegacyUnnamedParameters] TreeWalker createTreeWalker([Default=Undefined] optional Node root,
106                                                [Default=Undefined] optional unsigned long whatToShow,
107                                                [Default=Undefined] optional NodeFilter filter,
108                                                [Default=Undefined] optional boolean expandEntityReferences)
109         raises(DOMException);
110
111     // DOM Level 2 Abstract Views (DocumentView interface)
112
113     readonly attribute DOMWindow defaultView;
114
115     // DOM Level 2 Style (DocumentStyle interface)
116
117     readonly attribute StyleSheetList styleSheets;
118
119     // DOM Level 2 Style (DocumentCSS interface)
120
121     [ObjCLegacyUnnamedParameters] CSSStyleDeclaration getOverrideStyle([Default=Undefined] optional Element element,
122                                                         [Default=Undefined] optional DOMString pseudoElement);
123
124     // DOM Level 3 XPath (XPathEvaluator interface)
125     [ObjCLegacyUnnamedParameters] XPathExpression createExpression([Default=Undefined] optional DOMString expression,
126                                                     [Default=Undefined] optional XPathNSResolver resolver)
127         raises(DOMException);
128     XPathNSResolver    createNSResolver(Node nodeResolver);
129     [ObjCLegacyUnnamedParameters] XPathResult evaluate([Default=Undefined] optional DOMString expression,
130                                                   [Default=Undefined] optional Node contextNode,
131                                                   [Default=Undefined] optional XPathNSResolver resolver,
132                                                   [Default=Undefined] optional unsigned short type,
133                                                   [Default=Undefined] optional XPathResult inResult)
134         raises(DOMException);
135
136     // Common extensions
137     boolean            execCommand([Default=Undefined] optional DOMString command,
138                                    [Default=Undefined] optional boolean userInterface,
139                                    [TreatNullAs=NullString, TreatUndefinedAs=NullString, Default=Undefined] optional DOMString value);
140
141 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
142     // FIXME: remove the these two versions once optional is implemented for Objective-C.
143     boolean            execCommand(DOMString command,
144                                    boolean userInterface);
145     boolean            execCommand(DOMString command);
146 #endif
147
148     boolean            queryCommandEnabled([Default=Undefined] optional DOMString command);
149     boolean            queryCommandIndeterm([Default=Undefined] optional DOMString command);
150     boolean            queryCommandState([Default=Undefined] optional DOMString command);
151     boolean            queryCommandSupported([Default=Undefined] optional DOMString command);
152     DOMString          queryCommandValue([Default=Undefined] optional DOMString command);
153
154     // Moved down from HTMLDocument
155
156              [TreatNullAs=NullString] attribute DOMString title;
157     readonly attribute DOMString referrer;
158 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
159              [TreatNullAs=NullString] attribute DOMString domain
160                  setter raises (DOMException);
161 #else
162     readonly attribute DOMString domain;
163 #endif
164     readonly attribute DOMString URL;
165
166              [TreatNullAs=NullString] attribute DOMString cookie
167                  setter raises (DOMException),
168                  getter raises (DOMException);
169
170              attribute HTMLElement body
171                  setter raises (DOMException);
172
173     readonly attribute HTMLHeadElement head;
174     readonly attribute HTMLCollection images;
175     readonly attribute HTMLCollection applets;
176     readonly attribute HTMLCollection links;
177     readonly attribute HTMLCollection forms;
178     readonly attribute HTMLCollection anchors;
179     readonly attribute DOMString lastModified;
180
181     NodeList getElementsByName([Default=Undefined] optional DOMString elementName);
182
183     [Conditional=MICRODATA] NodeList getItems([TreatNullAs=NullString, TreatUndefinedAs=NullString, Default=Undefined] optional DOMString typeNames);
184
185 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
186              [Custom] attribute Location location;
187 #endif
188
189     // IE extensions
190
191              [TreatReturnedNullStringAs=Undefined, TreatNullAs=NullString] attribute DOMString charset;
192     [TreatReturnedNullStringAs=Undefined] readonly attribute DOMString defaultCharset;
193     [TreatReturnedNullStringAs=Undefined] readonly attribute DOMString readyState;
194
195     Element            elementFromPoint([Default=Undefined] optional long x, 
196                                         [Default=Undefined] optional long y);
197     Range              caretRangeFromPoint([Default=Undefined] optional long x, 
198                                            [Default=Undefined] optional long y);
199
200     // Mozilla extensions
201 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
202     DOMSelection       getSelection();
203 #endif
204     [TreatReturnedNullStringAs=Null] readonly attribute DOMString characterSet;
205
206     // WebKit extensions
207
208     [TreatReturnedNullStringAs=Null] readonly attribute DOMString preferredStylesheetSet;
209              [TreatReturnedNullStringAs=Null, TreatNullAs=NullString] attribute DOMString selectedStylesheetSet;
210
211 #if !defined(LANGUAGE_JAVASCRIPT) || !LANGUAGE_JAVASCRIPT
212     CSSStyleDeclaration createCSSStyleDeclaration();
213 #endif
214
215 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
216     // DOM Level 2 Style Interface
217     [ObjCLegacyUnnamedParameters, ObjCUseDefaultView] CSSStyleDeclaration getComputedStyle(Element element,
218                                                                   DOMString pseudoElement);
219
220     // WebKit extension
221     // FIXME: remove the first version once optional is implemented for Objective-C.
222     [ObjCUseDefaultView] CSSRuleList getMatchedCSSRules(Element element,
223                                               DOMString pseudoElement);
224     [ObjCUseDefaultView] CSSRuleList getMatchedCSSRules(Element element,
225                                               DOMString pseudoElement,
226                                               optional boolean authorOnly);
227                                               
228 #endif
229
230 #if !defined(LANGUAGE_CPP) || !LANGUAGE_CPP
231 #if !defined(LANGUAGE_OBJECTIVE_C) || !LANGUAGE_OBJECTIVE_C
232     CanvasRenderingContext getCSSCanvasContext(DOMString contextId, DOMString name, long width, long height);
233 #endif
234 #endif
235
236     // HTML 5
237     NodeList getElementsByClassName([Default=Undefined] optional DOMString tagname);
238
239     readonly attribute DOMString compatMode;
240
241     // NodeSelector - Selector API
242     Element querySelector(DOMString selectors)
243         raises(DOMException);
244     NodeList querySelectorAll(DOMString selectors)
245         raises(DOMException);
246
247 #if defined(ENABLE_FULLSCREEN_API) && ENABLE_FULLSCREEN_API
248     // Mozilla version
249     readonly attribute boolean webkitIsFullScreen;
250     readonly attribute boolean webkitFullScreenKeyboardInputAllowed;
251     readonly attribute Element webkitCurrentFullScreenElement;
252     void webkitCancelFullScreen();
253
254     // W3C version
255     readonly attribute boolean webkitFullscreenEnabled;
256     readonly attribute Element webkitFullscreenElement;
257     void webkitExitFullscreen();
258 #endif
259
260     [Conditional=POINTER_LOCK] void webkitExitPointerLock();
261     [Conditional=POINTER_LOCK] readonly attribute Element webkitPointerLockElement;
262
263     [Conditional=CSS_REGIONS] DOMNamedFlowCollection webkitGetNamedFlows();
264
265 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
266     [Conditional=FONT_LOAD_EVENTS] readonly attribute FontLoader fontloader;
267 #endif
268
269 #if !defined(LANGUAGE_OBJECTIVE_C) || !LANGUAGE_OBJECTIVE_C
270     // Event handler DOM attributes
271     [NotEnumerable] attribute EventListener onabort;
272     [NotEnumerable] attribute EventListener onblur;
273     [NotEnumerable] attribute EventListener onchange;
274     [NotEnumerable] attribute EventListener onclick;
275     [NotEnumerable] attribute EventListener oncontextmenu;
276     [NotEnumerable] attribute EventListener ondblclick;
277     [NotEnumerable] attribute EventListener ondrag;
278     [NotEnumerable] attribute EventListener ondragend;
279     [NotEnumerable] attribute EventListener ondragenter;
280     [NotEnumerable] attribute EventListener ondragleave;
281     [NotEnumerable] attribute EventListener ondragover;
282     [NotEnumerable] attribute EventListener ondragstart;
283     [NotEnumerable] attribute EventListener ondrop;
284     [NotEnumerable] attribute EventListener onerror;
285     [NotEnumerable] attribute EventListener onfocus;
286     [NotEnumerable] attribute EventListener oninput;
287     [NotEnumerable] attribute EventListener oninvalid;
288     [NotEnumerable] attribute EventListener onkeydown;
289     [NotEnumerable] attribute EventListener onkeypress;
290     [NotEnumerable] attribute EventListener onkeyup;
291     [NotEnumerable] attribute EventListener onload;
292     [NotEnumerable] attribute EventListener onmousedown;
293     [NotEnumerable] attribute EventListener onmouseenter;
294     [NotEnumerable] attribute EventListener onmouseleave;
295     [NotEnumerable] attribute EventListener onmousemove;
296     [NotEnumerable] attribute EventListener onmouseout;
297     [NotEnumerable] attribute EventListener onmouseover;
298     [NotEnumerable] attribute EventListener onmouseup;
299     [NotEnumerable] attribute EventListener onmousewheel;
300     [NotEnumerable] attribute EventListener onreadystatechange;
301     [NotEnumerable] attribute EventListener onscroll;
302     [NotEnumerable] attribute EventListener onselect;
303     [NotEnumerable] attribute EventListener onsubmit;
304
305     // attribute [NotEnumerable] EventListener oncanplay;
306     // attribute [NotEnumerable] EventListener oncanplaythrough;
307     // attribute [NotEnumerable] EventListener ondurationchange;
308     // attribute [NotEnumerable] EventListener onemptied;
309     // attribute [NotEnumerable] EventListener onended;
310     // attribute [NotEnumerable] EventListener onloadeddata;
311     // attribute [NotEnumerable] EventListener onloadedmetadata;
312     // attribute [NotEnumerable] EventListener onloadstart;
313     // attribute [NotEnumerable] EventListener onpause;
314     // attribute [NotEnumerable] EventListener onplay;
315     // attribute [NotEnumerable] EventListener onplaying;
316     // attribute [NotEnumerable] EventListener onprogress;
317     // attribute [NotEnumerable] EventListener onratechange;
318     // attribute [NotEnumerable] EventListener onseeked;
319     // attribute [NotEnumerable] EventListener onseeking;
320     // attribute [NotEnumerable] EventListener onshow;
321     // attribute [NotEnumerable] EventListener onstalled;
322     // attribute [NotEnumerable] EventListener onsuspend;
323     // attribute [NotEnumerable] EventListener ontimeupdate;
324     // attribute [NotEnumerable] EventListener onvolumechange;
325     // attribute [NotEnumerable] EventListener onwaiting;
326
327     // WebKit extensions
328     [NotEnumerable] attribute EventListener onbeforecut;
329     [NotEnumerable] attribute EventListener oncut;
330     [NotEnumerable] attribute EventListener onbeforecopy;
331     [NotEnumerable] attribute EventListener oncopy;
332     [NotEnumerable] attribute EventListener onbeforepaste;
333     [NotEnumerable] attribute EventListener onpaste;
334     [NotEnumerable] attribute EventListener onreset;
335     [NotEnumerable] attribute EventListener onsearch;
336     [NotEnumerable] attribute EventListener onselectstart;
337     [NotEnumerable] attribute EventListener onselectionchange;
338     [NotEnumerable,Conditional=TOUCH_EVENTS] attribute EventListener ontouchstart;
339     [NotEnumerable,Conditional=TOUCH_EVENTS] attribute EventListener ontouchmove;
340     [NotEnumerable,Conditional=TOUCH_EVENTS] attribute EventListener ontouchend;
341     [NotEnumerable,Conditional=TOUCH_EVENTS] attribute EventListener ontouchcancel;
342     [NotEnumerable, Conditional=FULLSCREEN_API] attribute EventListener onwebkitfullscreenchange;
343     [NotEnumerable, Conditional=FULLSCREEN_API] attribute EventListener onwebkitfullscreenerror;
344     [NotEnumerable, Conditional=POINTER_LOCK] attribute EventListener onwebkitpointerlockchange;
345     [NotEnumerable, Conditional=POINTER_LOCK] attribute EventListener onwebkitpointerlockerror;
346     [NotEnumerable, Conditional=CSP_NEXT] attribute EventListener onsecuritypolicyviolation;
347 #endif
348
349 #if defined(ENABLE_TOUCH_EVENTS) && ENABLE_TOUCH_EVENTS
350     [ReturnNewObject] Touch createTouch([Default=Undefined] optional DOMWindow window,
351                                                      [Default=Undefined] optional EventTarget target,
352                                                      [Default=Undefined] optional long identifier,
353                                                      [Default=Undefined] optional long pageX,
354                                                      [Default=Undefined] optional long pageY,
355                                                      [Default=Undefined] optional long screenX,
356                                                      [Default=Undefined] optional long screenY,
357                                                      [Default=Undefined] optional long webkitRadiusX,
358                                                      [Default=Undefined] optional long webkitRadiusY,
359                                                      [Default=Undefined] optional float webkitRotationAngle,
360                                                      [Default=Undefined] optional float webkitForce)
361         raises (DOMException);
362     [ReturnNewObject, Custom] TouchList createTouchList()
363         raises (DOMException);
364 #endif
365
366 #if defined(ENABLE_CUSTOM_ELEMENTS) && ENABLE_CUSTOM_ELEMENTS
367     [Conditional=CUSTOM_ELEMENTS, ImplementedAs=registerElement, CallWith=ScriptState]
368     CustomElementConstructor webkitRegister(DOMString name, optional Dictionary options) raises(DOMException);
369     [ReturnNewObject]
370     Element createElement(DOMString localName, [TreatNullAs=NullString] DOMString typeExtension) raises (DOMException);
371     [ReturnNewObject]
372     Element createElementNS([TreatNullAs=NullString] DOMString namespaceURI, DOMString qualifiedName,
373                             [TreatNullAs=NullString] DOMString typeExtension) raises (DOMException);
374 #endif
375
376 #if defined(LANGUAGE_CPP) && LANGUAGE_CPP
377     // Extra WebCore methods exposed to allow compile-time casting in C++
378     boolean isHTMLDocument();
379 #endif
380
381     // Page visibility API.
382     [Conditional=PAGE_VISIBILITY_API] readonly attribute DOMString visibilityState;
383     [Conditional=PAGE_VISIBILITY_API] readonly attribute boolean hidden;
384
385     // Security Policy API: http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html#script-interfaces
386     [Conditional=CSP_NEXT] readonly attribute DOMSecurityPolicy securityPolicy;
387
388 };
389