dom/events/EventDispatcher.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifdef MOZILLA_INTERNAL_API
   7 #ifndef mozilla_EventDispatcher_h_
   8 #define mozilla_EventDispatcher_h_
   9
  10 #include "mozilla/EventForwards.h"
  11 #include "nsCOMPtr.h"
  12 #include "nsTArray.h"
  13
  14 // Microsoft's API Name hackery sucks
  15 #undef CreateEvent
  16
  17 class nsIContent;
  18 class nsIDOMEvent;
  19 class nsIScriptGlobalObject;
  20 class nsPresContext;
  21
  22 template<class E> class nsCOMArray;
  23
  24 namespace mozilla {
  25 namespace dom {
  26 class EventTarget;
  27 } // namespace dom
  28
  29 /**
  30  * About event dispatching:
  31  * When either EventDispatcher::Dispatch or
  32  * EventDispatcher::DispatchDOMEvent is called an event target chain is
  33  * created. EventDispatcher creates the chain by calling PreHandleEvent
  34  * on each event target and the creation continues until either the mCanHandle
  35  * member of the EventChainPreVisitor object is false or the mParentTarget
  36  * does not point to a new target. The event target chain is created in the
  37  * heap.
  38  *
  39  * If the event needs retargeting, mEventTargetAtParent must be set in
  40  * PreHandleEvent.
  41  *
  42  * The capture, target and bubble phases of the event dispatch are handled
  43  * by iterating through the event target chain. Iteration happens twice,
  44  * first for the default event group and then for the system event group.
  45  * While dispatching the event for the system event group PostHandleEvent
  46  * is called right after calling event listener for the current event target.
  47  */
  48
  49 class EventChainVisitor
  50 {
  51 public:
  52   EventChainVisitor(nsPresContext* aPresContext,
  53                     WidgetEvent* aEvent,
  54                     nsIDOMEvent* aDOMEvent,
  55                     nsEventStatus aEventStatus = nsEventStatus_eIgnore)
  56     : mPresContext(aPresContext)
  57     , mEvent(aEvent)
  58     , mDOMEvent(aDOMEvent)
  59     , mEventStatus(aEventStatus)
  60     , mItemFlags(0)
  61   {
  62   }
  63
  64   /**
  65    * The prescontext, possibly nullptr.
  66    */
  67   nsPresContext* const  mPresContext;
  68
  69   /**
  70    * The WidgetEvent which is being dispatched. Never nullptr.
  71    */
  72   WidgetEvent* const mEvent;
  73
  74   /**
  75    * The DOM Event assiciated with the mEvent. Possibly nullptr if a DOM Event
  76    * is not (yet) created.
  77    */
  78   nsIDOMEvent*          mDOMEvent;
  79
  80   /**
  81    * The status of the event.
  82    * @see nsEventStatus.h
  83    */
  84   nsEventStatus         mEventStatus;
  85
  86   /**
  87    * Bits for items in the event target chain.
  88    * Set in PreHandleEvent() and used in PostHandleEvent().
  89    *
  90    * @note These bits are different for each item in the event target chain.
  91    *       It is up to the Pre/PostHandleEvent implementation to decide how to
  92    *       use these bits.
  93    *
  94    * @note Using uint16_t because that is used also in EventTargetChainItem.
  95    */
  96   uint16_t              mItemFlags;
  97
  98   /**
  99    * Data for items in the event target chain.
 100    * Set in PreHandleEvent() and used in PostHandleEvent().
 101    *
 102    * @note This data is different for each item in the event target chain.
 103    *       It is up to the Pre/PostHandleEvent implementation to decide how to
 104    *       use this.
 105    */
 106   nsCOMPtr<nsISupports> mItemData;
 107 };
 108
 109 class EventChainPreVisitor : public EventChainVisitor
 110 {
 111 public:
 112   EventChainPreVisitor(nsPresContext* aPresContext,
 113                        WidgetEvent* aEvent,
 114                        nsIDOMEvent* aDOMEvent,
 115                        nsEventStatus aEventStatus,
 116                        bool aIsInAnon)
 117     : EventChainVisitor(aPresContext, aEvent, aDOMEvent, aEventStatus)
 118     , mCanHandle(true)
 119     , mAutomaticChromeDispatch(true)
 120     , mForceContentDispatch(false)
 121     , mRelatedTargetIsInAnon(false)
 122     , mOriginalTargetIsInAnon(aIsInAnon)
 123     , mWantsWillHandleEvent(false)
 124     , mMayHaveListenerManager(true)
 125     , mParentTarget(nullptr)
 126     , mEventTargetAtParent(nullptr)
 127   {
 128   }
 129
 130   void Reset()
 131   {
 132     mItemFlags = 0;
 133     mItemData = nullptr;
 134     mCanHandle = true;
 135     mAutomaticChromeDispatch = true;
 136     mForceContentDispatch = false;
 137     mWantsWillHandleEvent = false;
 138     mMayHaveListenerManager = true;
 139     mParentTarget = nullptr;
 140     mEventTargetAtParent = nullptr;
 141   }
 142
 143   /**
 144    * Member that must be set in PreHandleEvent by event targets. If set to false,
 145    * indicates that this event target will not be handling the event and
 146    * construction of the event target chain is complete. The target that sets
 147    * mCanHandle to false is NOT included in the event target chain.
 148    */
 149   bool                  mCanHandle;
 150
 151   /**
 152    * If mCanHandle is false and mAutomaticChromeDispatch is also false
 153    * event will not be dispatched to the chrome event handler.
 154    */
 155   bool                  mAutomaticChromeDispatch;
 156
 157   /**
 158    * If mForceContentDispatch is set to true,
 159    * content dispatching is not disabled for this event target.
 160    * FIXME! This is here for backward compatibility. Bug 329119
 161    */
 162   bool                  mForceContentDispatch;
 163
 164   /**
 165    * true if it is known that related target is or is a descendant of an
 166    * element which is anonymous for events.
 167    */
 168   bool                  mRelatedTargetIsInAnon;
 169
 170   /**
 171    * true if the original target of the event is inside anonymous content.
 172    * This is set before calling PreHandleEvent on event targets.
 173    */
 174   bool                  mOriginalTargetIsInAnon;
 175
 176   /**
 177    * Whether or not nsIDOMEventTarget::WillHandleEvent will be
 178    * called. Default is false;
 179    */
 180   bool                  mWantsWillHandleEvent;
 181
 182   /**
 183    * If it is known that the current target doesn't have a listener manager
 184    * when PreHandleEvent is called, set this to false.
 185    */
 186   bool                  mMayHaveListenerManager;
 187
 188   /**
 189    * Parent item in the event target chain.
 190    */
 191   dom::EventTarget* mParentTarget;
 192
 193   /**
 194    * If the event needs to be retargeted, this is the event target,
 195    * which should be used when the event is handled at mParentTarget.
 196    */
 197   dom::EventTarget* mEventTargetAtParent;
 198
 199   /**
 200    * An array of destination insertion points that need to be inserted
 201    * into the event path of nodes that are distributed by the
 202    * web components distribution algorithm.
 203    */
 204   nsTArray<nsIContent*> mDestInsertionPoints;
 205 };
 206
 207 class EventChainPostVisitor : public mozilla::EventChainVisitor
 208 {
 209 public:
 210   explicit EventChainPostVisitor(EventChainVisitor& aOther)
 211     : EventChainVisitor(aOther.mPresContext, aOther.mEvent,
 212                         aOther.mDOMEvent, aOther.mEventStatus)
 213   {
 214   }
 215 };
 216
 217 /**
 218  * If an EventDispatchingCallback object is passed to Dispatch,
 219  * its HandleEvent method is called after handling the default event group,
 220  * before handling the system event group.
 221  * This is used in nsPresShell.
 222  */
 223 class MOZ_STACK_CLASS EventDispatchingCallback
 224 {
 225 public:
 226   virtual void HandleEvent(EventChainPostVisitor& aVisitor) = 0;
 227 };
 228
 229 /**
 230  * The generic class for event dispatching.
 231  * Must not be used outside Gecko!
 232  */
 233 class EventDispatcher
 234 {
 235 public:
 236   /**
 237    * aTarget should QI to EventTarget.
 238    * If the target of aEvent is set before calling this method, the target of
 239    * aEvent is used as the target (unless there is event
 240    * retargeting) and the originalTarget of the DOM Event.
 241    * aTarget is always used as the starting point for constructing the event
 242    * target chain, no matter what the value of aEvent->target is.
 243    * In other words, aEvent->target is only a property of the event and it has
 244    * nothing to do with the construction of the event target chain.
 245    * Neither aTarget nor aEvent is allowed to be nullptr.
 246    *
 247    * If aTargets is non-null, event target chain will be created, but
 248    * event won't be handled. In this case aEvent->message should be
 249    * NS_EVENT_NULL.
 250    * @note Use this method when dispatching a WidgetEvent.
 251    */
 252   static nsresult Dispatch(nsISupports* aTarget,
 253                            nsPresContext* aPresContext,
 254                            WidgetEvent* aEvent,
 255                            nsIDOMEvent* aDOMEvent = nullptr,
 256                            nsEventStatus* aEventStatus = nullptr,
 257                            EventDispatchingCallback* aCallback = nullptr,
 258                            nsCOMArray<dom::EventTarget>* aTargets = nullptr);
 259
 260   /**
 261    * Dispatches an event.
 262    * If aDOMEvent is not nullptr, it is used for dispatching
 263    * (aEvent can then be nullptr) and (if aDOMEvent is not |trusted| already),
 264    * the |trusted| flag is set based on the UniversalXPConnect capability.
 265    * Otherwise this works like EventDispatcher::Dispatch.
 266    * @note Use this method when dispatching nsIDOMEvent.
 267    */
 268   static nsresult DispatchDOMEvent(nsISupports* aTarget,
 269                                    WidgetEvent* aEvent,
 270                                    nsIDOMEvent* aDOMEvent,
 271                                    nsPresContext* aPresContext,
 272                                    nsEventStatus* aEventStatus);
 273
 274   /**
 275    * Creates a DOM Event.
 276    */
 277   static nsresult CreateEvent(dom::EventTarget* aOwner,
 278                               nsPresContext* aPresContext,
 279                               WidgetEvent* aEvent,
 280                               const nsAString& aEventType,
 281                               nsIDOMEvent** aDOMEvent);
 282
 283   /**
 284    * Called at shutting down.
 285    */
 286   static void Shutdown();
 287 };
 288
 289 } // namespace mozilla
 290
 291 #endif // mozilla_EventDispatcher_h_
 292 #endif