dom/events/EventTarget.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_dom_EventTarget_h_
   8 #define mozilla_dom_EventTarget_h_
   9
  10 #include "mozilla/dom/BindingDeclarations.h"
  11 #include "mozilla/dom/Nullable.h"
  12 #include "nsISupports.h"
  13 #include "nsWrapperCache.h"
  14 #include "nsAtom.h"
  15
  16 class nsPIDOMWindowOuter;
  17 class nsIGlobalObject;
  18 class nsIDOMEventListener;
  19
  20 namespace mozilla {
  21
  22 class AsyncEventDispatcher;
  23 class ErrorResult;
  24 class EventChainPostVisitor;
  25 class EventChainPreVisitor;
  26 class EventChainVisitor;
  27 class EventListenerManager;
  28
  29 namespace dom {
  30
  31 class AddEventListenerOptionsOrBoolean;
  32 class Event;
  33 class EventListener;
  34 class EventListenerOptionsOrBoolean;
  35 class EventHandlerNonNull;
  36 class GlobalObject;
  37 class WindowProxyHolder;
  38 enum class EventCallbackDebuggerNotificationType : uint8_t;
  39
  40 // IID for the dom::EventTarget interface
  41 #define NS_EVENTTARGET_IID                           \
  42   {                                                  \
  43     0xde651c36, 0x0053, 0x4c67, {                    \
  44       0xb1, 0x3d, 0x67, 0xb9, 0x40, 0xfc, 0x82, 0xe4 \
  45     }                                                \
  46   }
  47
  48 class EventTarget : public nsISupports, public nsWrapperCache {
  49  public:
  50   NS_DECLARE_STATIC_IID_ACCESSOR(NS_EVENTTARGET_IID)
  51
  52   // WebIDL API
  53   static already_AddRefed<EventTarget> Constructor(const GlobalObject& aGlobal,
  54                                                    ErrorResult& aRv);
  55   void AddEventListener(const nsAString& aType, EventListener* aCallback,
  56                         const AddEventListenerOptionsOrBoolean& aOptions,
  57                         const Nullable<bool>& aWantsUntrusted,
  58                         ErrorResult& aRv);
  59   void RemoveEventListener(const nsAString& aType, EventListener* aCallback,
  60                            const EventListenerOptionsOrBoolean& aOptions,
  61                            ErrorResult& aRv);
  62
  63  protected:
  64   /**
  65    * This method allows addition of event listeners represented by
  66    * nsIDOMEventListener, with almost the same semantics as the
  67    * standard AddEventListener.  The one difference is that it just
  68    * has a "use capture" boolean, not an EventListenerOptions.
  69    */
  70   nsresult AddEventListener(const nsAString& aType,
  71                             nsIDOMEventListener* aListener, bool aUseCapture,
  72                             const Nullable<bool>& aWantsUntrusted);
  73
  74  public:
  75   /**
  76    * Helper methods to make the nsIDOMEventListener version of
  77    * AddEventListener simpler to call for consumers.
  78    */
  79   nsresult AddEventListener(const nsAString& aType,
  80                             nsIDOMEventListener* aListener, bool aUseCapture) {
  81     return AddEventListener(aType, aListener, aUseCapture, Nullable<bool>());
  82   }
  83   nsresult AddEventListener(const nsAString& aType,
  84                             nsIDOMEventListener* aListener, bool aUseCapture,
  85                             bool aWantsUntrusted) {
  86     return AddEventListener(aType, aListener, aUseCapture,
  87                             Nullable<bool>(aWantsUntrusted));
  88   }
  89
  90   /**
  91    * This method allows the removal of event listeners represented by
  92    * nsIDOMEventListener from the event target, with the same semantics as the
  93    * standard RemoveEventListener.
  94    */
  95   void RemoveEventListener(const nsAString& aType,
  96                            nsIDOMEventListener* aListener, bool aUseCapture);
  97   /**
  98    * RemoveSystemEventListener() should be used if you have used
  99    * AddSystemEventListener().
 100    */
 101   void RemoveSystemEventListener(const nsAString& aType,
 102                                  nsIDOMEventListener* aListener,
 103                                  bool aUseCapture);
 104
 105   /**
 106    * Add a system event listener with the default wantsUntrusted value.
 107    */
 108   nsresult AddSystemEventListener(const nsAString& aType,
 109                                   nsIDOMEventListener* aListener,
 110                                   bool aUseCapture) {
 111     return AddSystemEventListener(aType, aListener, aUseCapture,
 112                                   Nullable<bool>());
 113   }
 114
 115   /**
 116    * Add a system event listener with the given wantsUntrusted value.
 117    */
 118   nsresult AddSystemEventListener(const nsAString& aType,
 119                                   nsIDOMEventListener* aListener,
 120                                   bool aUseCapture, bool aWantsUntrusted) {
 121     return AddSystemEventListener(aType, aListener, aUseCapture,
 122                                   Nullable<bool>(aWantsUntrusted));
 123   }
 124
 125   /**
 126    * Returns the EventTarget object which should be used as the target
 127    * of DOMEvents.
 128    * Usually |this| is returned, but for example Window (inner windw) returns
 129    * the WindowProxy (outer window).
 130    */
 131   virtual EventTarget* GetTargetForDOMEvent() { return this; };
 132
 133   /**
 134    * Returns the EventTarget object which should be used as the target
 135    * of the event and when constructing event target chain.
 136    * Usually |this| is returned, but for example WindowProxy (outer window)
 137    * returns the Window (inner window).
 138    */
 139   virtual EventTarget* GetTargetForEventTargetChain() { return this; }
 140
 141   /**
 142    * The most general DispatchEvent method.  This is the one the bindings call.
 143    */
 144   virtual bool DispatchEvent(Event& aEvent, CallerType aCallerType,
 145                              ErrorResult& aRv) = 0;
 146
 147   /**
 148    * A version of DispatchEvent you can use if you really don't care whether it
 149    * succeeds or not and whether default is prevented or not.
 150    */
 151   void DispatchEvent(Event& aEvent);
 152
 153   /**
 154    * A version of DispatchEvent you can use if you really don't care whether
 155    * default is prevented or not.
 156    */
 157   void DispatchEvent(Event& aEvent, ErrorResult& aRv);
 158
 159   nsIGlobalObject* GetParentObject() const { return GetOwnerGlobal(); }
 160
 161   // Note, this takes the type in onfoo form!
 162   EventHandlerNonNull* GetEventHandler(const nsAString& aType) {
 163     RefPtr<nsAtom> type = NS_Atomize(aType);
 164     return GetEventHandler(type);
 165   }
 166
 167   // Note, this takes the type in onfoo form!
 168   void SetEventHandler(const nsAString& aType, EventHandlerNonNull* aHandler,
 169                        ErrorResult& rv);
 170
 171   // For an event 'foo' aType will be 'onfoo'.
 172   virtual void EventListenerAdded(nsAtom* aType) {}
 173
 174   // For an event 'foo' aType will be 'onfoo'.
 175   virtual void EventListenerRemoved(nsAtom* aType) {}
 176
 177   // Returns an outer window that corresponds to the inner window this event
 178   // target is associated with.  Will return null if the inner window is not the
 179   // current inner or if there is no window around at all.
 180   Nullable<WindowProxyHolder> GetOwnerGlobalForBindings();
 181   virtual nsPIDOMWindowOuter* GetOwnerGlobalForBindingsInternal() = 0;
 182
 183   // The global object this event target is associated with, if any.
 184   // This may be an inner window or some other global object.  This
 185   // will never be an outer window.
 186   virtual nsIGlobalObject* GetOwnerGlobal() const = 0;
 187
 188   /**
 189    * Get the event listener manager, creating it if it does not already exist.
 190    */
 191   virtual EventListenerManager* GetOrCreateListenerManager() = 0;
 192
 193   /**
 194    * Get the event listener manager, returning null if it does not already
 195    * exist.
 196    */
 197   virtual EventListenerManager* GetExistingListenerManager() const = 0;
 198
 199   virtual Maybe<EventCallbackDebuggerNotificationType>
 200   GetDebuggerNotificationType() const {
 201     return Nothing();
 202   }
 203
 204   // Called from AsyncEventDispatcher to notify it is running.
 205   virtual void AsyncEventRunning(AsyncEventDispatcher* aEvent) {}
 206
 207   // Used by APZ to determine whether this event target has non-chrome event
 208   // listeners for untrusted key events.
 209   bool HasNonSystemGroupListenersForUntrustedKeyEvents() const;
 210
 211   // Used by APZ to determine whether this event target has non-chrome and
 212   // non-passive event listeners for untrusted key events.
 213   bool HasNonPassiveNonSystemGroupListenersForUntrustedKeyEvents() const;
 214
 215   virtual bool IsApzAware() const;
 216
 217   /**
 218    * Called before the capture phase of the event flow.
 219    * This is used to create the event target chain and implementations
 220    * should set the necessary members of EventChainPreVisitor.
 221    * At least aVisitor.mCanHandle must be set,
 222    * usually also aVisitor.mParentTarget if mCanHandle is true.
 223    * mCanHandle says that this object can handle the aVisitor.mEvent event and
 224    * the mParentTarget is the possible parent object for the event target chain.
 225    * @see EventDispatcher.h for more documentation about aVisitor.
 226    *
 227    * @param aVisitor the visitor object which is used to create the
 228    *                 event target chain for event dispatching.
 229    *
 230    * @note Only EventDispatcher should call this method.
 231    */
 232   virtual void GetEventTargetParent(EventChainPreVisitor& aVisitor) = 0;
 233
 234   /**
 235    * Called before the capture phase of the event flow and after event target
 236    * chain creation. This is used to handle things that must be executed before
 237    * dispatching the event to DOM.
 238    */
 239   virtual nsresult PreHandleEvent(EventChainVisitor& aVisitor) { return NS_OK; }
 240
 241   /**
 242    * If EventChainPreVisitor.mWantsWillHandleEvent is set true,
 243    * called just before possible event handlers on this object will be called.
 244    */
 245   virtual void WillHandleEvent(EventChainPostVisitor& aVisitor) {}
 246
 247   /**
 248    * Called after the bubble phase of the system event group.
 249    * The default handling of the event should happen here.
 250    * @param aVisitor the visitor object which is used during post handling.
 251    *
 252    * @see EventDispatcher.h for documentation about aVisitor.
 253    * @note Only EventDispatcher should call this method.
 254    */
 255   MOZ_CAN_RUN_SCRIPT
 256   virtual nsresult PostHandleEvent(EventChainPostVisitor& aVisitor) = 0;
 257
 258  protected:
 259   EventHandlerNonNull* GetEventHandler(nsAtom* aType);
 260   void SetEventHandler(nsAtom* aType, EventHandlerNonNull* aHandler);
 261
 262   /**
 263    * Hook for AddEventListener that allows it to compute the right
 264    * wantsUntrusted boolean when one is not provided.  If this returns failure,
 265    * the listener will not be added.
 266    *
 267    * This hook will NOT be called unless aWantsUntrusted is null in
 268    * AddEventListener.  If you need to take action when event listeners are
 269    * added, use EventListenerAdded.  Especially because not all event listener
 270    * additions go through AddEventListener!
 271    */
 272   virtual bool ComputeDefaultWantsUntrusted(ErrorResult& aRv) = 0;
 273
 274   /**
 275    * A method to compute the right wantsUntrusted value for AddEventListener.
 276    * This will call the above hook as needed.
 277    *
 278    * If aOptions is non-null, and it contains a value for mWantUntrusted, that
 279    * value takes precedence over aWantsUntrusted.
 280    */
 281   bool ComputeWantsUntrusted(const Nullable<bool>& aWantsUntrusted,
 282                              const AddEventListenerOptionsOrBoolean* aOptions,
 283                              ErrorResult& aRv);
 284
 285   /**
 286    * addSystemEventListener() adds an event listener of aType to the system
 287    * group.  Typically, core code should use the system group for listening to
 288    * content (i.e., non-chrome) element's events.  If core code uses
 289    * EventTarget::AddEventListener for a content node, it means
 290    * that the listener cannot listen to the event when web content calls
 291    * stopPropagation() of the event.
 292    *
 293    * @param aType            An event name you're going to handle.
 294    * @param aListener        An event listener.
 295    * @param aUseCapture      true if you want to listen the event in capturing
 296    *                         phase.  Otherwise, false.
 297    * @param aWantsUntrusted  true if you want to handle untrusted events.
 298    *                         false if not.
 299    *                         Null if you want the default behavior.
 300    */
 301   nsresult AddSystemEventListener(const nsAString& aType,
 302                                   nsIDOMEventListener* aListener,
 303                                   bool aUseCapture,
 304                                   const Nullable<bool>& aWantsUntrusted);
 305 };
 306
 307 NS_DEFINE_STATIC_IID_ACCESSOR(EventTarget, NS_EVENTTARGET_IID)
 308
 309 }  // namespace dom
 310 }  // namespace mozilla
 311
 312 #endif  // mozilla_dom_EventTarget_h_