[Web IDL] Add support for [TreatNullAs=EmptyString] and use it
[WebKit-https.git] / Source / WebCore / dom / Element.idl
1 /*
2  * Copyright (C) 2006, 2007, 2009, 2015 Apple Inc. All rights reserved.
3  * Copyright (C) 2006 Samuel Weinig <sam.weinig@gmail.com>
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     JSCustomHeader,
23     JSGenerateToNativeObject,
24 ] interface Element : Node {
25
26     // DOM Level 1 Core
27
28     readonly attribute DOMString? tagName;
29
30     DOMString? getAttribute([Default=Undefined] optional DOMString name);
31     [ObjCLegacyUnnamedParameters, RaisesException] void setAttribute([Default=Undefined] optional DOMString name,
32                                      [Default=Undefined] optional DOMString value);
33     void removeAttribute([Default=Undefined] optional DOMString name);
34     Attr getAttributeNode([Default=Undefined] optional DOMString name);
35     [RaisesException] Attr setAttributeNode([Default=Undefined] optional Attr newAttr);
36     [RaisesException] Attr removeAttributeNode([Default=Undefined] optional Attr oldAttr);
37
38 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
39     [ImplementedAs=getElementsByTagNameForObjC] NodeList getElementsByTagName([Default=Undefined] optional DOMString name);
40 #else
41     HTMLCollection getElementsByTagName([Default=Undefined] optional DOMString name);
42 #endif
43
44 #if !defined(LANGUAGE_OBJECTIVE_C)
45     // For ObjC this is defined on Node for legacy support.
46     readonly attribute NamedNodeMap     attributes;
47     boolean            hasAttributes();
48 #endif
49
50     // DOM Level 2 Core
51
52     [ObjCLegacyUnnamedParameters] DOMString? getAttributeNS([Default=Undefined] optional DOMString? namespaceURI, [Default=Undefined] optional DOMString localName);
53     [ObjCLegacyUnnamedParameters, RaisesException] void setAttributeNS([Default=Undefined] optional DOMString? namespaceURI,
54         [Default=Undefined] optional DOMString qualifiedName,
55         [Default=Undefined] optional DOMString value);
56     [ObjCLegacyUnnamedParameters] void removeAttributeNS(DOMString? namespaceURI, DOMString localName);
57
58 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
59     [ObjCLegacyUnnamedParameters, ImplementedAs=getElementsByTagNameNSForObjC] NodeList getElementsByTagNameNS(optional DOMString namespaceURI, optional DOMString localName);
60 #else
61     HTMLCollection getElementsByTagNameNS([Default=Undefined] optional DOMString? namespaceURI, [Default=Undefined] optional DOMString localName);
62 #endif
63     [ObjCLegacyUnnamedParameters] Attr getAttributeNodeNS([Default=Undefined] optional DOMString? namespaceURI, [Default=Undefined] optional DOMString localName);
64     [RaisesException] Attr setAttributeNodeNS([Default=Undefined] optional Attr newAttr);
65     boolean hasAttribute(DOMString name);
66     [ObjCLegacyUnnamedParameters] boolean hasAttributeNS([Default=Undefined] optional DOMString? namespaceURI, [Default=Undefined] optional DOMString localName);
67
68     [ImplementedAs=cssomStyle] readonly attribute CSSStyleDeclaration style;
69
70     // DOM 4
71 #if !defined(LANGUAGE_OBJECTIVE_C) || !LANGUAGE_OBJECTIVE_C
72     [Reflect] attribute DOMString id;
73 #endif
74
75     // Common extensions
76
77 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
78     readonly attribute long offsetLeft;
79     readonly attribute long offsetTop;
80     readonly attribute long offsetWidth;
81     readonly attribute long offsetHeight;
82     readonly attribute long clientLeft;
83     readonly attribute long clientTop;
84     readonly attribute long clientWidth;
85     readonly attribute long clientHeight;
86 #else
87     readonly attribute double offsetLeft;
88     readonly attribute double offsetTop;
89     readonly attribute double offsetWidth;
90     readonly attribute double offsetHeight;
91     readonly attribute double clientLeft;
92     readonly attribute double clientTop;
93     readonly attribute double clientWidth;
94     readonly attribute double clientHeight;
95 #endif
96
97     attribute long scrollLeft;
98     attribute long scrollTop;
99     readonly attribute long scrollWidth;
100     readonly attribute long scrollHeight;
101
102     [ImplementedAs=bindingsOffsetParent] readonly attribute Element offsetParent;
103
104     void focus();
105     void blur();
106     void scrollIntoView(optional boolean alignWithTop);
107
108     // WebKit extensions
109
110     void scrollIntoViewIfNeeded(optional boolean centerIfNeeded);
111     void scrollByLines([Default=Undefined] optional long lines);
112     void scrollByPages([Default=Undefined] optional long pages);
113
114     // HTML 5
115 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
116     [ImplementedAs=getElementsByClassNameForObjC] NodeList getElementsByClassName([Default=Undefined] optional DOMString name);
117 #else
118     HTMLCollection getElementsByClassName([Default=Undefined] optional DOMString name);
119 #endif
120     [TreatNullAs=EmptyString, SetterRaisesException] attribute DOMString innerHTML;
121     [TreatNullAs=EmptyString, SetterRaisesException] attribute DOMString outerHTML;
122              
123
124     [Reflect=class] attribute DOMString className;
125     [PutForwards=value] readonly attribute DOMTokenList classList;
126
127 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
128     readonly attribute DOMStringMap dataset;
129 #endif
130
131     [RaisesException] boolean matches(DOMString selectors);
132     [RaisesException] Element closest(DOMString selectors);    
133     [ImplementedAs=matches, RaisesException] boolean webkitMatchesSelector(DOMString selectors);
134
135 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
136     // CSSOM View Module API
137     ClientRectList getClientRects();
138     ClientRect getBoundingClientRect();
139 #endif
140
141 #if defined(LANGUAGE_OBJECTIVE_C) && LANGUAGE_OBJECTIVE_C
142     // Objective-C extensions
143     readonly attribute DOMString innerText;
144 #endif
145
146 #if defined(ENABLE_FULLSCREEN_API) && ENABLE_FULLSCREEN_API
147     // Mozilla version
148     const unsigned short ALLOW_KEYBOARD_INPUT = 1;
149     void webkitRequestFullScreen([Default=Undefined] optional unsigned short flags);
150
151     // W3C version
152     void webkitRequestFullscreen();
153 #endif
154
155 #if defined(ENABLE_INDIE_UI) && ENABLE_INDIE_UI
156     [Reflect] attribute DOMString uiactions;
157 #endif
158
159     [Conditional=POINTER_LOCK] void requestPointerLock();
160
161     // CSS Regions API
162     [Conditional=CSS_REGIONS] readonly attribute DOMString webkitRegionOverset;
163     [Conditional=CSS_REGIONS] sequence<Range> webkitGetRegionFlowRanges();
164
165     // Shadow DOM API
166 #if defined(LANGUAGE_JAVASCRIPT) && LANGUAGE_JAVASCRIPT
167     [Conditional=SHADOW_DOM, RaisesException] ShadowRoot attachShadow(Dictionary options);
168     [Conditional=SHADOW_DOM, ImplementedAs=shadowRootForBindings, CallWith=ScriptState] readonly attribute ShadowRoot shadowRoot;
169     [Conditional=SHADOW_DOM, Reflect] attribute DOMString slot;
170 #endif
171
172     // Event Handlers
173
174     // Unique to Element and Document
175     // FIXME: Should these be exposed on Window as well (and therefore moved to GlobalEventHandlers.idl)?
176     [NotEnumerable] attribute EventHandler onbeforecopy;
177     [NotEnumerable] attribute EventHandler onbeforecut;
178     [NotEnumerable] attribute EventHandler onbeforepaste;
179     [NotEnumerable] attribute EventHandler oncopy;
180     [NotEnumerable] attribute EventHandler oncut;
181     [NotEnumerable] attribute EventHandler onpaste;
182     [NotEnumerable] attribute EventHandler onselectstart;
183     [NotEnumerable, Conditional=FULLSCREEN_API] attribute EventHandler onwebkitfullscreenchange;
184     [NotEnumerable, Conditional=FULLSCREEN_API] attribute EventHandler onwebkitfullscreenerror;
185
186     // Unique to Element and DOMWindow
187     // FIXME: Should these be exposed on Document as well (and therefore moved to GlobalEventHandlers.idl)?
188     [NotEnumerable] attribute EventHandler onanimationend;
189     [NotEnumerable] attribute EventHandler onanimationiteration;
190     [NotEnumerable] attribute EventHandler onanimationstart;
191     [NotEnumerable] attribute EventHandler ontransitionend;
192     [NotEnumerable] attribute EventHandler onwebkitanimationend;
193     [NotEnumerable] attribute EventHandler onwebkitanimationiteration;
194     [NotEnumerable] attribute EventHandler onwebkitanimationstart;
195     [NotEnumerable] attribute EventHandler onwebkittransitionend;
196     [NotEnumerable, Conditional=IOS_GESTURE_EVENTS] attribute EventHandler ongesturechange;
197     [NotEnumerable, Conditional=IOS_GESTURE_EVENTS] attribute EventHandler ongestureend;
198     [NotEnumerable, Conditional=IOS_GESTURE_EVENTS] attribute EventHandler ongesturestart;
199
200     // Unique to Element, HTMLBodyElement and HTMLFrameSetElement
201     [NotEnumerable] attribute EventHandler onfocusin;
202     [NotEnumerable] attribute EventHandler onfocusout;
203
204     // Unique to Element
205     [NotEnumerable] attribute EventHandler onbeforeload;
206     [NotEnumerable, Conditional=ENCRYPTED_MEDIA] attribute EventHandler onwebkitkeyadded;
207     [NotEnumerable, Conditional=ENCRYPTED_MEDIA] attribute EventHandler onwebkitkeyerror;
208     [NotEnumerable, Conditional=ENCRYPTED_MEDIA] attribute EventHandler onwebkitkeymessage;
209     [NotEnumerable, Conditional=ENCRYPTED_MEDIA|ENCRYPTED_MEDIA_V2] attribute EventHandler onwebkitneedkey;
210     [NotEnumerable, Conditional=VIDEO_PRESENTATION_MODE] attribute EventHandler onwebkitpresentationmodechanged;
211     [NotEnumerable, Conditional=WIRELESS_PLAYBACK_TARGET] attribute EventHandler onwebkitcurrentplaybacktargetiswirelesschanged;
212     [NotEnumerable, Conditional=WIRELESS_PLAYBACK_TARGET] attribute EventHandler onwebkitplaybacktargetavailabilitychanged;
213 };
214
215 Element implements ChildNode;
216 Element implements ParentNode;
217 Element implements NonDocumentTypeChildNode;
218 Element implements GlobalEventHandlers;