LCOV - code coverage report
Current view: directory - objdir/dist/include - nsIMutationObserver.h (source / functions) Found Hit Coverage
Test: app.info Lines: 1 1 100.0 %
Date: 2012-06-02 Functions: 1 1 100.0 %

       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 Version
       6                 :  * 1.1 (the "License"); you may not use this file except in compliance with
       7                 :  * 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
      18                 :  * Netscape Communications Corporation.
      19                 :  * Portions created by the Initial Developer are Copyright (C) 1998
      20                 :  * the Initial Developer. All Rights Reserved.
      21                 :  *
      22                 :  * Contributor(s):
      23                 :  *   Ms2ger <ms2ger@gmail.com>
      24                 :  *
      25                 :  * Alternatively, the contents of this file may be used under the terms of
      26                 :  * either of the GNU General Public License Version 2 or later (the "GPL"),
      27                 :  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
      28                 :  * in which case the provisions of the GPL or the LGPL are applicable instead
      29                 :  * of those above. If you wish to allow use of your version of this file only
      30                 :  * under the terms of either the GPL or the LGPL, and not to allow others to
      31                 :  * use your version of this file under the terms of the MPL, indicate your
      32                 :  * decision by deleting the provisions above and replace them with the notice
      33                 :  * and other provisions required by the GPL or the LGPL. If you do not delete
      34                 :  * the provisions above, a recipient may use your version of this file under
      35                 :  * the terms of any one of the MPL, the GPL or the LGPL.
      36                 :  *
      37                 :  * ***** END LICENSE BLOCK ***** */
      38                 : 
      39                 : #ifndef nsIMutationObserver_h
      40                 : #define nsIMutationObserver_h
      41                 : 
      42                 : #include "nsISupports.h"
      43                 : 
      44                 : class nsIAtom;
      45                 : class nsIContent;
      46                 : class nsIDocument;
      47                 : class nsINode;
      48                 : 
      49                 : namespace mozilla {
      50                 : namespace dom {
      51                 : class Element;
      52                 : } // namespace dom
      53                 : } // namespace mozilla
      54                 : 
      55                 : #define NS_IMUTATION_OBSERVER_IID \
      56                 : { 0x85eea794, 0xed8e, 0x4e1b, \
      57                 :   { 0xa1, 0x28, 0xd0, 0x93, 0x00, 0xae, 0x51, 0xaa } }
      58                 : 
      59                 : /**
      60                 :  * Information details about a characterdata change.  Basically, we
      61                 :  * view all changes as replacements of a length of text at some offset
      62                 :  * with some other text (of possibly some other length).
      63                 :  */
      64                 : struct CharacterDataChangeInfo
      65                 : {
      66                 :   /**
      67                 :    * True if this character data change is just an append.
      68                 :    */
      69                 :   bool mAppend;
      70                 : 
      71                 :   /**
      72                 :    * The offset in the text where the change occurred.
      73                 :    */
      74                 :   PRUint32 mChangeStart;
      75                 : 
      76                 :   /**
      77                 :    * The offset such that mChangeEnd - mChangeStart is equal to the length of
      78                 :    * the text we removed. If this was a pure insert or append, this is equal to
      79                 :    * mChangeStart.
      80                 :    */
      81                 :   PRUint32 mChangeEnd;
      82                 : 
      83                 :   /**
      84                 :    * The length of the text that was inserted in place of the removed text.  If
      85                 :    * this was a pure text removal, this is 0.
      86                 :    */
      87                 :   PRUint32 mReplaceLength;
      88                 : 
      89                 :   /**
      90                 :    * The net result is that mChangeStart characters at the beginning of the
      91                 :    * text remained as they were.  The next mChangeEnd - mChangeStart characters
      92                 :    * were removed, and mReplaceLength characters were inserted in their place.
      93                 :    * The text that used to begin at mChangeEnd now begins at
      94                 :    * mChangeStart + mReplaceLength.
      95                 :    */
      96                 : 
      97                 :   struct Details {
      98                 :     enum {
      99                 :       eMerge,  // two text nodes are merged as a result of normalize()
     100                 :       eSplit   // a text node is split as a result of splitText()
     101                 :     } mType;
     102                 :     /**
     103                 :      * For eMerge it's the text node that will be removed, for eSplit it's the
     104                 :      * new text node.
     105                 :      */
     106                 :     nsIContent* mNextSibling;
     107                 :   };
     108                 : 
     109                 :   /**
     110                 :    * Used for splitText() and normalize(), otherwise null.
     111                 :    */
     112                 :   Details* mDetails;
     113                 : };
     114                 : 
     115                 : /**
     116                 :  * Mutation observer interface
     117                 :  *
     118                 :  * See nsINode::AddMutationObserver, nsINode::RemoveMutationObserver for how to
     119                 :  * attach or remove your observers.
     120                 :  *
     121                 :  * WARNING: During these notifications, you are not allowed to perform
     122                 :  * any mutations to the current or any other document, or start a
     123                 :  * network load.  If you need to perform such operations do that
     124                 :  * during the _last_ nsIDocumentObserver::EndUpdate notification.  The
     125                 :  * expection for this is ParentChainChanged, where mutations should be
     126                 :  * done from an async event, as the notification might not be
     127                 :  * surrounded by BeginUpdate/EndUpdate calls.
     128                 :  */
     129                 : class nsIMutationObserver : public nsISupports
     130            9432 : {
     131                 : public:
     132                 :   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IMUTATION_OBSERVER_IID)
     133                 : 
     134                 :   /**
     135                 :    * Notification that the node value of a data node (text, cdata, pi, comment)
     136                 :    * will be changed.
     137                 :    *
     138                 :    * This notification is not sent when a piece of content is
     139                 :    * added/removed from the document (the other notifications are used
     140                 :    * for that).
     141                 :    *
     142                 :    * @param aDocument The owner-document of aContent. Can be null.
     143                 :    * @param aContent  The piece of content that changed. Is never null.
     144                 :    * @param aInfo     The structure with information details about the change.
     145                 :    *
     146                 :    * @note Callers of this method might not hold a strong reference to the
     147                 :    *       observer.  The observer is responsible for making sure it stays
     148                 :    *       alive for the duration of the call as needed.  The observer may
     149                 :    *       assume that this call will happen when there are script blockers on
     150                 :    *       the stack.
     151                 :    */
     152                 :   virtual void CharacterDataWillChange(nsIDocument *aDocument,
     153                 :                                        nsIContent* aContent,
     154                 :                                        CharacterDataChangeInfo* aInfo) = 0;
     155                 : 
     156                 :   /**
     157                 :    * Notification that the node value of a data node (text, cdata, pi, comment)
     158                 :    * has changed.
     159                 :    *
     160                 :    * This notification is not sent when a piece of content is
     161                 :    * added/removed from the document (the other notifications are used
     162                 :    * for that).
     163                 :    *
     164                 :    * @param aDocument The owner-document of aContent. Can be null.
     165                 :    * @param aContent  The piece of content that changed. Is never null.
     166                 :    * @param aInfo     The structure with information details about the change.
     167                 :    *
     168                 :    * @note Callers of this method might not hold a strong reference to the
     169                 :    *       observer.  The observer is responsible for making sure it stays
     170                 :    *       alive for the duration of the call as needed.  The observer may
     171                 :    *       assume that this call will happen when there are script blockers on
     172                 :    *       the stack.
     173                 :    */
     174                 :   virtual void CharacterDataChanged(nsIDocument *aDocument,
     175                 :                                     nsIContent* aContent,
     176                 :                                     CharacterDataChangeInfo* aInfo) = 0;
     177                 : 
     178                 :   /**
     179                 :    * Notification that an attribute of an element will change.  This
     180                 :    * can happen before the BeginUpdate for the change and may not
     181                 :    * always be followed by an AttributeChanged (in particular, if the
     182                 :    * attribute doesn't actually change there will be no corresponding
     183                 :    * AttributeChanged).
     184                 :    *
     185                 :    * @param aDocument    The owner-document of aContent. Can be null.
     186                 :    * @param aContent     The element whose attribute will change
     187                 :    * @param aNameSpaceID The namespace id of the changing attribute
     188                 :    * @param aAttribute   The name of the changing attribute
     189                 :    * @param aModType     Whether or not the attribute will be added, changed, or
     190                 :    *                     removed. The constants are defined in
     191                 :    *                     nsIDOMMutationEvent.h.
     192                 :    *
     193                 :    * @note Callers of this method might not hold a strong reference to the
     194                 :    *       observer.  The observer is responsible for making sure it stays
     195                 :    *       alive for the duration of the call as needed.  The observer may
     196                 :    *       assume that this call will happen when there are script blockers on
     197                 :    *       the stack.
     198                 :    */
     199                 :   virtual void AttributeWillChange(nsIDocument* aDocument,
     200                 :                                    mozilla::dom::Element* aElement,
     201                 :                                    PRInt32      aNameSpaceID,
     202                 :                                    nsIAtom*     aAttribute,
     203                 :                                    PRInt32      aModType) = 0;
     204                 : 
     205                 :   /**
     206                 :    * Notification that an attribute of an element has changed.
     207                 :    *
     208                 :    * @param aDocument    The owner-document of aContent. Can be null.
     209                 :    * @param aElement     The element whose attribute changed
     210                 :    * @param aNameSpaceID The namespace id of the changed attribute
     211                 :    * @param aAttribute   The name of the changed attribute
     212                 :    * @param aModType     Whether or not the attribute was added, changed, or
     213                 :    *                     removed. The constants are defined in
     214                 :    *                     nsIDOMMutationEvent.h.
     215                 :    *
     216                 :    * @note Callers of this method might not hold a strong reference to the
     217                 :    *       observer.  The observer is responsible for making sure it stays
     218                 :    *       alive for the duration of the call as needed.  The observer may
     219                 :    *       assume that this call will happen when there are script blockers on
     220                 :    *       the stack.
     221                 :    */
     222                 :   virtual void AttributeChanged(nsIDocument* aDocument,
     223                 :                                 mozilla::dom::Element* aElement,
     224                 :                                 PRInt32      aNameSpaceID,
     225                 :                                 nsIAtom*     aAttribute,
     226                 :                                 PRInt32      aModType) = 0;
     227                 : 
     228                 :   /**
     229                 :    * Notification that one or more content nodes have been appended to the
     230                 :    * child list of another node in the tree.
     231                 :    *
     232                 :    * @param aDocument  The owner-document of aContent. Can be null.
     233                 :    * @param aContainer The container that had new children appended. Is never
     234                 :    *                   null.
     235                 :    * @param aFirstNewContent the node at aIndexInContainer in aContainer.
     236                 :    * @param aNewIndexInContainer the index in the container of the first
     237                 :    *                   new child
     238                 :    *
     239                 :    * @note Callers of this method might not hold a strong reference to the
     240                 :    *       observer.  The observer is responsible for making sure it stays
     241                 :    *       alive for the duration of the call as needed.  The observer may
     242                 :    *       assume that this call will happen when there are script blockers on
     243                 :    *       the stack.
     244                 :    */
     245                 :   virtual void ContentAppended(nsIDocument *aDocument,
     246                 :                                nsIContent* aContainer,
     247                 :                                nsIContent* aFirstNewContent,
     248                 :                                PRInt32     aNewIndexInContainer) = 0;
     249                 : 
     250                 :   /**
     251                 :    * Notification that a content node has been inserted as child to another
     252                 :    * node in the tree.
     253                 :    *
     254                 :    * @param aDocument  The owner-document of aContent, or, when aContainer
     255                 :    *                   is null, the container that had the child inserted.
     256                 :    *                   Can be null.
     257                 :    * @param aContainer The container that had new a child inserted. Can be
     258                 :    *                   null to indicate that the child was inserted into
     259                 :    *                   aDocument
     260                 :    * @param aChild     The newly inserted child.
     261                 :    * @param aIndexInContainer The index in the container of the new child.
     262                 :    *
     263                 :    * @note Callers of this method might not hold a strong reference to the
     264                 :    *       observer.  The observer is responsible for making sure it stays
     265                 :    *       alive for the duration of the call as needed.  The observer may
     266                 :    *       assume that this call will happen when there are script blockers on
     267                 :    *       the stack.
     268                 :    */
     269                 :   virtual void ContentInserted(nsIDocument *aDocument,
     270                 :                                nsIContent* aContainer,
     271                 :                                nsIContent* aChild,
     272                 :                                PRInt32 aIndexInContainer) = 0;
     273                 : 
     274                 :   /**
     275                 :    * Notification that a content node has been removed from the child list of
     276                 :    * another node in the tree.
     277                 :    *
     278                 :    * @param aDocument  The owner-document of aContent, or, when aContainer
     279                 :    *                   is null, the container that had the child removed.
     280                 :    *                   Can be null.
     281                 :    * @param aContainer The container that had new a child removed. Can be
     282                 :    *                   null to indicate that the child was removed from
     283                 :    *                   aDocument.
     284                 :    * @param aChild     The child that was removed.
     285                 :    * @param aIndexInContainer The index in the container which the child used
     286                 :    *                          to have.
     287                 :    * @param aPreviousSibling The previous sibling to the child that was removed.
     288                 :    *                         Can be null if there was no previous sibling.
     289                 :    *
     290                 :    * @note Callers of this method might not hold a strong reference to the
     291                 :    *       observer.  The observer is responsible for making sure it stays
     292                 :    *       alive for the duration of the call as needed.  The observer may
     293                 :    *       assume that this call will happen when there are script blockers on
     294                 :    *       the stack.
     295                 :    */
     296                 :   virtual void ContentRemoved(nsIDocument *aDocument,
     297                 :                               nsIContent* aContainer,
     298                 :                               nsIContent* aChild,
     299                 :                               PRInt32 aIndexInContainer,
     300                 :                               nsIContent* aPreviousSibling) = 0;
     301                 : 
     302                 :  /**
     303                 :    * The node is in the process of being destroyed. Calling QI on the node is
     304                 :    * not supported, however it is possible to get children and flags through
     305                 :    * nsINode as well as calling IsNodeOfType(eCONTENT) and casting to
     306                 :    * nsIContent to get attributes.
     307                 :    *
     308                 :    * NOTE: This notification is only called on observers registered directly
     309                 :    * on the node. This is because when the node is destroyed it can not have
     310                 :    * any ancestors. If you want to know when a descendant node is being
     311                 :    * removed from the observed node, use the ContentRemoved notification.
     312                 :    * 
     313                 :    * @param aNode The node being destroyed.
     314                 :    *
     315                 :    * @note Callers of this method might not hold a strong reference to
     316                 :    *       the observer.  The observer is responsible for making sure it
     317                 :    *       stays alive for the duration of the call as needed.
     318                 :    */
     319                 :   virtual void NodeWillBeDestroyed(const nsINode *aNode) = 0;
     320                 : 
     321                 :   /**
     322                 :    * Notification that the node's parent chain has changed. This
     323                 :    * happens when either the node or one of its ancestors is inserted
     324                 :    * or removed as a child of another node.
     325                 :    *
     326                 :    * Note that when a node is inserted this notification is sent to
     327                 :    * all descendants of that node, since all such nodes have their
     328                 :    * parent chain changed.
     329                 :    *
     330                 :    * @param aContent  The piece of content that had its parent changed.
     331                 :    *
     332                 :    * @note Callers of this method might not hold a strong reference to
     333                 :    *       the observer.  The observer is responsible for making sure it
     334                 :    *       stays alive for the duration of the call as needed.
     335                 :    */
     336                 : 
     337                 :   virtual void ParentChainChanged(nsIContent *aContent) = 0;
     338                 : };
     339                 : 
     340                 : NS_DEFINE_STATIC_IID_ACCESSOR(nsIMutationObserver, NS_IMUTATION_OBSERVER_IID)
     341                 : 
     342                 : #define NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATAWILLCHANGE                  \
     343                 :     virtual void CharacterDataWillChange(nsIDocument* aDocument,             \
     344                 :                                          nsIContent* aContent,               \
     345                 :                                          CharacterDataChangeInfo* aInfo);
     346                 : 
     347                 : #define NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATACHANGED                     \
     348                 :     virtual void CharacterDataChanged(nsIDocument* aDocument,                \
     349                 :                                       nsIContent* aContent,                  \
     350                 :                                       CharacterDataChangeInfo* aInfo);
     351                 : 
     352                 : #define NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTEWILLCHANGE                      \
     353                 :     virtual void AttributeWillChange(nsIDocument* aDocument,                 \
     354                 :                                      mozilla::dom::Element* aElement,        \
     355                 :                                      PRInt32 aNameSpaceID,                   \
     356                 :                                      nsIAtom* aAttribute,                    \
     357                 :                                      PRInt32 aModType);
     358                 : 
     359                 : #define NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED                         \
     360                 :     virtual void AttributeChanged(nsIDocument* aDocument,                    \
     361                 :                                   mozilla::dom::Element* aElement,           \
     362                 :                                   PRInt32 aNameSpaceID,                      \
     363                 :                                   nsIAtom* aAttribute,                       \
     364                 :                                   PRInt32 aModType);
     365                 : 
     366                 : #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED                          \
     367                 :     virtual void ContentAppended(nsIDocument* aDocument,                     \
     368                 :                                  nsIContent* aContainer,                     \
     369                 :                                  nsIContent* aFirstNewContent,               \
     370                 :                                  PRInt32 aNewIndexInContainer);
     371                 : 
     372                 : #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED                          \
     373                 :     virtual void ContentInserted(nsIDocument* aDocument,                     \
     374                 :                                  nsIContent* aContainer,                     \
     375                 :                                  nsIContent* aChild,                         \
     376                 :                                  PRInt32 aIndexInContainer);
     377                 : 
     378                 : #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED                           \
     379                 :     virtual void ContentRemoved(nsIDocument* aDocument,                      \
     380                 :                                 nsIContent* aContainer,                      \
     381                 :                                 nsIContent* aChild,                          \
     382                 :                                 PRInt32 aIndexInContainer,                   \
     383                 :                                 nsIContent* aPreviousSibling);
     384                 : 
     385                 : #define NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED                      \
     386                 :     virtual void NodeWillBeDestroyed(const nsINode* aNode);
     387                 : 
     388                 : #define NS_DECL_NSIMUTATIONOBSERVER_PARENTCHAINCHANGED                       \
     389                 :     virtual void ParentChainChanged(nsIContent *aContent);
     390                 : 
     391                 : #define NS_DECL_NSIMUTATIONOBSERVER                                          \
     392                 :     NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATAWILLCHANGE                      \
     393                 :     NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATACHANGED                         \
     394                 :     NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTEWILLCHANGE                          \
     395                 :     NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED                             \
     396                 :     NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED                              \
     397                 :     NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED                              \
     398                 :     NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED                               \
     399                 :     NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED                          \
     400                 :     NS_DECL_NSIMUTATIONOBSERVER_PARENTCHAINCHANGED
     401                 : 
     402                 : #define NS_IMPL_NSIMUTATIONOBSERVER_CORE_STUB(_class)                     \
     403                 : void                                                                      \
     404                 : _class::NodeWillBeDestroyed(const nsINode* aNode)                               \
     405                 : {                                                                         \
     406                 : }
     407                 : 
     408                 : #define NS_IMPL_NSIMUTATIONOBSERVER_CONTENT(_class)                       \
     409                 : void                                                                      \
     410                 : _class::CharacterDataWillChange(nsIDocument* aDocument,                   \
     411                 :                                 nsIContent* aContent,                     \
     412                 :                                 CharacterDataChangeInfo* aInfo)           \
     413                 : {                                                                         \
     414                 : }                                                                         \
     415                 : void                                                                      \
     416                 : _class::CharacterDataChanged(nsIDocument* aDocument,                      \
     417                 :                              nsIContent* aContent,                        \
     418                 :                              CharacterDataChangeInfo* aInfo)              \
     419                 : {                                                                         \
     420                 : }                                                                         \
     421                 : void                                                                      \
     422                 : _class::AttributeWillChange(nsIDocument* aDocument,                       \
     423                 :                             mozilla::dom::Element* aElement,              \
     424                 :                             PRInt32 aNameSpaceID,                         \
     425                 :                             nsIAtom* aAttribute,                          \
     426                 :                             PRInt32 aModType)                             \
     427                 : {                                                                         \
     428                 : }                                                                         \
     429                 : void                                                                      \
     430                 : _class::AttributeChanged(nsIDocument* aDocument,                          \
     431                 :                          mozilla::dom::Element* aElement,                 \
     432                 :                          PRInt32 aNameSpaceID,                            \
     433                 :                          nsIAtom* aAttribute,                             \
     434                 :                          PRInt32 aModType)                                \
     435                 : {                                                                         \
     436                 : }                                                                         \
     437                 : void                                                                      \
     438                 : _class::ContentAppended(nsIDocument* aDocument,                           \
     439                 :                         nsIContent* aContainer,                           \
     440                 :                         nsIContent* aFirstNewContent,                     \
     441                 :                         PRInt32 aNewIndexInContainer)                     \
     442                 : {                                                                         \
     443                 : }                                                                         \
     444                 : void                                                                      \
     445                 : _class::ContentInserted(nsIDocument* aDocument,                           \
     446                 :                         nsIContent* aContainer,                           \
     447                 :                         nsIContent* aChild,                               \
     448                 :                         PRInt32 aIndexInContainer)                        \
     449                 : {                                                                         \
     450                 : }                                                                         \
     451                 : void                                                                      \
     452                 : _class::ContentRemoved(nsIDocument* aDocument,                            \
     453                 :                        nsIContent* aContainer,                            \
     454                 :                        nsIContent* aChild,                                \
     455                 :                        PRInt32 aIndexInContainer,                         \
     456                 :                        nsIContent* aPreviousSibling)                      \
     457                 : {                                                                         \
     458                 : }                                                                         \
     459                 : void                                                                      \
     460                 : _class::ParentChainChanged(nsIContent *aContent)                          \
     461                 : {                                                                         \
     462                 : }
     463                 : 
     464                 : 
     465                 : #endif /* nsIMutationObserver_h */

Generated by: LCOV version 1.7