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