michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIDOMEventListener;
michael@0: interface nsIDOMEventTarget;
michael@0: 
michael@0: /**
michael@0:  * An instance of this interface describes how an event listener
michael@0:  * was added to an event target.
michael@0:  */
michael@0: [scriptable, uuid(c4776eb7-05bc-49ce-a0ca-6213a346d53a)]
michael@0: interface nsIEventListenerInfo : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * The type of the event for which the listener was added.
michael@0:    * Null if the listener is for all the events.
michael@0:    */
michael@0:   readonly attribute AString type;
michael@0:   readonly attribute boolean capturing;
michael@0:   readonly attribute boolean allowsUntrusted;
michael@0:   readonly attribute boolean inSystemEventGroup;
michael@0: 
michael@0:   /**
michael@0:    * The underlying JS object of the event listener, if this listener
michael@0:    * has one.  Null otherwise.
michael@0:    */
michael@0:   [implicit_jscontext]
michael@0:   readonly attribute jsval listenerObject;
michael@0: 
michael@0:   /**
michael@0:    * Tries to serialize event listener to a string.
michael@0:    * Returns null if serialization isn't possible
michael@0:    * (for example with C++ listeners).
michael@0:    */
michael@0:   AString toSource();
michael@0: 
michael@0:   /**
michael@0:    * If jsdIDebuggerService is active and the listener is implemented in JS,
michael@0:    * this returns the listener as a jsdIValue. Otherwise null.
michael@0:    */
michael@0:   nsISupports getDebugObject();
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(f6964bfb-dabe-4cab-9733-be0ee2bf8171)]
michael@0: interface nsIEventListenerService : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Returns an array of nsIEventListenerInfo objects.
michael@0:    * If aEventTarget doesn't have any listeners, this returns null.
michael@0:    */
michael@0:   void getListenerInfoFor(in nsIDOMEventTarget aEventTarget,
michael@0:                           [optional] out unsigned long aCount,
michael@0:                           [retval, array, size_is(aCount)] out
michael@0:                             nsIEventListenerInfo aOutArray);
michael@0: 
michael@0:   /**
michael@0:    * Returns an array of event targets.
michael@0:    * aEventTarget will be at index 0.
michael@0:    * The objects are the ones that would be used as DOMEvent.currentTarget while
michael@0:    * dispatching an event to aEventTarget
michael@0:    * @note Some events, especially 'load', may actually have a shorter
michael@0:    *       event target chain than what this methods returns.
michael@0:    */
michael@0:   void getEventTargetChainFor(in nsIDOMEventTarget aEventTarget,
michael@0:                               [optional] out unsigned long aCount,
michael@0:                               [retval, array, size_is(aCount)] out
michael@0:                                 nsIDOMEventTarget aOutArray);
michael@0: 
michael@0:   /**
michael@0:    * Returns true if a event target has any listener for the given type.
michael@0:    */
michael@0:   boolean hasListenersFor(in nsIDOMEventTarget aEventTarget,
michael@0:                           in DOMString aType);
michael@0: 
michael@0:   /**
michael@0:    * Add a system-group eventlistener to a event target.
michael@0:    */
michael@0:   void addSystemEventListener(in nsIDOMEventTarget target,
michael@0:                               in DOMString type,
michael@0:                               in nsIDOMEventListener listener,
michael@0:                               in boolean useCapture);
michael@0: 
michael@0:   /**
michael@0:    * Remove a system-group eventlistener from a event target.
michael@0:    */
michael@0:   void removeSystemEventListener(in nsIDOMEventTarget target,
michael@0:                                  in DOMString type,
michael@0:                                  in nsIDOMEventListener listener,
michael@0:                                  in boolean useCapture);
michael@0: 
michael@0:   void addListenerForAllEvents(in nsIDOMEventTarget target,
michael@0:                                in nsIDOMEventListener listener,
michael@0:                                [optional] in boolean aUseCapture,
michael@0:                                [optional] in boolean aWantsUntrusted,
michael@0:                                [optional] in boolean aSystemEventGroup);
michael@0: 
michael@0:   void removeListenerForAllEvents(in nsIDOMEventTarget target,
michael@0:                                   in nsIDOMEventListener listener,
michael@0:                                   [optional] in boolean aUseCapture,
michael@0:                                   [optional] in boolean aSystemEventGroup);
michael@0: };
michael@0: