DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Line Code
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 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317
/* -*- 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 EventChainVisitor;
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(9a78ac3c-9507-4d00-b2d6-10b508d2ec31)]
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 GetEventTargetParent(in EventChainPreVisitorRef aVisitor);

  /**
   * Called before the capture phase of the event flow and after event target
   * chain creation. This is used to handle those stuffs must be executed before
   * dispatch event to DOM
   */
%{C++
  virtual nsresult PreHandleEvent(mozilla::EventChainVisitor& aVisitor)
  {
    return NS_OK;
  }
%}

  /**
   * 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);
};

%{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; }

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

%}