The Tor Browser / file comparison

comparison: dom/interfaces/events/nsIDOMEventTarget.idl

dom/interfaces/events/nsIDOMEventTarget.idl

changeset 2
7e26c7da4463
equal deleted inserted replaced
-1:000000000000 0:8056b1d7de4e
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6 #include "domstubs.idl"
7
8 %{C++
9 #include "mozilla/EventForwards.h"
10 #include "mozilla/dom/Nullable.h"
11 #include "js/TypeDecls.h"
12
13 using mozilla::dom::Nullable;
14
15 namespace mozilla {
16 class EventChainPostVisitor;
17 class EventChainPreVisitor;
18 class EventListenerManager;
19 namespace dom {
20 class EventTarget;
21 } // namespace dom
22 } // namespace mozilla
23
24 class nsPresContext;
25 %}
26
27 /**
28 * The nsIDOMEventTarget interface is the interface implemented by all
29 * event targets in the Document Object Model.
30 *
31 * For more information on this interface please see
32 * http://www.w3.org/TR/DOM-Level-2-Events/
33 */
34
35 [ptr] native WidgetEventPtr(mozilla::WidgetEvent);
36 [ptr] native nsPresContextPtr(nsPresContext);
37 [ptr] native nsEventStatusPtr(nsEventStatus);
38 [ptr] native JSContextPtr(JSContext);
39 [ref] native EventChainPostVisitorRef(mozilla::EventChainPostVisitor);
40 [ref] native EventChainPreVisitorRef(mozilla::EventChainPreVisitor);
41 [ptr] native EventListenerManagerPtr(mozilla::EventListenerManager);
42 [ptr] native EventTargetPtr(mozilla::dom::EventTarget);
43
44 interface nsIScriptContext;
45 interface nsIDOMEventListener;
46 interface nsIDOMEvent;
47
48 [scriptable, builtinclass, uuid(b128448c-7b53-4769-92cb-cd6eafee676c)]
49 interface nsIDOMEventTarget : nsISupports
50 {
51 /**
52 * This method allows the registration of event listeners on the event target.
53 * If an EventListener is added to an EventTarget while it is processing an
54 * event, it will not be triggered by the current actions but may be
55 * triggered during a later stage of event flow, such as the bubbling phase.
56 *
57 * If multiple identical EventListeners are registered on the same
58 * EventTarget with the same parameters the duplicate instances are
59 * discarded. They do not cause the EventListener to be called twice
60 * and since they are discarded they do not need to be removed with the
61 * removeEventListener method.
62 *
63 * @param type The event type for which the user is registering
64 * @param listener The listener parameter takes an interface
65 * implemented by the user which contains the methods
66 * to be called when the event occurs.
67 * @param useCapture If true, useCapture indicates that the user
68 * wishes to initiate capture. After initiating
69 * capture, all events of the specified type will be
70 * dispatched to the registered EventListener before
71 * being dispatched to any EventTargets beneath them
72 * in the tree. Events which are bubbling upward
73 * through the tree will not trigger an
74 * EventListener designated to use capture.
75 * @param wantsUntrusted If false, the listener will not receive any
76 * untrusted events (see above), if true, the
77 * listener will receive events whether or not
78 * they're trusted
79 */
80 [optional_argc] void addEventListener(in DOMString type,
81 in nsIDOMEventListener listener,
82 [optional] in boolean useCapture,
83 [optional] in boolean wantsUntrusted);
84
85 /**
86 * addSystemEventListener() adds an event listener of aType to the system
87 * group. Typically, core code should use system group for listening to
88 * content (i.e., non-chrome) element's events. If core code uses
89 * nsIDOMEventTarget::AddEventListener for a content node, it means
90 * that the listener cannot listen the event when web content calls
91 * stopPropagation() of the event.
92 *
93 * @param aType An event name you're going to handle.
94 * @param aListener An event listener.
95 * @param aUseCapture TRUE if you want to listen the event in capturing
96 * phase. Otherwise, FALSE.
97 * @param aWantsUntrusted TRUE if you want to handle untrusted events.
98 * Otherwise, FALSE.
99 * @return NS_OK if succeed. Otherwise, NS_ERROR_*.
100 */
101 [noscript, optional_argc] void addSystemEventListener(
102 in DOMString type,
103 in nsIDOMEventListener listener,
104 [optional] in boolean aUseCapture,
105 [optional] in boolean aWantsUntrusted);
106
107 %{C++
108 // non-virtual so it won't affect the vtable
109 nsresult AddEventListener(const nsAString& aType,
110 nsIDOMEventListener* aListener,
111 bool aUseCapture)
112 {
113 return AddEventListener(aType, aListener, aUseCapture, false, 1);
114 }
115 // non-virtual so it won't affect the vtable
116 nsresult AddEventListener(const nsAString& aType,
117 nsIDOMEventListener* aListener,
118 bool aUseCapture,
119 bool aWantsUntrusted)
120 {
121 return AddEventListener(aType, aListener, aUseCapture, aWantsUntrusted, 2);
122 }
123 // non-virtual so it won't affect the vtable
124 nsresult AddSystemEventListener(const nsAString& aType,
125 nsIDOMEventListener* aListener,
126 bool aUseCapture)
127 {
128 return AddSystemEventListener(aType, aListener, aUseCapture, false, 1);
129 }
130 // non-virtual so it won't affect the vtable
131 nsresult AddSystemEventListener(const nsAString& aType,
132 nsIDOMEventListener* aListener,
133 bool aUseCapture,
134 bool aWantsUntrusted)
135 {
136 return AddSystemEventListener(aType, aListener, aUseCapture,
137 aWantsUntrusted, 2);
138 }
139 %}
140
141 /**
142 * This method allows the removal of event listeners from the event
143 * target. If an EventListener is removed from an EventTarget while it
144 * is processing an event, it will not be triggered by the current actions.
145 * EventListeners can never be invoked after being removed.
146 * Calling removeEventListener with arguments which do not identify any
147 * currently registered EventListener on the EventTarget has no effect.
148 *
149 * @param type Specifies the event type of the EventListener being
150 * removed.
151 * @param listener The EventListener parameter indicates the
152 * EventListener to be removed.
153 * @param useCapture Specifies whether the EventListener being
154 * removed was registered as a capturing listener or
155 * not. If a listener was registered twice, one with
156 * capture and one without, each must be removed
157 * separately. Removal of a capturing listener does
158 * not affect a non-capturing version of the same
159 * listener, and vice versa.
160 */
161 void removeEventListener(in DOMString type,
162 in nsIDOMEventListener listener,
163 [optional] in boolean useCapture);
164
165 /**
166 * removeSystemEventListener() should be used if you have used
167 * addSystemEventListener().
168 */
169 [noscript] void removeSystemEventListener(
170 in DOMString type,
171 in nsIDOMEventListener listener,
172 [optional] in boolean aUseCapture);
173
174 /**
175 * This method allows the dispatch of events into the implementations
176 * event model. Events dispatched in this manner will have the same
177 * capturing and bubbling behavior as events dispatched directly by the
178 * implementation. The target of the event is the EventTarget on which
179 * dispatchEvent is called.
180 *
181 * @param evt Specifies the event type, behavior, and contextual
182 * information to be used in processing the event.
183 * @return Indicates whether any of the listeners which handled the
184 * event called preventDefault. If preventDefault was called
185 * the value is false, else the value is true.
186 * @throws INVALID_STATE_ERR: Raised if the Event's type was
187 * not specified by initializing the event before
188 * dispatchEvent was called. Specification of the Event's
189 * type as null or an empty string will also trigger this
190 * exception.
191 */
192 boolean dispatchEvent(in nsIDOMEvent evt)
193 raises(DOMException);
194
195 /**
196 * Returns the nsIDOMEventTarget object which should be used as the target
197 * of DOMEvents.
198 * Usually |this| is returned, but for example global object returns
199 * the outer object.
200 */
201 [notxpcom, nostdcall] EventTargetPtr GetTargetForDOMEvent();
202
203 /**
204 * Returns the nsIDOMEventTarget object which should be used as the target
205 * of the event and when constructing event target chain.
206 * Usually |this| is returned, but for example global object returns
207 * the inner object.
208 */
209 [notxpcom, nostdcall] EventTargetPtr GetTargetForEventTargetChain();
210
211 /**
212 * Called before the capture phase of the event flow.
213 * This is used to create the event target chain and implementations
214 * should set the necessary members of EventChainPreVisitor.
215 * At least aVisitor.mCanHandle must be set,
216 * usually also aVisitor.mParentTarget if mCanHandle is PR_TRUE.
217 * First one tells that this object can handle the aVisitor.mEvent event and
218 * the latter one is the possible parent object for the event target chain.
219 * @see EventDispatcher.h for more documentation about aVisitor.
220 *
221 * @param aVisitor the visitor object which is used to create the
222 * event target chain for event dispatching.
223 *
224 * @note Only EventDispatcher should call this method.
225 */
226 [noscript, nostdcall]
227 void PreHandleEvent(in EventChainPreVisitorRef aVisitor);
228
229 /**
230 * If EventChainPreVisitor.mWantsWillHandleEvent is set PR_TRUE,
231 * called just before possible event handlers on this object will be called.
232 */
233 [noscript, nostdcall]
234 void WillHandleEvent(in EventChainPostVisitorRef aVisitor);
235
236 /**
237 * Called after the bubble phase of the system event group.
238 * The default handling of the event should happen here.
239 * @param aVisitor the visitor object which is used during post handling.
240 *
241 * @see EventDispatcher.h for documentation about aVisitor.
242 * @note Only EventDispatcher should call this method.
243 */
244 [noscript, nostdcall]
245 void PostHandleEvent(in EventChainPostVisitorRef aVisitor);
246
247 /**
248 * Dispatch an event.
249 * @param aEvent the event that is being dispatched.
250 * @param aDOMEvent the event that is being dispatched, use if you want to
251 * dispatch nsIDOMEvent, not only WidgetEvent.
252 * @param aPresContext the current presentation context, can be nullptr.
253 * @param aEventStatus the status returned from the function, can be nullptr.
254 *
255 * @note If both aEvent and aDOMEvent are used, aEvent must be the internal
256 * event of the aDOMEvent.
257 *
258 * If aDOMEvent is not nullptr (in which case aEvent can be nullptr) it is used
259 * for dispatching, otherwise aEvent is used.
260 *
261 * @deprecated This method is here just until all the callers outside Gecko
262 * have been converted to use nsIDOMEventTarget::dispatchEvent.
263 */
264 [noscript, nostdcall]
265 void DispatchDOMEvent(in WidgetEventPtr aEvent,
266 in nsIDOMEvent aDOMEvent,
267 in nsPresContextPtr aPresContext,
268 in nsEventStatusPtr aEventStatus);
269
270 /**
271 * Get the script context in which the event handlers should be run.
272 * May return null.
273 * @note Caller *must* check the value of aRv.
274 */
275 [notxpcom, nostdcall]
276 nsIScriptContext GetContextForEventHandlers(out nsresult aRv);
277
278 /**
279 * If the method above returns null, but a success code, this method
280 * is called.
281 */
282 [notxpcom, nostdcall] JSContextPtr GetJSContextForEventHandlers();
283 };
284
285 %{C++
286
287 #define NS_IMPL_DOMTARGET_DEFAULTS(_class) \
288 mozilla::dom::EventTarget* _class::GetTargetForDOMEvent() { return this; } \
289 mozilla::dom::EventTarget* _class::GetTargetForEventTargetChain() { return this; } \
290 nsresult _class::WillHandleEvent(mozilla::EventChainPostVisitor& aVisitor) { return NS_OK; } \
291 JSContext* _class::GetJSContextForEventHandlers() { return nullptr; }
292
293 #define NS_IMPL_REMOVE_SYSTEM_EVENT_LISTENER(aClass) \
294 NS_IMETHODIMP \
295 aClass::RemoveSystemEventListener(const nsAString& aType, \
296 nsIDOMEventListener *aListener, \
297 bool aUseCapture) \
298 { \
299 mozilla::EventListenerManager* listenerManager = \
300 GetExistingListenerManager(); \
301 if (!listenerManager) { \
302 return NS_OK; \
303 } \
304 mozilla::EventListenerFlags flags; \
305 flags.mInSystemGroup = true; \
306 flags.mCapture = aUseCapture; \
307 listenerManager->RemoveEventListenerByType(aListener, aType, flags); \
308 return NS_OK; \
309 }
310
311 %}

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial