diff options
Diffstat (limited to 'dom/interfaces/events/nsIDOMEventTarget.idl')
| -rw-r--r-- | dom/interfaces/events/nsIDOMEventTarget.idl | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/dom/interfaces/events/nsIDOMEventTarget.idl b/dom/interfaces/events/nsIDOMEventTarget.idl new file mode 100644 index 000000000..a7e3aae5a --- /dev/null +++ b/dom/interfaces/events/nsIDOMEventTarget.idl @@ -0,0 +1,304 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "domstubs.idl" + +%{C++ +#include "mozilla/EventForwards.h" +#include "mozilla/dom/Nullable.h" +#include "js/TypeDecls.h" + +using mozilla::dom::Nullable; + +namespace mozilla { +class EventChainPostVisitor; +class EventChainPreVisitor; +class EventListenerManager; +namespace dom { +class EventTarget; +} // namespace dom +} // namespace mozilla + +class nsPresContext; +%} + +/** + * The nsIDOMEventTarget interface is the interface implemented by all + * event targets in the Document Object Model. + * + * For more information on this interface please see + * http://www.w3.org/TR/DOM-Level-2-Events/ + */ + +[ptr] native WidgetEventPtr(mozilla::WidgetEvent); +[ptr] native nsPresContextPtr(nsPresContext); +[ptr] native nsEventStatusPtr(nsEventStatus); +[ptr] native JSContextPtr(JSContext); +[ref] native EventChainPostVisitorRef(mozilla::EventChainPostVisitor); +[ref] native EventChainPreVisitorRef(mozilla::EventChainPreVisitor); +[ptr] native EventListenerManagerPtr(mozilla::EventListenerManager); +[ptr] native EventTargetPtr(mozilla::dom::EventTarget); + +interface nsIScriptContext; +interface nsIDOMEventListener; +interface nsIDOMEvent; + +[scriptable, builtinclass, uuid(9a78ac3c-9507-4d00-b2d6-10b508d2ec31)] +interface nsIDOMEventTarget : nsISupports +{ + /** + * This method allows the registration of event listeners on the event target. + * If an EventListener is added to an EventTarget while it is processing an + * event, it will not be triggered by the current actions but may be + * triggered during a later stage of event flow, such as the bubbling phase. + * + * If multiple identical EventListeners are registered on the same + * EventTarget with the same parameters the duplicate instances are + * discarded. They do not cause the EventListener to be called twice + * and since they are discarded they do not need to be removed with the + * removeEventListener method. + * + * @param type The event type for which the user is registering + * @param listener The listener parameter takes an interface + * implemented by the user which contains the methods + * to be called when the event occurs. + * @param useCapture If true, useCapture indicates that the user + * wishes to initiate capture. After initiating + * capture, all events of the specified type will be + * dispatched to the registered EventListener before + * being dispatched to any EventTargets beneath them + * in the tree. Events which are bubbling upward + * through the tree will not trigger an + * EventListener designated to use capture. + * @param wantsUntrusted If false, the listener will not receive any + * untrusted events (see above), if true, the + * listener will receive events whether or not + * they're trusted + */ + [optional_argc] void addEventListener(in DOMString type, + in nsIDOMEventListener listener, + [optional] in boolean useCapture, + [optional] in boolean wantsUntrusted); + + /** + * addSystemEventListener() adds an event listener of aType to the system + * group. Typically, core code should use system group for listening to + * content (i.e., non-chrome) element's events. If core code uses + * nsIDOMEventTarget::AddEventListener for a content node, it means + * that the listener cannot listen the event when web content calls + * stopPropagation() of the event. + * + * @param aType An event name you're going to handle. + * @param aListener An event listener. + * @param aUseCapture TRUE if you want to listen the event in capturing + * phase. Otherwise, FALSE. + * @param aWantsUntrusted TRUE if you want to handle untrusted events. + * Otherwise, FALSE. + * @return NS_OK if succeed. Otherwise, NS_ERROR_*. + */ + [noscript, optional_argc] void addSystemEventListener( + in DOMString type, + in nsIDOMEventListener listener, + [optional] in boolean aUseCapture, + [optional] in boolean aWantsUntrusted); + +%{C++ + // non-virtual so it won't affect the vtable + nsresult AddEventListener(const nsAString& aType, + nsIDOMEventListener* aListener, + bool aUseCapture) + { + return AddEventListener(aType, aListener, aUseCapture, false, 1); + } + // non-virtual so it won't affect the vtable + nsresult AddEventListener(const nsAString& aType, + nsIDOMEventListener* aListener, + bool aUseCapture, + bool aWantsUntrusted) + { + return AddEventListener(aType, aListener, aUseCapture, aWantsUntrusted, 2); + } + // non-virtual so it won't affect the vtable + nsresult AddSystemEventListener(const nsAString& aType, + nsIDOMEventListener* aListener, + bool aUseCapture) + { + return AddSystemEventListener(aType, aListener, aUseCapture, false, 1); + } + // non-virtual so it won't affect the vtable + nsresult AddSystemEventListener(const nsAString& aType, + nsIDOMEventListener* aListener, + bool aUseCapture, + bool aWantsUntrusted) + { + return AddSystemEventListener(aType, aListener, aUseCapture, + aWantsUntrusted, 2); + } +%} + + /** + * This method allows the removal of event listeners from the event + * target. If an EventListener is removed from an EventTarget while it + * is processing an event, it will not be triggered by the current actions. + * EventListeners can never be invoked after being removed. + * Calling removeEventListener with arguments which do not identify any + * currently registered EventListener on the EventTarget has no effect. + * + * @param type Specifies the event type of the EventListener being + * removed. + * @param listener The EventListener parameter indicates the + * EventListener to be removed. + * @param useCapture Specifies whether the EventListener being + * removed was registered as a capturing listener or + * not. If a listener was registered twice, one with + * capture and one without, each must be removed + * separately. Removal of a capturing listener does + * not affect a non-capturing version of the same + * listener, and vice versa. + */ + void removeEventListener(in DOMString type, + in nsIDOMEventListener listener, + [optional] in boolean useCapture); + + /** + * removeSystemEventListener() should be used if you have used + * addSystemEventListener(). + */ + [noscript] void removeSystemEventListener( + in DOMString type, + in nsIDOMEventListener listener, + [optional] in boolean aUseCapture); + + /** + * This method allows the dispatch of events into the implementations + * event model. Events dispatched in this manner will have the same + * capturing and bubbling behavior as events dispatched directly by the + * implementation. The target of the event is the EventTarget on which + * dispatchEvent is called. + * + * @param evt Specifies the event type, behavior, and contextual + * information to be used in processing the event. + * @return Indicates whether any of the listeners which handled the + * event called preventDefault. If preventDefault was called + * the value is false, else the value is true. + * @throws INVALID_STATE_ERR: Raised if the Event's type was + * not specified by initializing the event before + * dispatchEvent was called. Specification of the Event's + * type as null or an empty string will also trigger this + * exception. + */ + boolean dispatchEvent(in nsIDOMEvent evt) + raises(DOMException); + + /** + * Returns the nsIDOMEventTarget object which should be used as the target + * of DOMEvents. + * Usually |this| is returned, but for example global object returns + * the outer object. + */ + [notxpcom, nostdcall] EventTargetPtr GetTargetForDOMEvent(); + + /** + * Returns the nsIDOMEventTarget object which should be used as the target + * of the event and when constructing event target chain. + * Usually |this| is returned, but for example global object returns + * the inner object. + */ + [notxpcom, nostdcall] EventTargetPtr GetTargetForEventTargetChain(); + + /** + * Called before the capture phase of the event flow. + * This is used to create the event target chain and implementations + * should set the necessary members of EventChainPreVisitor. + * At least aVisitor.mCanHandle must be set, + * usually also aVisitor.mParentTarget if mCanHandle is PR_TRUE. + * First one tells that this object can handle the aVisitor.mEvent event and + * the latter one is the possible parent object for the event target chain. + * @see EventDispatcher.h for more documentation about aVisitor. + * + * @param aVisitor the visitor object which is used to create the + * event target chain for event dispatching. + * + * @note Only EventDispatcher should call this method. + */ + [noscript, nostdcall] + void PreHandleEvent(in EventChainPreVisitorRef aVisitor); + + /** + * If EventChainPreVisitor.mWantsWillHandleEvent is set PR_TRUE, + * called just before possible event handlers on this object will be called. + */ + [noscript, nostdcall] + void WillHandleEvent(in EventChainPostVisitorRef aVisitor); + + /** + * Called after the bubble phase of the system event group. + * The default handling of the event should happen here. + * @param aVisitor the visitor object which is used during post handling. + * + * @see EventDispatcher.h for documentation about aVisitor. + * @note Only EventDispatcher should call this method. + */ + [noscript, nostdcall] + void PostHandleEvent(in EventChainPostVisitorRef aVisitor); + + /** + * Dispatch an event. + * @param aEvent the event that is being dispatched. + * @param aDOMEvent the event that is being dispatched, use if you want to + * dispatch nsIDOMEvent, not only WidgetEvent. + * @param aPresContext the current presentation context, can be nullptr. + * @param aEventStatus the status returned from the function, can be nullptr. + * + * @note If both aEvent and aDOMEvent are used, aEvent must be the internal + * event of the aDOMEvent. + * + * If aDOMEvent is not nullptr (in which case aEvent can be nullptr) it is used + * for dispatching, otherwise aEvent is used. + * + * @deprecated This method is here just until all the callers outside Gecko + * have been converted to use nsIDOMEventTarget::dispatchEvent. + */ + [noscript, nostdcall] + void DispatchDOMEvent(in WidgetEventPtr aEvent, + in nsIDOMEvent aDOMEvent, + in nsPresContextPtr aPresContext, + in nsEventStatusPtr aEventStatus); + + /** + * Get the script context in which the event handlers should be run. + * May return null. + * @note Caller *must* check the value of aRv. + */ + [notxpcom, nostdcall] + nsIScriptContext GetContextForEventHandlers(out nsresult aRv); +}; + +%{C++ + +#define NS_IMPL_DOMTARGET_DEFAULTS(_class) \ +mozilla::dom::EventTarget* _class::GetTargetForDOMEvent() { return this; } \ +mozilla::dom::EventTarget* _class::GetTargetForEventTargetChain() { return this; } \ +nsresult _class::WillHandleEvent(mozilla::EventChainPostVisitor& aVisitor) { return NS_OK; } + +#define NS_IMPL_REMOVE_SYSTEM_EVENT_LISTENER(aClass) \ +NS_IMETHODIMP \ +aClass::RemoveSystemEventListener(const nsAString& aType, \ + nsIDOMEventListener *aListener, \ + bool aUseCapture) \ +{ \ + mozilla::EventListenerManager* listenerManager = \ + GetExistingListenerManager(); \ + if (!listenerManager) { \ + return NS_OK; \ + } \ + mozilla::EventListenerFlags flags; \ + flags.mInSystemGroup = true; \ + flags.mCapture = aUseCapture; \ + listenerManager->RemoveEventListenerByType(aListener, aType, flags); \ + return NS_OK; \ +} + +%} |