The Tor Browser / file revision

 /* -*- 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(b128448c-7b53-4769-92cb-cd6eafee676c)]

 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; \

 }

 %}