content/base/public/nsIDocumentObserver.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 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  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or 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 #ifndef nsIDocumentObserver_h___
  38 #define nsIDocumentObserver_h___
  39
  40 #include "nsISupports.h"
  41 #include "nsIMutationObserver.h"
  42
  43 class nsIAtom;
  44 class nsIContent;
  45 class nsIPresShell;
  46 class nsIStyleSheet;
  47 class nsIStyleRule;
  48 class nsString;
  49 class nsIDocument;
  50
  51 #define NS_IDOCUMENT_OBSERVER_IID \
  52 { 0x4e14e321, 0xa4bb, 0x49f8, \
  53   { 0xa5, 0x7a, 0x23, 0x63, 0x66, 0x8d, 0x14, 0xd0 } }
  54
  55 typedef PRUint32 nsUpdateType;
  56
  57 #define UPDATE_CONTENT_MODEL 0x00000001
  58 #define UPDATE_STYLE         0x00000002
  59 #define UPDATE_CONTENT_STATE 0x00000004
  60 #define UPDATE_ALL (UPDATE_CONTENT_MODEL | UPDATE_STYLE | UPDATE_CONTENT_STATE)
  61
  62 // Document observer interface
  63 class nsIDocumentObserver : public nsIMutationObserver
  64 {
  65 public:
  66   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IDOCUMENT_OBSERVER_IID)
  67
  68   /**
  69    * Notify that a content model update is beginning. This call can be
  70    * nested.
  71    */
  72   virtual void BeginUpdate(nsIDocument *aDocument,
  73                            nsUpdateType aUpdateType) = 0;
  74
  75   /**
  76    * Notify that a content model update is finished. This call can be
  77    * nested.
  78    */
  79   virtual void EndUpdate(nsIDocument *aDocument, nsUpdateType aUpdateType) = 0;
  80
  81   /**
  82    * Notify the observer that a document load is beginning.
  83    */
  84   virtual void BeginLoad(nsIDocument *aDocument) = 0;
  85
  86   /**
  87    * Notify the observer that a document load has finished. Note that
  88    * the associated reflow of the document will be done <b>before</b>
  89    * EndLoad is invoked, not after.
  90    */
  91   virtual void EndLoad(nsIDocument *aDocument) = 0;
  92
  93   /**
  94    * Notification that the state of a content node has changed.
  95    * (ie: gained or lost focus, became active or hovered over)
  96    * This method is called automatically by content objects
  97    * when their state is changed (therefore there is normally
  98    * no need to invoke this method directly).  The notification
  99    * is passed to any IDocumentObservers. The notification is
 100    * passed on to all of the document observers. <p>
 101    *
 102    * This notification is not sent when a piece of content is
 103    * added/removed from the document or the content itself changed
 104    * (the other notifications are used for that).
 105    *
 106    * The optional second content node is to allow optimization
 107    * of the case where state moves from one node to another
 108    * (as is likely for :focus and :hover)
 109    *
 110    * Either content node may be nsnull, but not both
 111    *
 112    * @param aDocument The document being observed
 113    * @param aContent1 the piece of content that changed
 114    * @param aContent2 optional second piece of content that changed
 115    */
 116   virtual void ContentStatesChanged(nsIDocument* aDocument,
 117                                     nsIContent* aContent1,
 118                                     nsIContent* aContent2,
 119                                     PRInt32 aStateMask) = 0;
 120
 121   /**
 122    * A StyleSheet has just been added to the document.  This method is
 123    * called automatically when a StyleSheet gets added to the
 124    * document, even if the stylesheet is not applicable. The
 125    * notification is passed on to all of the document observers.
 126    *
 127    * @param aDocument The document being observed
 128    * @param aStyleSheet the StyleSheet that has been added
 129    * @param aDocumentSheet True if sheet is in document's style sheet list,
 130    *                       false if sheet is not (i.e., UA or user sheet)
 131    */
 132   virtual void StyleSheetAdded(nsIDocument *aDocument,
 133                                nsIStyleSheet* aStyleSheet,
 134                                PRBool aDocumentSheet) = 0;
 135
 136   /**
 137    * A StyleSheet has just been removed from the document.  This
 138    * method is called automatically when a StyleSheet gets removed
 139    * from the document, even if the stylesheet is not applicable. The
 140    * notification is passed on to all of the document observers.
 141    *
 142    * @param aDocument The document being observed
 143    * @param aStyleSheet the StyleSheet that has been removed
 144    * @param aDocumentSheet True if sheet is in document's style sheet list,
 145    *                       false if sheet is not (i.e., UA or user sheet)
 146    */
 147   virtual void StyleSheetRemoved(nsIDocument *aDocument,
 148                                  nsIStyleSheet* aStyleSheet,
 149                                  PRBool aDocumentSheet) = 0;
 150
 151   /**
 152    * A StyleSheet has just changed its applicable state.
 153    * This method is called automatically when the applicable state
 154    * of a StyleSheet gets changed. The style sheet passes this
 155    * notification to the document. The notification is passed on
 156    * to all of the document observers.
 157    *
 158    * @param aDocument The document being observed
 159    * @param aStyleSheet the StyleSheet that has changed state
 160    * @param aApplicable PR_TRUE if the sheet is applicable, PR_FALSE if
 161    *        it is not applicable
 162    */
 163   virtual void StyleSheetApplicableStateChanged(nsIDocument *aDocument,
 164                                                 nsIStyleSheet* aStyleSheet,
 165                                                 PRBool aApplicable) = 0;
 166
 167   /**
 168    * A StyleRule has just been modified within a style sheet.
 169    * This method is called automatically when the rule gets
 170    * modified. The style sheet passes this notification to
 171    * the document. The notification is passed on to all of
 172    * the document observers.
 173    *
 174    * Since nsIStyleRule objects are immutable, there is a new object
 175    * replacing the old one.  However, the use of this method (rather
 176    * than StyleRuleAdded and StyleRuleRemoved) implies that the new rule
 177    * matches the same elements and has the same priority (weight,
 178    * origin, specificity) as the old one.  (However, if it is a CSS
 179    * style rule, there may be a change in whether it has an important
 180    * rule.)
 181    *
 182    * @param aDocument The document being observed
 183    * @param aStyleSheet the StyleSheet that contians the rule
 184    * @param aOldStyleRule The rule being removed.  This rule may not be
 185    *                      fully valid anymore -- however, it can still
 186    *                      be used for pointer comparison and
 187    *                      |QueryInterface|.
 188    * @param aNewStyleRule The rule being added.
 189    */
 190   virtual void StyleRuleChanged(nsIDocument *aDocument,
 191                                 nsIStyleSheet* aStyleSheet,
 192                                 nsIStyleRule* aOldStyleRule,
 193                                 nsIStyleRule* aNewStyleRule) = 0;
 194
 195   /**
 196    * A StyleRule has just been added to a style sheet.
 197    * This method is called automatically when the rule gets
 198    * added to the sheet. The style sheet passes this
 199    * notification to the document. The notification is passed on
 200    * to all of the document observers.
 201    *
 202    * @param aDocument The document being observed
 203    * @param aStyleSheet the StyleSheet that has been modified
 204    * @param aStyleRule the rule that was added
 205    */
 206   virtual void StyleRuleAdded(nsIDocument *aDocument,
 207                               nsIStyleSheet* aStyleSheet,
 208                               nsIStyleRule* aStyleRule) = 0;
 209
 210   /**
 211    * A StyleRule has just been removed from a style sheet.
 212    * This method is called automatically when the rule gets
 213    * removed from the sheet. The style sheet passes this
 214    * notification to the document. The notification is passed on
 215    * to all of the document observers.
 216    *
 217    * @param aDocument The document being observed
 218    * @param aStyleSheet the StyleSheet that has been modified
 219    * @param aStyleRule the rule that was removed
 220    */
 221   virtual void StyleRuleRemoved(nsIDocument *aDocument,
 222                                 nsIStyleSheet* aStyleSheet,
 223                                 nsIStyleRule* aStyleRule) = 0;
 224 };
 225
 226 NS_DEFINE_STATIC_IID_ACCESSOR(nsIDocumentObserver, NS_IDOCUMENT_OBSERVER_IID)
 227
 228 #define NS_DECL_NSIDOCUMENTOBSERVER                                          \
 229     virtual void BeginUpdate(nsIDocument* aDocument, nsUpdateType aUpdateType);\
 230     virtual void EndUpdate(nsIDocument* aDocument, nsUpdateType aUpdateType);\
 231     virtual void BeginLoad(nsIDocument* aDocument);                          \
 232     virtual void EndLoad(nsIDocument* aDocument);                            \
 233     virtual void ContentStatesChanged(nsIDocument* aDocument,                \
 234                                       nsIContent* aContent1,                 \
 235                                       nsIContent* aContent2,                 \
 236                                       PRInt32 aStateMask);                   \
 237     virtual void StyleSheetAdded(nsIDocument* aDocument,                     \
 238                                  nsIStyleSheet* aStyleSheet,                 \
 239                                  PRBool aDocumentSheet);                     \
 240     virtual void StyleSheetRemoved(nsIDocument* aDocument,                   \
 241                                    nsIStyleSheet* aStyleSheet,               \
 242                                    PRBool aDocumentSheet);                   \
 243     virtual void StyleSheetApplicableStateChanged(nsIDocument* aDocument,    \
 244                                                   nsIStyleSheet* aStyleSheet,\
 245                                                   PRBool aApplicable);       \
 246     virtual void StyleRuleChanged(nsIDocument* aDocument,                    \
 247                                   nsIStyleSheet* aStyleSheet,                \
 248                                   nsIStyleRule* aOldStyleRule,               \
 249                                   nsIStyleRule* aNewStyleRule);              \
 250     virtual void StyleRuleAdded(nsIDocument* aDocument,                      \
 251                                 nsIStyleSheet* aStyleSheet,                  \
 252                                 nsIStyleRule* aStyleRule);                   \
 253     virtual void StyleRuleRemoved(nsIDocument* aDocument,                    \
 254                                   nsIStyleSheet* aStyleSheet,                \
 255                                   nsIStyleRule* aStyleRule);                 \
 256     NS_DECL_NSIMUTATIONOBSERVER
 257
 258
 259 #define NS_IMPL_NSIDOCUMENTOBSERVER_CORE_STUB(_class)                     \
 260 void                                                                      \
 261 _class::BeginUpdate(nsIDocument* aDocument, nsUpdateType aUpdateType)     \
 262 {                                                                         \
 263 }                                                                         \
 264 void                                                                      \
 265 _class::EndUpdate(nsIDocument* aDocument, nsUpdateType aUpdateType)       \
 266 {                                                                         \
 267 }                                                                         \
 268 NS_IMPL_NSIMUTATIONOBSERVER_CORE_STUB(_class)
 269
 270 #define NS_IMPL_NSIDOCUMENTOBSERVER_LOAD_STUB(_class)                     \
 271 void                                                                      \
 272 _class::BeginLoad(nsIDocument* aDocument)                                 \
 273 {                                                                         \
 274 }                                                                         \
 275 void                                                                      \
 276 _class::EndLoad(nsIDocument* aDocument)                                   \
 277 {                                                                         \
 278 }
 279
 280 #define NS_IMPL_NSIDOCUMENTOBSERVER_STATE_STUB(_class)                    \
 281 void                                                                      \
 282 _class::ContentStatesChanged(nsIDocument* aDocument,                      \
 283                              nsIContent* aContent1,                       \
 284                              nsIContent* aContent2,                       \
 285                              PRInt32 aStateMask)                          \
 286 {                                                                         \
 287 }
 288
 289 #define NS_IMPL_NSIDOCUMENTOBSERVER_CONTENT(_class)                       \
 290 NS_IMPL_NSIMUTATIONOBSERVER_CONTENT(_class)
 291
 292 #define NS_IMPL_NSIDOCUMENTOBSERVER_STYLE_STUB(_class)                    \
 293 void                                                                      \
 294 _class::StyleSheetAdded(nsIDocument* aDocument,                           \
 295                         nsIStyleSheet* aStyleSheet,                       \
 296                         PRBool aDocumentSheet)                            \
 297 {                                                                         \
 298 }                                                                         \
 299 void                                                                      \
 300 _class::StyleSheetRemoved(nsIDocument* aDocument,                         \
 301                           nsIStyleSheet* aStyleSheet,                     \
 302                           PRBool aDocumentSheet)                          \
 303 {                                                                         \
 304 }                                                                         \
 305 void                                                                      \
 306 _class::StyleSheetApplicableStateChanged(nsIDocument* aDocument,          \
 307                                          nsIStyleSheet* aStyleSheet,      \
 308                                          PRBool aApplicable)              \
 309 {                                                                         \
 310 }                                                                         \
 311 void                                                                      \
 312 _class::StyleRuleChanged(nsIDocument* aDocument,                          \
 313                          nsIStyleSheet* aStyleSheet,                      \
 314                          nsIStyleRule* aOldStyleRule,                     \
 315                          nsIStyleRule* aNewStyleRule)                     \
 316 {                                                                         \
 317 }                                                                         \
 318 void                                                                      \
 319 _class::StyleRuleAdded(nsIDocument* aDocument,                            \
 320                        nsIStyleSheet* aStyleSheet,                        \
 321                        nsIStyleRule* aStyleRule)                          \
 322 {                                                                         \
 323 }                                                                         \
 324 void                                                                      \
 325 _class::StyleRuleRemoved(nsIDocument* aDocument,                          \
 326                          nsIStyleSheet* aStyleSheet,                      \
 327                          nsIStyleRule* aStyleRule)                        \
 328 {                                                                         \
 329 }
 330
 331 #endif /* nsIDocumentObserver_h___ */