dom/interfaces/events/nsIDOMEventTarget.idl
author Boris Zbarsky <bzbarsky@mit.edu>
Thu, 05 Apr 2018 13:42:41 -0400
changeset 411929 433dba4e710415a040ca047a5f0cbcb94eeaf2d0
parent 411928 caa5bef6848122d106ad47fc7b2bf104d2d8ce3d
child 411930 15546aaa4d0999765a7f278058614d08082a4558
permissions -rw-r--r--
Bug 1449631 part 7. Remove nsIDOMEventTarget::GetTargetFor* methods. r=smaug MozReview-Commit-ID: AIzDo67mTDf

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

[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);
  }
%}

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