1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/interfaces/events/nsIDOMEventTarget.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,311 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "domstubs.idl"
1.10 +
1.11 +%{C++
1.12 +#include "mozilla/EventForwards.h"
1.13 +#include "mozilla/dom/Nullable.h"
1.14 +#include "js/TypeDecls.h"
1.15 +
1.16 +using mozilla::dom::Nullable;
1.17 +
1.18 +namespace mozilla {
1.19 +class EventChainPostVisitor;
1.20 +class EventChainPreVisitor;
1.21 +class EventListenerManager;
1.22 +namespace dom {
1.23 +class EventTarget;
1.24 +} // namespace dom
1.25 +} // namespace mozilla
1.26 +
1.27 +class nsPresContext;
1.28 +%}
1.29 +
1.30 +/**
1.31 + * The nsIDOMEventTarget interface is the interface implemented by all
1.32 + * event targets in the Document Object Model.
1.33 + *
1.34 + * For more information on this interface please see
1.35 + * http://www.w3.org/TR/DOM-Level-2-Events/
1.36 + */
1.37 +
1.38 +[ptr] native WidgetEventPtr(mozilla::WidgetEvent);
1.39 +[ptr] native nsPresContextPtr(nsPresContext);
1.40 +[ptr] native nsEventStatusPtr(nsEventStatus);
1.41 +[ptr] native JSContextPtr(JSContext);
1.42 +[ref] native EventChainPostVisitorRef(mozilla::EventChainPostVisitor);
1.43 +[ref] native EventChainPreVisitorRef(mozilla::EventChainPreVisitor);
1.44 +[ptr] native EventListenerManagerPtr(mozilla::EventListenerManager);
1.45 +[ptr] native EventTargetPtr(mozilla::dom::EventTarget);
1.46 +
1.47 +interface nsIScriptContext;
1.48 +interface nsIDOMEventListener;
1.49 +interface nsIDOMEvent;
1.50 +
1.51 +[scriptable, builtinclass, uuid(b128448c-7b53-4769-92cb-cd6eafee676c)]
1.52 +interface nsIDOMEventTarget : nsISupports
1.53 +{
1.54 + /**
1.55 + * This method allows the registration of event listeners on the event target.
1.56 + * If an EventListener is added to an EventTarget while it is processing an
1.57 + * event, it will not be triggered by the current actions but may be
1.58 + * triggered during a later stage of event flow, such as the bubbling phase.
1.59 + *
1.60 + * If multiple identical EventListeners are registered on the same
1.61 + * EventTarget with the same parameters the duplicate instances are
1.62 + * discarded. They do not cause the EventListener to be called twice
1.63 + * and since they are discarded they do not need to be removed with the
1.64 + * removeEventListener method.
1.65 + *
1.66 + * @param type The event type for which the user is registering
1.67 + * @param listener The listener parameter takes an interface
1.68 + * implemented by the user which contains the methods
1.69 + * to be called when the event occurs.
1.70 + * @param useCapture If true, useCapture indicates that the user
1.71 + * wishes to initiate capture. After initiating
1.72 + * capture, all events of the specified type will be
1.73 + * dispatched to the registered EventListener before
1.74 + * being dispatched to any EventTargets beneath them
1.75 + * in the tree. Events which are bubbling upward
1.76 + * through the tree will not trigger an
1.77 + * EventListener designated to use capture.
1.78 + * @param wantsUntrusted If false, the listener will not receive any
1.79 + * untrusted events (see above), if true, the
1.80 + * listener will receive events whether or not
1.81 + * they're trusted
1.82 + */
1.83 + [optional_argc] void addEventListener(in DOMString type,
1.84 + in nsIDOMEventListener listener,
1.85 + [optional] in boolean useCapture,
1.86 + [optional] in boolean wantsUntrusted);
1.87 +
1.88 + /**
1.89 + * addSystemEventListener() adds an event listener of aType to the system
1.90 + * group. Typically, core code should use system group for listening to
1.91 + * content (i.e., non-chrome) element's events. If core code uses
1.92 + * nsIDOMEventTarget::AddEventListener for a content node, it means
1.93 + * that the listener cannot listen the event when web content calls
1.94 + * stopPropagation() of the event.
1.95 + *
1.96 + * @param aType An event name you're going to handle.
1.97 + * @param aListener An event listener.
1.98 + * @param aUseCapture TRUE if you want to listen the event in capturing
1.99 + * phase. Otherwise, FALSE.
1.100 + * @param aWantsUntrusted TRUE if you want to handle untrusted events.
1.101 + * Otherwise, FALSE.
1.102 + * @return NS_OK if succeed. Otherwise, NS_ERROR_*.
1.103 + */
1.104 + [noscript, optional_argc] void addSystemEventListener(
1.105 + in DOMString type,
1.106 + in nsIDOMEventListener listener,
1.107 + [optional] in boolean aUseCapture,
1.108 + [optional] in boolean aWantsUntrusted);
1.109 +
1.110 +%{C++
1.111 + // non-virtual so it won't affect the vtable
1.112 + nsresult AddEventListener(const nsAString& aType,
1.113 + nsIDOMEventListener* aListener,
1.114 + bool aUseCapture)
1.115 + {
1.116 + return AddEventListener(aType, aListener, aUseCapture, false, 1);
1.117 + }
1.118 + // non-virtual so it won't affect the vtable
1.119 + nsresult AddEventListener(const nsAString& aType,
1.120 + nsIDOMEventListener* aListener,
1.121 + bool aUseCapture,
1.122 + bool aWantsUntrusted)
1.123 + {
1.124 + return AddEventListener(aType, aListener, aUseCapture, aWantsUntrusted, 2);
1.125 + }
1.126 + // non-virtual so it won't affect the vtable
1.127 + nsresult AddSystemEventListener(const nsAString& aType,
1.128 + nsIDOMEventListener* aListener,
1.129 + bool aUseCapture)
1.130 + {
1.131 + return AddSystemEventListener(aType, aListener, aUseCapture, false, 1);
1.132 + }
1.133 + // non-virtual so it won't affect the vtable
1.134 + nsresult AddSystemEventListener(const nsAString& aType,
1.135 + nsIDOMEventListener* aListener,
1.136 + bool aUseCapture,
1.137 + bool aWantsUntrusted)
1.138 + {
1.139 + return AddSystemEventListener(aType, aListener, aUseCapture,
1.140 + aWantsUntrusted, 2);
1.141 + }
1.142 +%}
1.143 +
1.144 + /**
1.145 + * This method allows the removal of event listeners from the event
1.146 + * target. If an EventListener is removed from an EventTarget while it
1.147 + * is processing an event, it will not be triggered by the current actions.
1.148 + * EventListeners can never be invoked after being removed.
1.149 + * Calling removeEventListener with arguments which do not identify any
1.150 + * currently registered EventListener on the EventTarget has no effect.
1.151 + *
1.152 + * @param type Specifies the event type of the EventListener being
1.153 + * removed.
1.154 + * @param listener The EventListener parameter indicates the
1.155 + * EventListener to be removed.
1.156 + * @param useCapture Specifies whether the EventListener being
1.157 + * removed was registered as a capturing listener or
1.158 + * not. If a listener was registered twice, one with
1.159 + * capture and one without, each must be removed
1.160 + * separately. Removal of a capturing listener does
1.161 + * not affect a non-capturing version of the same
1.162 + * listener, and vice versa.
1.163 + */
1.164 + void removeEventListener(in DOMString type,
1.165 + in nsIDOMEventListener listener,
1.166 + [optional] in boolean useCapture);
1.167 +
1.168 + /**
1.169 + * removeSystemEventListener() should be used if you have used
1.170 + * addSystemEventListener().
1.171 + */
1.172 + [noscript] void removeSystemEventListener(
1.173 + in DOMString type,
1.174 + in nsIDOMEventListener listener,
1.175 + [optional] in boolean aUseCapture);
1.176 +
1.177 + /**
1.178 + * This method allows the dispatch of events into the implementations
1.179 + * event model. Events dispatched in this manner will have the same
1.180 + * capturing and bubbling behavior as events dispatched directly by the
1.181 + * implementation. The target of the event is the EventTarget on which
1.182 + * dispatchEvent is called.
1.183 + *
1.184 + * @param evt Specifies the event type, behavior, and contextual
1.185 + * information to be used in processing the event.
1.186 + * @return Indicates whether any of the listeners which handled the
1.187 + * event called preventDefault. If preventDefault was called
1.188 + * the value is false, else the value is true.
1.189 + * @throws INVALID_STATE_ERR: Raised if the Event's type was
1.190 + * not specified by initializing the event before
1.191 + * dispatchEvent was called. Specification of the Event's
1.192 + * type as null or an empty string will also trigger this
1.193 + * exception.
1.194 + */
1.195 + boolean dispatchEvent(in nsIDOMEvent evt)
1.196 + raises(DOMException);
1.197 +
1.198 + /**
1.199 + * Returns the nsIDOMEventTarget object which should be used as the target
1.200 + * of DOMEvents.
1.201 + * Usually |this| is returned, but for example global object returns
1.202 + * the outer object.
1.203 + */
1.204 + [notxpcom, nostdcall] EventTargetPtr GetTargetForDOMEvent();
1.205 +
1.206 + /**
1.207 + * Returns the nsIDOMEventTarget object which should be used as the target
1.208 + * of the event and when constructing event target chain.
1.209 + * Usually |this| is returned, but for example global object returns
1.210 + * the inner object.
1.211 + */
1.212 + [notxpcom, nostdcall] EventTargetPtr GetTargetForEventTargetChain();
1.213 +
1.214 + /**
1.215 + * Called before the capture phase of the event flow.
1.216 + * This is used to create the event target chain and implementations
1.217 + * should set the necessary members of EventChainPreVisitor.
1.218 + * At least aVisitor.mCanHandle must be set,
1.219 + * usually also aVisitor.mParentTarget if mCanHandle is PR_TRUE.
1.220 + * First one tells that this object can handle the aVisitor.mEvent event and
1.221 + * the latter one is the possible parent object for the event target chain.
1.222 + * @see EventDispatcher.h for more documentation about aVisitor.
1.223 + *
1.224 + * @param aVisitor the visitor object which is used to create the
1.225 + * event target chain for event dispatching.
1.226 + *
1.227 + * @note Only EventDispatcher should call this method.
1.228 + */
1.229 + [noscript, nostdcall]
1.230 + void PreHandleEvent(in EventChainPreVisitorRef aVisitor);
1.231 +
1.232 + /**
1.233 + * If EventChainPreVisitor.mWantsWillHandleEvent is set PR_TRUE,
1.234 + * called just before possible event handlers on this object will be called.
1.235 + */
1.236 + [noscript, nostdcall]
1.237 + void WillHandleEvent(in EventChainPostVisitorRef aVisitor);
1.238 +
1.239 + /**
1.240 + * Called after the bubble phase of the system event group.
1.241 + * The default handling of the event should happen here.
1.242 + * @param aVisitor the visitor object which is used during post handling.
1.243 + *
1.244 + * @see EventDispatcher.h for documentation about aVisitor.
1.245 + * @note Only EventDispatcher should call this method.
1.246 + */
1.247 + [noscript, nostdcall]
1.248 + void PostHandleEvent(in EventChainPostVisitorRef aVisitor);
1.249 +
1.250 + /**
1.251 + * Dispatch an event.
1.252 + * @param aEvent the event that is being dispatched.
1.253 + * @param aDOMEvent the event that is being dispatched, use if you want to
1.254 + * dispatch nsIDOMEvent, not only WidgetEvent.
1.255 + * @param aPresContext the current presentation context, can be nullptr.
1.256 + * @param aEventStatus the status returned from the function, can be nullptr.
1.257 + *
1.258 + * @note If both aEvent and aDOMEvent are used, aEvent must be the internal
1.259 + * event of the aDOMEvent.
1.260 + *
1.261 + * If aDOMEvent is not nullptr (in which case aEvent can be nullptr) it is used
1.262 + * for dispatching, otherwise aEvent is used.
1.263 + *
1.264 + * @deprecated This method is here just until all the callers outside Gecko
1.265 + * have been converted to use nsIDOMEventTarget::dispatchEvent.
1.266 + */
1.267 + [noscript, nostdcall]
1.268 + void DispatchDOMEvent(in WidgetEventPtr aEvent,
1.269 + in nsIDOMEvent aDOMEvent,
1.270 + in nsPresContextPtr aPresContext,
1.271 + in nsEventStatusPtr aEventStatus);
1.272 +
1.273 + /**
1.274 + * Get the script context in which the event handlers should be run.
1.275 + * May return null.
1.276 + * @note Caller *must* check the value of aRv.
1.277 + */
1.278 + [notxpcom, nostdcall]
1.279 + nsIScriptContext GetContextForEventHandlers(out nsresult aRv);
1.280 +
1.281 + /**
1.282 + * If the method above returns null, but a success code, this method
1.283 + * is called.
1.284 + */
1.285 + [notxpcom, nostdcall] JSContextPtr GetJSContextForEventHandlers();
1.286 +};
1.287 +
1.288 +%{C++
1.289 +
1.290 +#define NS_IMPL_DOMTARGET_DEFAULTS(_class) \
1.291 +mozilla::dom::EventTarget* _class::GetTargetForDOMEvent() { return this; } \
1.292 +mozilla::dom::EventTarget* _class::GetTargetForEventTargetChain() { return this; } \
1.293 +nsresult _class::WillHandleEvent(mozilla::EventChainPostVisitor& aVisitor) { return NS_OK; } \
1.294 +JSContext* _class::GetJSContextForEventHandlers() { return nullptr; }
1.295 +
1.296 +#define NS_IMPL_REMOVE_SYSTEM_EVENT_LISTENER(aClass) \
1.297 +NS_IMETHODIMP \
1.298 +aClass::RemoveSystemEventListener(const nsAString& aType, \
1.299 + nsIDOMEventListener *aListener, \
1.300 + bool aUseCapture) \
1.301 +{ \
1.302 + mozilla::EventListenerManager* listenerManager = \
1.303 + GetExistingListenerManager(); \
1.304 + if (!listenerManager) { \
1.305 + return NS_OK; \
1.306 + } \
1.307 + mozilla::EventListenerFlags flags; \
1.308 + flags.mInSystemGroup = true; \
1.309 + flags.mCapture = aUseCapture; \
1.310 + listenerManager->RemoveEventListenerByType(aListener, aType, flags); \
1.311 + return NS_OK; \
1.312 +}
1.313 +
1.314 +%}
