dom/base/nsIMutationObserver.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef nsIMutationObserver_h
   8 #define nsIMutationObserver_h
   9
  10 #include "nsISupports.h"
  11
  12 #include "mozilla/Assertions.h"
  13
  14 class nsAttrValue;
  15 class nsAtom;
  16 class nsIContent;
  17 class nsINode;
  18
  19 namespace mozilla {
  20 namespace dom {
  21 class Element;
  22 }  // namespace dom
  23 }  // namespace mozilla
  24
  25 #define NS_IMUTATION_OBSERVER_IID                    \
  26   {                                                  \
  27     0x6d674c17, 0x0fbc, 0x4633, {                    \
  28       0x8f, 0x46, 0x73, 0x4e, 0x87, 0xeb, 0xf0, 0xc7 \
  29     }                                                \
  30   }
  31
  32 /**
  33  * Information details about a characterdata change.  Basically, we
  34  * view all changes as replacements of a length of text at some offset
  35  * with some other text (of possibly some other length).
  36  */
  37 struct CharacterDataChangeInfo {
  38   /**
  39    * True if this character data change is just an append.
  40    */
  41   bool mAppend;
  42
  43   /**
  44    * The offset in the text where the change occurred.
  45    */
  46   uint32_t mChangeStart;
  47
  48   /**
  49    * The offset such that mChangeEnd - mChangeStart is equal to the length of
  50    * the text we removed. If this was a pure insert, append or a result of
  51    * `splitText()` this is equal to mChangeStart.
  52    */
  53   uint32_t mChangeEnd;
  54
  55   uint32_t LengthOfRemovedText() const {
  56     MOZ_ASSERT(mChangeStart <= mChangeEnd);
  57
  58     return mChangeEnd - mChangeStart;
  59   }
  60
  61   /**
  62    * The length of the text that was inserted in place of the removed text.  If
  63    * this was a pure text removal, this is 0.
  64    */
  65   uint32_t mReplaceLength;
  66
  67   /**
  68    * The net result is that mChangeStart characters at the beginning of the
  69    * text remained as they were.  The next mChangeEnd - mChangeStart characters
  70    * were removed, and mReplaceLength characters were inserted in their place.
  71    * The text that used to begin at mChangeEnd now begins at
  72    * mChangeStart + mReplaceLength.
  73    */
  74
  75   struct MOZ_STACK_CLASS Details {
  76     enum {
  77       eMerge,  // two text nodes are merged as a result of normalize()
  78       eSplit   // a text node is split as a result of splitText()
  79     } mType;
  80     /**
  81      * For eMerge it's the text node that will be removed, for eSplit it's the
  82      * new text node.
  83      */
  84     nsIContent* MOZ_NON_OWNING_REF mNextSibling;
  85   };
  86
  87   /**
  88    * Used for splitText() and normalize(), otherwise null.
  89    */
  90   Details* mDetails;
  91 };
  92
  93 /**
  94  * Mutation observer interface
  95  *
  96  * See nsINode::AddMutationObserver, nsINode::RemoveMutationObserver for how to
  97  * attach or remove your observers.
  98  *
  99  * WARNING: During these notifications, you are not allowed to perform
 100  * any mutations to the current or any other document, or start a
 101  * network load.  If you need to perform such operations do that
 102  * during the _last_ nsIDocumentObserver::EndUpdate notification.  The
 103  * exception for this is ParentChainChanged, where mutations should be
 104  * done from an async event, as the notification might not be
 105  * surrounded by BeginUpdate/EndUpdate calls.
 106  */
 107 class nsIMutationObserver : public nsISupports {
 108  public:
 109   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IMUTATION_OBSERVER_IID)
 110
 111   /**
 112    * Notification that the node value of a data node (text, cdata, pi, comment)
 113    * will be changed.
 114    *
 115    * This notification is not sent when a piece of content is
 116    * added/removed from the document (the other notifications are used
 117    * for that).
 118    *
 119    * @param aContent  The piece of content that changed. Is never null.
 120    * @param aInfo     The structure with information details about the change.
 121    *
 122    * @note Callers of this method might not hold a strong reference to the
 123    *       observer.  The observer is responsible for making sure it stays
 124    *       alive for the duration of the call as needed.  The observer may
 125    *       assume that this call will happen when there are script blockers on
 126    *       the stack.
 127    */
 128   virtual void CharacterDataWillChange(nsIContent* aContent,
 129                                        const CharacterDataChangeInfo&) = 0;
 130
 131   /**
 132    * Notification that the node value of a data node (text, cdata, pi, comment)
 133    * has changed.
 134    *
 135    * This notification is not sent when a piece of content is
 136    * added/removed from the document (the other notifications are used
 137    * for that).
 138    *
 139    * @param aContent  The piece of content that changed. Is never null.
 140    * @param aInfo     The structure with information details about the change.
 141    *
 142    * @note Callers of this method might not hold a strong reference to the
 143    *       observer.  The observer is responsible for making sure it stays
 144    *       alive for the duration of the call as needed.  The observer may
 145    *       assume that this call will happen when there are script blockers on
 146    *       the stack.
 147    */
 148   virtual void CharacterDataChanged(nsIContent* aContent,
 149                                     const CharacterDataChangeInfo&) = 0;
 150
 151   /**
 152    * Notification that an attribute of an element will change.  This
 153    * can happen before the BeginUpdate for the change and may not
 154    * always be followed by an AttributeChanged (in particular, if the
 155    * attribute doesn't actually change there will be no corresponding
 156    * AttributeChanged).
 157    *
 158    * @param aContent     The element whose attribute will change
 159    * @param aNameSpaceID The namespace id of the changing attribute
 160    * @param aAttribute   The name of the changing attribute
 161    * @param aModType     Whether or not the attribute will be added, changed, or
 162    *                     removed. The constants are defined in
 163    *                     MutationEvent.webidl.
 164    * @param aNewValue    The new value, IF it has been preparsed by
 165    *                     BeforeSetAttr, otherwise null.
 166    *
 167    * @note Callers of this method might not hold a strong reference to the
 168    *       observer.  The observer is responsible for making sure it stays
 169    *       alive for the duration of the call as needed.  The observer may
 170    *       assume that this call will happen when there are script blockers on
 171    *       the stack.
 172    */
 173   virtual void AttributeWillChange(mozilla::dom::Element* aElement,
 174                                    int32_t aNameSpaceID, nsAtom* aAttribute,
 175                                    int32_t aModType) = 0;
 176
 177   /**
 178    * Notification that an attribute of an element has changed.
 179    *
 180    * @param aElement     The element whose attribute changed
 181    * @param aNameSpaceID The namespace id of the changed attribute
 182    * @param aAttribute   The name of the changed attribute
 183    * @param aModType     Whether or not the attribute was added, changed, or
 184    *                     removed. The constants are defined in
 185    *                     MutationEvent.webidl.
 186    * @param aOldValue    The old value, if either the old value or the new
 187    *                     value are StoresOwnData() (or absent); null otherwise.
 188    *
 189    * @note Callers of this method might not hold a strong reference to the
 190    *       observer.  The observer is responsible for making sure it stays
 191    *       alive for the duration of the call as needed.  The observer may
 192    *       assume that this call will happen when there are script blockers on
 193    *       the stack.
 194    */
 195   virtual void AttributeChanged(mozilla::dom::Element* aElement,
 196                                 int32_t aNameSpaceID, nsAtom* aAttribute,
 197                                 int32_t aModType,
 198                                 const nsAttrValue* aOldValue) = 0;
 199
 200   /**
 201    * Notification that the root of a native anonymous has been added
 202    * or removed.
 203    *
 204    * @param aContent     Anonymous node that's been added or removed
 205    * @param aIsRemove    True if it's a removal, false if an addition
 206    */
 207   virtual void NativeAnonymousChildListChange(nsIContent* aContent,
 208                                               bool aIsRemove) {}
 209
 210   /**
 211    * Notification that an attribute of an element has been
 212    * set to the value it already had.
 213    *
 214    * @param aElement     The element whose attribute changed
 215    * @param aNameSpaceID The namespace id of the changed attribute
 216    * @param aAttribute   The name of the changed attribute
 217    */
 218   virtual void AttributeSetToCurrentValue(mozilla::dom::Element* aElement,
 219                                           int32_t aNameSpaceID,
 220                                           nsAtom* aAttribute) {}
 221
 222   /**
 223    * Notification that one or more content nodes have been appended to the
 224    * child list of another node in the tree.
 225    *
 226    * @param aFirstNewContent the first node appended.
 227    *
 228    * @note Callers of this method might not hold a strong reference to the
 229    *       observer.  The observer is responsible for making sure it stays
 230    *       alive for the duration of the call as needed.  The observer may
 231    *       assume that this call will happen when there are script blockers on
 232    *       the stack.
 233    */
 234   virtual void ContentAppended(nsIContent* aFirstNewContent) = 0;
 235
 236   /**
 237    * Notification that a content node has been inserted as child to another
 238    * node in the tree.
 239    *
 240    * @param aChild The newly inserted child.
 241    *
 242    * @note Callers of this method might not hold a strong reference to the
 243    *       observer.  The observer is responsible for making sure it stays
 244    *       alive for the duration of the call as needed.  The observer may
 245    *       assume that this call will happen when there are script blockers on
 246    *       the stack.
 247    */
 248   virtual void ContentInserted(nsIContent* aChild) = 0;
 249
 250   /**
 251    * Notification that a content node has been removed from the child list of
 252    * another node in the tree.
 253    *
 254    * @param aChild     The child that was removed.
 255    * @param aPreviousSibling The previous sibling to the child that was removed.
 256    *                         Can be null if there was no previous sibling.
 257    *
 258    * @note Callers of this method might not hold a strong reference to the
 259    *       observer.  The observer is responsible for making sure it stays
 260    *       alive for the duration of the call as needed.  The observer may
 261    *       assume that this call will happen when there are script blockers on
 262    *       the stack.
 263    */
 264   virtual void ContentRemoved(nsIContent* aChild,
 265                               nsIContent* aPreviousSibling) = 0;
 266
 267   /**
 268    * The node is in the process of being destroyed. Calling QI on the node is
 269    * not supported, however it is possible to get children and flags through
 270    * nsINode as well as calling IsContent and casting to nsIContent to get
 271    * attributes.
 272    *
 273    * NOTE: This notification is only called on observers registered directly
 274    * on the node. This is because when the node is destroyed it can not have
 275    * any ancestors. If you want to know when a descendant node is being
 276    * removed from the observed node, use the ContentRemoved notification.
 277    *
 278    * @param aNode The node being destroyed.
 279    *
 280    * @note Callers of this method might not hold a strong reference to
 281    *       the observer.  The observer is responsible for making sure it
 282    *       stays alive for the duration of the call as needed.
 283    */
 284   virtual void NodeWillBeDestroyed(const nsINode* aNode) = 0;
 285
 286   /**
 287    * Notification that the node's parent chain has changed. This
 288    * happens when either the node or one of its ancestors is inserted
 289    * or removed as a child of another node.
 290    *
 291    * Note that when a node is inserted this notification is sent to
 292    * all descendants of that node, since all such nodes have their
 293    * parent chain changed.
 294    *
 295    * @param aContent  The piece of content that had its parent changed.
 296    *
 297    * @note Callers of this method might not hold a strong reference to
 298    *       the observer.  The observer is responsible for making sure it
 299    *       stays alive for the duration of the call as needed.
 300    */
 301
 302   virtual void ParentChainChanged(nsIContent* aContent) = 0;
 303 };
 304
 305 NS_DEFINE_STATIC_IID_ACCESSOR(nsIMutationObserver, NS_IMUTATION_OBSERVER_IID)
 306
 307 #define NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATAWILLCHANGE \
 308   virtual void CharacterDataWillChange(                     \
 309       nsIContent* aContent, const CharacterDataChangeInfo& aInfo) override;
 310
 311 #define NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATACHANGED \
 312   virtual void CharacterDataChanged(                     \
 313       nsIContent* aContent, const CharacterDataChangeInfo& aInfo) override;
 314
 315 #define NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTEWILLCHANGE                      \
 316   virtual void AttributeWillChange(mozilla::dom::Element* aElement,          \
 317                                    int32_t aNameSpaceID, nsAtom* aAttribute, \
 318                                    int32_t aModType) override;
 319
 320 #define NS_DECL_NSIMUTATIONOBSERVER_NATIVEANONYMOUSCHILDLISTCHANGE  \
 321   virtual void NativeAnonymousChildListChange(nsIContent* aContent, \
 322                                               bool aIsRemove) override;
 323
 324 #define NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED                      \
 325   virtual void AttributeChanged(mozilla::dom::Element* aElement,          \
 326                                 int32_t aNameSpaceID, nsAtom* aAttribute, \
 327                                 int32_t aModType,                         \
 328                                 const nsAttrValue* aOldValue) override;
 329
 330 #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED \
 331   virtual void ContentAppended(nsIContent* aFirstNewContent) override;
 332
 333 #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED \
 334   virtual void ContentInserted(nsIContent* aChild) override;
 335
 336 #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED \
 337   virtual void ContentRemoved(nsIContent* aChild,  \
 338                               nsIContent* aPreviousSibling) override;
 339
 340 #define NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED \
 341   virtual void NodeWillBeDestroyed(const nsINode* aNode) override;
 342
 343 #define NS_DECL_NSIMUTATIONOBSERVER_PARENTCHAINCHANGED \
 344   virtual void ParentChainChanged(nsIContent* aContent) override;
 345
 346 #define NS_DECL_NSIMUTATIONOBSERVER                          \
 347   NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATAWILLCHANGE        \
 348   NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATACHANGED           \
 349   NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTEWILLCHANGE            \
 350   NS_DECL_NSIMUTATIONOBSERVER_NATIVEANONYMOUSCHILDLISTCHANGE \
 351   NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED               \
 352   NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED                \
 353   NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED                \
 354   NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED                 \
 355   NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED            \
 356   NS_DECL_NSIMUTATIONOBSERVER_PARENTCHAINCHANGED
 357
 358 #define NS_IMPL_NSIMUTATIONOBSERVER_CORE_STUB(_class) \
 359   void _class::NodeWillBeDestroyed(const nsINode* aNode) {}
 360
 361 #define NS_IMPL_NSIMUTATIONOBSERVER_CONTENT(_class)                          \
 362   void _class::CharacterDataWillChange(                                      \
 363       nsIContent* aContent, const CharacterDataChangeInfo& aInfo) {}         \
 364   void _class::CharacterDataChanged(nsIContent* aContent,                    \
 365                                     const CharacterDataChangeInfo& aInfo) {} \
 366   void _class::AttributeWillChange(mozilla::dom::Element* aElement,          \
 367                                    int32_t aNameSpaceID, nsAtom* aAttribute, \
 368                                    int32_t aModType) {}                      \
 369   void _class::NativeAnonymousChildListChange(nsIContent* aContent,          \
 370                                               bool aIsRemove) {}             \
 371   void _class::AttributeChanged(                                             \
 372       mozilla::dom::Element* aElement, int32_t aNameSpaceID,                 \
 373       nsAtom* aAttribute, int32_t aModType, const nsAttrValue* aOldValue) {} \
 374   void _class::ContentAppended(nsIContent* aFirstNewContent) {}              \
 375   void _class::ContentInserted(nsIContent* aChild) {}                        \
 376   void _class::ContentRemoved(nsIContent* aChild,                            \
 377                               nsIContent* aPreviousSibling) {}               \
 378   void _class::ParentChainChanged(nsIContent* aContent) {}
 379
 380 #endif /* nsIMutationObserver_h */