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/Nullable.h"
  11 #include "nsISupports.h"
  12 #include "nsWrapperCache.h"
  13 #include "nsAtom.h"
  14
  15 class nsIDOMEventListener;
  16 class nsIGlobalObject;
  17 class nsINode;
  18 class nsPIDOMWindowInner;
  19 class nsPIDOMWindowOuter;
  20 class nsPIWindowRoot;
  21
  22 namespace mozilla {
  23
  24 class AsyncEventDispatcher;
  25 class ErrorResult;
  26 class EventChainPostVisitor;
  27 class EventChainPreVisitor;
  28 class EventChainVisitor;
  29 class EventListenerManager;
  30
  31 namespace dom {
  32
  33 class AddEventListenerOptionsOrBoolean;
  34 class Event;
  35 class EventListener;
  36 class EventListenerOptionsOrBoolean;
  37 class EventHandlerNonNull;
  38 class GlobalObject;
  39 class WindowProxyHolder;
  40 enum class CallerType : uint32_t;
  41 enum class EventCallbackDebuggerNotificationType : uint8_t;
  42
  43 // IID for the dom::EventTarget interface
  44 #define NS_EVENTTARGET_IID                           \
  45   {                                                  \
  46     0xde651c36, 0x0053, 0x4c67, {                    \
  47       0xb1, 0x3d, 0x67, 0xb9, 0x40, 0xfc, 0x82, 0xe4 \
  48     }                                                \
  49   }
  50
  51 class EventTarget : public nsISupports, public nsWrapperCache {
  52  public:
  53   NS_DECLARE_STATIC_IID_ACCESSOR(NS_EVENTTARGET_IID)
  54
  55   // WebIDL API
  56   static already_AddRefed<EventTarget> Constructor(const GlobalObject& aGlobal,
  57                                                    ErrorResult& aRv);
  58   void AddEventListener(const nsAString& aType, EventListener* aCallback,
  59                         const AddEventListenerOptionsOrBoolean& aOptions,
  60                         const Nullable<bool>& aWantsUntrusted,
  61                         ErrorResult& aRv);
  62   void RemoveEventListener(const nsAString& aType, EventListener* aCallback,
  63                            const EventListenerOptionsOrBoolean& aOptions,
  64                            ErrorResult& aRv);
  65
  66  protected:
  67   /**
  68    * This method allows addition of event listeners represented by
  69    * nsIDOMEventListener, with almost the same semantics as the
  70    * standard AddEventListener.  The one difference is that it just
  71    * has a "use capture" boolean, not an EventListenerOptions.
  72    */
  73   nsresult AddEventListener(const nsAString& aType,
  74                             nsIDOMEventListener* aListener, bool aUseCapture,
  75                             const Nullable<bool>& aWantsUntrusted);
  76
  77  public:
  78   /**
  79    * Helper methods to make the nsIDOMEventListener version of
  80    * AddEventListener simpler to call for consumers.
  81    */
  82   nsresult AddEventListener(const nsAString& aType,
  83                             nsIDOMEventListener* aListener, bool aUseCapture) {
  84     return AddEventListener(aType, aListener, aUseCapture, Nullable<bool>());
  85   }
  86   nsresult AddEventListener(const nsAString& aType,
  87                             nsIDOMEventListener* aListener, bool aUseCapture,
  88                             bool aWantsUntrusted) {
  89     return AddEventListener(aType, aListener, aUseCapture,
  90                             Nullable<bool>(aWantsUntrusted));
  91   }
  92
  93   /**
  94    * This method allows the removal of event listeners represented by
  95    * nsIDOMEventListener from the event target, with the same semantics as the
  96    * standard RemoveEventListener.
  97    */
  98   void RemoveEventListener(const nsAString& aType,
  99                            nsIDOMEventListener* aListener, bool aUseCapture);
 100   /**
 101    * RemoveSystemEventListener() should be used if you have used
 102    * AddSystemEventListener().
 103    */
 104   void RemoveSystemEventListener(const nsAString& aType,
 105                                  nsIDOMEventListener* aListener,
 106                                  bool aUseCapture);
 107
 108   /**
 109    * Add a system event listener with the default wantsUntrusted value.
 110    */
 111   nsresult AddSystemEventListener(const nsAString& aType,
 112                                   nsIDOMEventListener* aListener,
 113                                   bool aUseCapture) {
 114     return AddSystemEventListener(aType, aListener, aUseCapture,
 115                                   Nullable<bool>());
 116   }
 117
 118   /**
 119    * Add a system event listener with the given wantsUntrusted value.
 120    */
 121   nsresult AddSystemEventListener(const nsAString& aType,
 122                                   nsIDOMEventListener* aListener,
 123                                   bool aUseCapture, bool aWantsUntrusted) {
 124     return AddSystemEventListener(aType, aListener, aUseCapture,
 125                                   Nullable<bool>(aWantsUntrusted));
 126   }
 127
 128   virtual bool IsNode() const { return false; }
 129   inline nsINode* GetAsNode();
 130   inline const nsINode* GetAsNode() const;
 131   inline nsINode* AsNode();
 132   inline const nsINode* AsNode() const;
 133
 134   virtual bool IsInnerWindow() const { return false; }
 135   virtual bool IsOuterWindow() const { return false; }
 136   virtual bool IsRootWindow() const { return false; }
 137   nsPIDOMWindowInner* GetAsWindowInner();
 138   const nsPIDOMWindowInner* GetAsWindowInner() const;
 139   nsPIDOMWindowOuter* GetAsWindowOuter();
 140   const nsPIDOMWindowOuter* GetAsWindowOuter() const;
 141   inline nsPIWindowRoot* GetAsWindowRoot();
 142   inline const nsPIWindowRoot* GetAsWindowRoot() const;
 143   nsPIDOMWindowInner* AsWindowInner();
 144   const nsPIDOMWindowInner* AsWindowInner() const;
 145   nsPIDOMWindowOuter* AsWindowOuter();
 146   const nsPIDOMWindowOuter* AsWindowOuter() const;
 147   inline nsPIWindowRoot* AsWindowRoot();
 148   inline const nsPIWindowRoot* AsWindowRoot() const;
 149
 150   /**
 151    * Returns the EventTarget object which should be used as the target
 152    * of DOMEvents.
 153    * Usually |this| is returned, but for example Window (inner windw) returns
 154    * the WindowProxy (outer window).
 155    */
 156   virtual EventTarget* GetTargetForDOMEvent() { return this; };
 157
 158   /**
 159    * Returns the EventTarget object which should be used as the target
 160    * of the event and when constructing event target chain.
 161    * Usually |this| is returned, but for example WindowProxy (outer window)
 162    * returns the Window (inner window).
 163    */
 164   virtual EventTarget* GetTargetForEventTargetChain() { return this; }
 165
 166   /**
 167    * The most general DispatchEvent method.  This is the one the bindings call.
 168    */
 169   // TODO: Convert this to MOZ_CAN_RUN_SCRIPT (bug 1415230)
 170   MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual bool DispatchEvent(Event& aEvent,
 171                                                          CallerType aCallerType,
 172                                                          ErrorResult& aRv) = 0;
 173
 174   /**
 175    * A version of DispatchEvent you can use if you really don't care whether it
 176    * succeeds or not and whether default is prevented or not.
 177    */
 178   // TODO: Convert this to MOZ_CAN_RUN_SCRIPT (bug 1415230)
 179   MOZ_CAN_RUN_SCRIPT_BOUNDARY void DispatchEvent(Event& aEvent);
 180
 181   /**
 182    * A version of DispatchEvent you can use if you really don't care whether
 183    * default is prevented or not.
 184    */
 185   // TODO: Convert this to MOZ_CAN_RUN_SCRIPT (bug 1415230)
 186   MOZ_CAN_RUN_SCRIPT_BOUNDARY void DispatchEvent(Event& aEvent,
 187                                                  ErrorResult& aRv);
 188
 189   nsIGlobalObject* GetParentObject() const { return GetOwnerGlobal(); }
 190
 191   // Note, this takes the type in onfoo form!
 192   EventHandlerNonNull* GetEventHandler(const nsAString& aType) {
 193     RefPtr<nsAtom> type = NS_Atomize(aType);
 194     return GetEventHandler(type);
 195   }
 196
 197   // Note, this takes the type in onfoo form!
 198   void SetEventHandler(const nsAString& aType, EventHandlerNonNull* aHandler,
 199                        ErrorResult& rv);
 200
 201   // For an event 'foo' aType will be 'onfoo'.
 202   virtual void EventListenerAdded(nsAtom* aType) {}
 203
 204   // For an event 'foo' aType will be 'onfoo'.
 205   virtual void EventListenerRemoved(nsAtom* aType) {}
 206
 207   // Returns an outer window that corresponds to the inner window this event
 208   // target is associated with.  Will return null if the inner window is not the
 209   // current inner or if there is no window around at all.
 210   Nullable<WindowProxyHolder> GetOwnerGlobalForBindings();
 211   virtual nsPIDOMWindowOuter* GetOwnerGlobalForBindingsInternal() = 0;
 212
 213   // The global object this event target is associated with, if any.
 214   // This may be an inner window or some other global object.  This
 215   // will never be an outer window.
 216   virtual nsIGlobalObject* GetOwnerGlobal() const = 0;
 217
 218   /**
 219    * Get the event listener manager, creating it if it does not already exist.
 220    */
 221   virtual EventListenerManager* GetOrCreateListenerManager() = 0;
 222
 223   /**
 224    * Get the event listener manager, returning null if it does not already
 225    * exist.
 226    */
 227   virtual EventListenerManager* GetExistingListenerManager() const = 0;
 228
 229   virtual Maybe<EventCallbackDebuggerNotificationType>
 230   GetDebuggerNotificationType() const {
 231     return Nothing();
 232   }
 233
 234   // Called from AsyncEventDispatcher to notify it is running.
 235   virtual void AsyncEventRunning(AsyncEventDispatcher* aEvent) {}
 236
 237   // Used by APZ to determine whether this event target has non-chrome event
 238   // listeners for untrusted key events.
 239   bool HasNonSystemGroupListenersForUntrustedKeyEvents() const;
 240
 241   // Used by APZ to determine whether this event target has non-chrome and
 242   // non-passive event listeners for untrusted key events.
 243   bool HasNonPassiveNonSystemGroupListenersForUntrustedKeyEvents() const;
 244
 245   virtual bool IsApzAware() const;
 246
 247   /**
 248    * Called before the capture phase of the event flow.
 249    * This is used to create the event target chain and implementations
 250    * should set the necessary members of EventChainPreVisitor.
 251    * At least aVisitor.mCanHandle must be set,
 252    * usually also aVisitor.mParentTarget if mCanHandle is true.
 253    * mCanHandle says that this object can handle the aVisitor.mEvent event and
 254    * the mParentTarget is the possible parent object for the event target chain.
 255    * @see EventDispatcher.h for more documentation about aVisitor.
 256    *
 257    * @param aVisitor the visitor object which is used to create the
 258    *                 event target chain for event dispatching.
 259    *
 260    * @note Only EventDispatcher should call this method.
 261    */
 262   virtual void GetEventTargetParent(EventChainPreVisitor& aVisitor) = 0;
 263
 264   /**
 265    * Called before the capture phase of the event flow and after event target
 266    * chain creation. This is used to handle things that must be executed before
 267    * dispatching the event to DOM.
 268    */
 269   virtual nsresult PreHandleEvent(EventChainVisitor& aVisitor) { return NS_OK; }
 270
 271   /**
 272    * If EventChainPreVisitor.mWantsWillHandleEvent is set true,
 273    * called just before possible event handlers on this object will be called.
 274    */
 275   virtual void WillHandleEvent(EventChainPostVisitor& aVisitor) {}
 276
 277   /**
 278    * Called after the bubble phase of the system event group.
 279    * The default handling of the event should happen here.
 280    * @param aVisitor the visitor object which is used during post handling.
 281    *
 282    * @see EventDispatcher.h for documentation about aVisitor.
 283    * @note Only EventDispatcher should call this method.
 284    */
 285   MOZ_CAN_RUN_SCRIPT
 286   virtual nsresult PostHandleEvent(EventChainPostVisitor& aVisitor) = 0;
 287
 288  protected:
 289   EventHandlerNonNull* GetEventHandler(nsAtom* aType);
 290   void SetEventHandler(nsAtom* aType, EventHandlerNonNull* aHandler);
 291
 292   /**
 293    * Hook for AddEventListener that allows it to compute the right
 294    * wantsUntrusted boolean when one is not provided.  If this returns failure,
 295    * the listener will not be added.
 296    *
 297    * This hook will NOT be called unless aWantsUntrusted is null in
 298    * AddEventListener.  If you need to take action when event listeners are
 299    * added, use EventListenerAdded.  Especially because not all event listener
 300    * additions go through AddEventListener!
 301    */
 302   virtual bool ComputeDefaultWantsUntrusted(ErrorResult& aRv) = 0;
 303
 304   /**
 305    * A method to compute the right wantsUntrusted value for AddEventListener.
 306    * This will call the above hook as needed.
 307    *
 308    * If aOptions is non-null, and it contains a value for mWantUntrusted, that
 309    * value takes precedence over aWantsUntrusted.
 310    */
 311   bool ComputeWantsUntrusted(const Nullable<bool>& aWantsUntrusted,
 312                              const AddEventListenerOptionsOrBoolean* aOptions,
 313                              ErrorResult& aRv);
 314
 315   /**
 316    * addSystemEventListener() adds an event listener of aType to the system
 317    * group.  Typically, core code should use the system group for listening to
 318    * content (i.e., non-chrome) element's events.  If core code uses
 319    * EventTarget::AddEventListener for a content node, it means
 320    * that the listener cannot listen to the event when web content calls
 321    * stopPropagation() of the event.
 322    *
 323    * @param aType            An event name you're going to handle.
 324    * @param aListener        An event listener.
 325    * @param aUseCapture      true if you want to listen the event in capturing
 326    *                         phase.  Otherwise, false.
 327    * @param aWantsUntrusted  true if you want to handle untrusted events.
 328    *                         false if not.
 329    *                         Null if you want the default behavior.
 330    */
 331   nsresult AddSystemEventListener(const nsAString& aType,
 332                                   nsIDOMEventListener* aListener,
 333                                   bool aUseCapture,
 334                                   const Nullable<bool>& aWantsUntrusted);
 335 };
 336
 337 NS_DEFINE_STATIC_IID_ACCESSOR(EventTarget, NS_EVENTTARGET_IID)
 338
 339 #define NS_IMPL_FROMEVENTTARGET_GENERIC(_class, _check, _const)             \
 340   template <typename T>                                                     \
 341   static auto FromEventTarget(_const T& aEventTarget)                       \
 342       ->decltype(static_cast<_const _class*>(&aEventTarget)) {              \
 343     return aEventTarget._check ? static_cast<_const _class*>(&aEventTarget) \
 344                                : nullptr;                                   \
 345   }                                                                         \
 346   template <typename T>                                                     \
 347   static _const _class* FromEventTarget(_const T* aEventTarget) {           \
 348     MOZ_DIAGNOSTIC_ASSERT(aEventTarget);                                    \
 349     return FromEventTarget(*aEventTarget);                                  \
 350   }                                                                         \
 351   template <typename T>                                                     \
 352   static _const _class* FromEventTargetOrNull(_const T* aEventTarget) {     \
 353     return aEventTarget ? FromEventTarget(*aEventTarget) : nullptr;         \
 354   }
 355
 356 #define NS_IMPL_FROMEVENTTARGET_HELPER(_class, _check)                         \
 357   NS_IMPL_FROMEVENTTARGET_GENERIC(_class, _check, )                            \
 358   NS_IMPL_FROMEVENTTARGET_GENERIC(_class, _check, const)                       \
 359   template <typename T>                                                        \
 360   static _class* FromEventTarget(T&& aEventTarget) {                           \
 361     MOZ_DIAGNOSTIC_ASSERT(!!aEventTarget);                                     \
 362     /* We need the double-cast in case aEventTarget is a smartptr.  Those */   \
 363     /* can cast to superclasses of the type they're templated on, */           \
 364     /* but not directly to subclasses.  */                                     \
 365     return aEventTarget->_check                                                \
 366                ? static_cast<_class*>(static_cast<EventTarget*>(aEventTarget)) \
 367                : nullptr;                                                      \
 368   }                                                                            \
 369   template <typename T>                                                        \
 370   static _class* FromEventTargetOrNull(T&& aEventTarget) {                     \
 371     return aEventTarget ? FromEventTarget(aEventTarget) : nullptr;             \
 372   }
 373
 374 // Unfortunately, nsPIDOMWindowInner and nsPIDOMWindowOuter do not inherit
 375 // EventTarget directly, but they are public interfaces which should have
 376 // these helper methods.  Therefore, we cannot cast from EventTarget to
 377 // the interfaces in their header file.  That's the reason why we cannot use
 378 // the zero cost casts nor decltype for the template methods which take a
 379 // reference.
 380 #define NS_IMPL_FROMEVENTTARGET_GENERIC_WITH_GETTER(_class, _getter, _const) \
 381   static _const _class* FromEventTarget(                                     \
 382       _const mozilla::dom::EventTarget& aEventTarget) {                      \
 383     return aEventTarget._getter;                                             \
 384   }                                                                          \
 385   template <typename T>                                                      \
 386   static _const _class* FromEventTarget(_const T* aEventTarget) {            \
 387     return aEventTarget->_getter;                                            \
 388   }                                                                          \
 389   template <typename T>                                                      \
 390   static _const _class* FromEventTargetOrNull(_const T* aEventTarget) {      \
 391     return aEventTarget ? aEventTarget->_getter : nullptr;                   \
 392   }
 393
 394 #define NS_IMPL_FROMEVENTTARGET_HELPER_WITH_GETTER_INNER(_class, _getter) \
 395   template <typename T>                                                   \
 396   static _class* FromEventTarget(T&& aEventTarget) {                      \
 397     return aEventTarget->_getter;                                         \
 398   }                                                                       \
 399   template <typename T>                                                   \
 400   static _class* FromEventTargetOrNull(T&& aEventTarget) {                \
 401     return aEventTarget ? aEventTarget->_getter : nullptr;                \
 402   }
 403
 404 #define NS_IMPL_FROMEVENTTARGET_HELPER_WITH_GETTER(_class, _getter)   \
 405   NS_IMPL_FROMEVENTTARGET_GENERIC_WITH_GETTER(_class, _getter, )      \
 406   NS_IMPL_FROMEVENTTARGET_GENERIC_WITH_GETTER(_class, _getter, const) \
 407   NS_IMPL_FROMEVENTTARGET_HELPER_WITH_GETTER_INNER(_class, _getter)
 408
 409 }  // namespace dom
 410 }  // namespace mozilla
 411
 412 #endif  // mozilla_dom_EventTarget_h_