summaryrefslogtreecommitdiff
path: root/dom/events/EventDispatcher.h
blob: 3c754033dbe66e0ee6baf4cb118f3f990b91d8a3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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/. */

#ifdef MOZILLA_INTERNAL_API
#ifndef mozilla_EventDispatcher_h_
#define mozilla_EventDispatcher_h_

#include "mozilla/EventForwards.h"
#include "nsCOMPtr.h"
#include "nsTArray.h"

// Microsoft's API Name hackery sucks
#undef CreateEvent

class nsIContent;
class nsIDOMEvent;
class nsPresContext;

template<class E> class nsCOMArray;

namespace mozilla {
namespace dom {
class Event;
class EventTarget;
} // namespace dom

/**
 * About event dispatching:
 * When either EventDispatcher::Dispatch or
 * EventDispatcher::DispatchDOMEvent is called an event target chain is
 * created. EventDispatcher creates the chain by calling PreHandleEvent 
 * on each event target and the creation continues until either the mCanHandle
 * member of the EventChainPreVisitor object is false or the mParentTarget
 * does not point to a new target. The event target chain is created in the
 * heap.
 *
 * If the event needs retargeting, mEventTargetAtParent must be set in
 * PreHandleEvent.
 *
 * The capture, target and bubble phases of the event dispatch are handled
 * by iterating through the event target chain. Iteration happens twice,
 * first for the default event group and then for the system event group.
 * While dispatching the event for the system event group PostHandleEvent
 * is called right after calling event listener for the current event target.
 */

class EventChainVisitor
{
public:
  EventChainVisitor(nsPresContext* aPresContext,
                    WidgetEvent* aEvent,
                    nsIDOMEvent* aDOMEvent,
                    nsEventStatus aEventStatus = nsEventStatus_eIgnore)
    : mPresContext(aPresContext)
    , mEvent(aEvent)
    , mDOMEvent(aDOMEvent)
    , mEventStatus(aEventStatus)
    , mItemFlags(0)
  {
  }

  /**
   * The prescontext, possibly nullptr.
   */
  nsPresContext* const  mPresContext;

  /**
   * The WidgetEvent which is being dispatched. Never nullptr.
   */
  WidgetEvent* const mEvent;

  /**
   * The DOM Event assiciated with the mEvent. Possibly nullptr if a DOM Event
   * is not (yet) created.
   */
  nsIDOMEvent*          mDOMEvent;

  /**
   * The status of the event.
   * @see nsEventStatus.h
   */
  nsEventStatus         mEventStatus;

  /**
   * Bits for items in the event target chain.
   * Set in PreHandleEvent() and used in PostHandleEvent().
   *
   * @note These bits are different for each item in the event target chain.
   *       It is up to the Pre/PostHandleEvent implementation to decide how to
   *       use these bits.
   *
   * @note Using uint16_t because that is used also in EventTargetChainItem.
   */
  uint16_t              mItemFlags;

  /**
   * Data for items in the event target chain.
   * Set in PreHandleEvent() and used in PostHandleEvent().
   *
   * @note This data is different for each item in the event target chain.
   *       It is up to the Pre/PostHandleEvent implementation to decide how to
   *       use this.
   */
  nsCOMPtr<nsISupports> mItemData;
};

class EventChainPreVisitor : public EventChainVisitor
{
public:
  EventChainPreVisitor(nsPresContext* aPresContext,
                       WidgetEvent* aEvent,
                       nsIDOMEvent* aDOMEvent,
                       nsEventStatus aEventStatus,
                       bool aIsInAnon)
    : EventChainVisitor(aPresContext, aEvent, aDOMEvent, aEventStatus)
    , mCanHandle(true)
    , mAutomaticChromeDispatch(true)
    , mForceContentDispatch(false)
    , mRelatedTargetIsInAnon(false)
    , mOriginalTargetIsInAnon(aIsInAnon)
    , mWantsWillHandleEvent(false)
    , mMayHaveListenerManager(true)
    , mParentTarget(nullptr)
    , mEventTargetAtParent(nullptr)
  {
  }

  void Reset()
  {
    mItemFlags = 0;
    mItemData = nullptr;
    mCanHandle = true;
    mAutomaticChromeDispatch = true;
    mForceContentDispatch = false;
    mWantsWillHandleEvent = false;
    mMayHaveListenerManager = true;
    mParentTarget = nullptr;
    mEventTargetAtParent = nullptr;
  }

  /**
   * Member that must be set in PreHandleEvent by event targets. If set to false,
   * indicates that this event target will not be handling the event and
   * construction of the event target chain is complete. The target that sets
   * mCanHandle to false is NOT included in the event target chain.
   */
  bool                  mCanHandle;

  /**
   * If mCanHandle is false and mAutomaticChromeDispatch is also false
   * event will not be dispatched to the chrome event handler.
   */
  bool                  mAutomaticChromeDispatch;

  /**
   * If mForceContentDispatch is set to true,
   * content dispatching is not disabled for this event target.
   * FIXME! This is here for backward compatibility. Bug 329119
   */
  bool                  mForceContentDispatch;

  /**
   * true if it is known that related target is or is a descendant of an
   * element which is anonymous for events.
   */
  bool                  mRelatedTargetIsInAnon;

  /**
   * true if the original target of the event is inside anonymous content.
   * This is set before calling PreHandleEvent on event targets.
   */
  bool                  mOriginalTargetIsInAnon;

  /**
   * Whether or not nsIDOMEventTarget::WillHandleEvent will be
   * called. Default is false;
   */
  bool                  mWantsWillHandleEvent;

  /**
   * If it is known that the current target doesn't have a listener manager
   * when PreHandleEvent is called, set this to false.
   */
  bool                  mMayHaveListenerManager;

  /**
   * Parent item in the event target chain.
   */
  dom::EventTarget* mParentTarget;

  /**
   * If the event needs to be retargeted, this is the event target,
   * which should be used when the event is handled at mParentTarget.
   */
  dom::EventTarget* mEventTargetAtParent;

  /**
   * An array of destination insertion points that need to be inserted
   * into the event path of nodes that are distributed by the
   * web components distribution algorithm.
   */
  nsTArray<nsIContent*> mDestInsertionPoints;
};

class EventChainPostVisitor : public mozilla::EventChainVisitor
{
public:
  explicit EventChainPostVisitor(EventChainVisitor& aOther)
    : EventChainVisitor(aOther.mPresContext, aOther.mEvent,
                        aOther.mDOMEvent, aOther.mEventStatus)
  {
  }
};

/**
 * If an EventDispatchingCallback object is passed to Dispatch,
 * its HandleEvent method is called after handling the default event group,
 * before handling the system event group.
 * This is used in nsPresShell.
 */
class MOZ_STACK_CLASS EventDispatchingCallback
{
public:
  virtual void HandleEvent(EventChainPostVisitor& aVisitor) = 0;
};

/**
 * The generic class for event dispatching.
 * Must not be used outside Gecko!
 */
class EventDispatcher
{
public:
  /**
   * aTarget should QI to EventTarget.
   * If the target of aEvent is set before calling this method, the target of 
   * aEvent is used as the target (unless there is event
   * retargeting) and the originalTarget of the DOM Event.
   * aTarget is always used as the starting point for constructing the event
   * target chain, no matter what the value of aEvent->mTarget is.
   * In other words, aEvent->mTarget is only a property of the event and it has
   * nothing to do with the construction of the event target chain.
   * Neither aTarget nor aEvent is allowed to be nullptr.
   *
   * If aTargets is non-null, event target chain will be created, but
   * event won't be handled. In this case aEvent->mMessage should be
   * eVoidEvent.
   * @note Use this method when dispatching a WidgetEvent.
   */
  static nsresult Dispatch(nsISupports* aTarget,
                           nsPresContext* aPresContext,
                           WidgetEvent* aEvent,
                           nsIDOMEvent* aDOMEvent = nullptr,
                           nsEventStatus* aEventStatus = nullptr,
                           EventDispatchingCallback* aCallback = nullptr,
                           nsTArray<dom::EventTarget*>* aTargets = nullptr);

  /**
   * Dispatches an event.
   * If aDOMEvent is not nullptr, it is used for dispatching
   * (aEvent can then be nullptr) and (if aDOMEvent is not |trusted| already),
   * the |trusted| flag is set based on the UniversalXPConnect capability.
   * Otherwise this works like EventDispatcher::Dispatch.
   * @note Use this method when dispatching nsIDOMEvent.
   */
  static nsresult DispatchDOMEvent(nsISupports* aTarget,
                                   WidgetEvent* aEvent,
                                   nsIDOMEvent* aDOMEvent,
                                   nsPresContext* aPresContext,
                                   nsEventStatus* aEventStatus);

  /**
   * Creates a DOM Event.  Returns null if the event type is unsupported.
   */
  static already_AddRefed<dom::Event> CreateEvent(dom::EventTarget* aOwner,
                                                  nsPresContext* aPresContext,
                                                  WidgetEvent* aEvent,
                                                  const nsAString& aEventType);

  /**
   * Called at shutting down.
   */
  static void Shutdown();
};

} // namespace mozilla

#endif // mozilla_EventDispatcher_h_
#endif