content/events/public/nsPIDOMEventTarget.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License
   6  * Version 1.1 (the "License"); you may not use this file except in
   7  * compliance with the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is Mozilla.org.
  18  * Portions created by the Initial Developer are Copyright (C) 2006
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *     Olli Pettay <Olli.Pettay@helsinki.fi> (Original Author)
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsPIDOMEventTarget_h_
  39 #define nsPIDOMEventTarget_h_
  40
  41 #include "nsISupports.h"
  42 #include "nsEvent.h"
  43
  44 class nsIDOMEvent;
  45 class nsPresContext;
  46 class nsEventChainPreVisitor;
  47 class nsEventChainPostVisitor;
  48 class nsIEventListenerManager;
  49 class nsIDOMEventListener;
  50 class nsIDOMEventGroup;
  51 class nsIScriptContext;
  52
  53 // 25982813-af2e-4ab6-b512-e6c6ada6d0ec
  54 #define NS_PIDOMEVENTTARGET_IID \
  55   { 0x25982813, 0xaf2e, 0x4ab6, \
  56     { 0xb5, 0x12, 0xe6, 0xc6, 0xad, 0xa6, 0xd0, 0xec } }
  57
  58 class nsPIDOMEventTarget : public nsISupports
  59 {
  60 public:
  61   NS_DECLARE_STATIC_IID_ACCESSOR(NS_PIDOMEVENTTARGET_IID)
  62
  63   /**
  64    * Returns the nsPIDOMEventTarget object which should be used as the target
  65    * of DOMEvents.
  66    * Usually |this| is returned, but for example global object returns
  67    * the outer object.
  68    */
  69    virtual nsPIDOMEventTarget* GetTargetForDOMEvent() { return this; }
  70
  71   /**
  72    * Returns the nsPIDOMEventTarget object which should be used as the target
  73    * of the event and when constructing event target chain.
  74    * Usually |this| is returned, but for example global object returns
  75    * the inner object.
  76    */
  77    virtual nsPIDOMEventTarget* GetTargetForEventTargetChain() { return this; }
  78
  79   /**
  80    * Called before the capture phase of the event flow.
  81    * This is used to create the event target chain and implementations
  82    * should set the necessary members of nsEventChainPreVisitor.
  83    * At least aVisitor.mCanHandle must be set,
  84    * usually also aVisitor.mParentTarget if mCanHandle is PR_TRUE.
  85    * First one tells that this object can handle the aVisitor.mEvent event and
  86    * the latter one is the possible parent object for the event target chain.
  87    * @see nsEventDispatcher.h for more documentation about aVisitor.
  88    *
  89    * @param aVisitor the visitor object which is used to create the
  90    *                 event target chain for event dispatching.
  91    *
  92    * @note Only nsEventDispatcher should call this method.
  93    */
  94   virtual nsresult PreHandleEvent(nsEventChainPreVisitor& aVisitor) = 0;
  95
  96   /**
  97    * If nsEventChainPreVisitor.mWantsWillHandleEvent is set PR_TRUE,
  98    * called just before possible event handlers on this object will be called.
  99    */
 100   virtual nsresult WillHandleEvent(nsEventChainPostVisitor& aVisitor)
 101   {
 102     return NS_OK;
 103   }
 104
 105   /**
 106    * Called after the bubble phase of the system event group.
 107    * The default handling of the event should happen here.
 108    * @param aVisitor the visitor object which is used during post handling.
 109    *
 110    * @see nsEventDispatcher.h for documentation about aVisitor.
 111    * @note Only nsEventDispatcher should call this method.
 112    */
 113   virtual nsresult PostHandleEvent(nsEventChainPostVisitor& aVisitor) = 0;
 114
 115   /**
 116    * Dispatch an event.
 117    * @param aEvent the event that is being dispatched.
 118    * @param aDOMEvent the event that is being dispatched, use if you want to
 119    *                  dispatch nsIDOMEvent, not only nsEvent.
 120    * @param aPresContext the current presentation context, can be nsnull.
 121    * @param aEventStatus the status returned from the function, can be nsnull.
 122    *
 123    * @note If both aEvent and aDOMEvent are used, aEvent must be the internal
 124    *       event of the aDOMEvent.
 125    *
 126    * If aDOMEvent is not nsnull (in which case aEvent can be nsnull) it is used
 127    * for dispatching, otherwise aEvent is used.
 128    *
 129    * @deprecated This method is here just until all the callers outside Gecko
 130    *             have been converted to use nsIDOMEventTarget::dispatchEvent.
 131    */
 132   virtual nsresult DispatchDOMEvent(nsEvent* aEvent,
 133                                     nsIDOMEvent* aDOMEvent,
 134                                     nsPresContext* aPresContext,
 135                                     nsEventStatus* aEventStatus) = 0;
 136
 137   /**
 138    * Get the event listener manager, the guy you talk to to register for events
 139    * on this node.
 140    * @param aCreateIfNotFound If PR_FALSE, returns a listener manager only if
 141    *                          one already exists. [IN]
 142    * @param aResult           The event listener manager [OUT]
 143    */
 144   virtual nsresult GetListenerManager(PRBool aCreateIfNotFound,
 145                                       nsIEventListenerManager** aResult) = 0;
 146
 147   /**
 148    * Add an event listener for nsIID.
 149    */
 150   virtual nsresult AddEventListenerByIID(nsIDOMEventListener *aListener,
 151                                          const nsIID& aIID) = 0;
 152   /**
 153    * Remove event listener for nsIID.
 154    */
 155   virtual nsresult RemoveEventListenerByIID(nsIDOMEventListener *aListener,
 156                                             const nsIID& aIID) = 0;
 157
 158   /**
 159    * Get the system event group.
 160    */
 161   virtual nsresult GetSystemEventGroup(nsIDOMEventGroup** aGroup) = 0;
 162
 163   /**
 164    * Get the script context in which the event handlers should be run.
 165    * May return null.
 166    */
 167   virtual nsresult GetContextForEventHandlers(nsIScriptContext** aContext) = 0;
 168 };
 169
 170 NS_DEFINE_STATIC_IID_ACCESSOR(nsPIDOMEventTarget, NS_PIDOMEVENTTARGET_IID)
 171
 172 #endif // !defined(nsPIDOMEventTarget_h_)