/* -*- 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); /** * If the method above returns null, but a success code, this method * is called. */ [notxpcom, nostdcall] JSContextPtr GetJSContextForEventHandlers(); }; %{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; } \ JSContext* _class::GetJSContextForEventHandlers() { return nullptr; } #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; \ } %}