dom/base/IDTracker.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 mozilla_dom_IDTracker_h_
   8 #define mozilla_dom_IDTracker_h_
   9
  10 #include "mozilla/Attributes.h"
  11 #include "nsIObserver.h"
  12 #include "nsThreadUtils.h"
  13
  14 class nsAtom;
  15 class nsIContent;
  16 class nsINode;
  17 class nsIURI;
  18 class nsIReferrerInfo;
  19
  20 namespace mozilla::dom {
  21
  22 class Document;
  23 class DocumentOrShadowRoot;
  24 class Element;
  25
  26 /**
  27  * Class to track what element is referenced by a given ID.
  28  *
  29  * To use it, call one of the Reset methods to set it up to watch a given ID.
  30  * Call get() anytime to determine the referenced element (which may be null if
  31  * the element isn't found). When the element changes, ElementChanged
  32  * will be called, so subclass this class if you want to receive that
  33  * notification. ElementChanged runs at safe-for-script time, i.e. outside
  34  * of the content update. Call Unlink() if you want to stop watching
  35  * for changes (get() will then return null).
  36  *
  37  * By default this is a single-shot tracker --- i.e., when ElementChanged
  38  * fires, we will automatically stop tracking. get() will continue to return
  39  * the changed-to element.
  40  * Override IsPersistent to return true if you want to keep tracking after
  41  * the first change.
  42  */
  43 class IDTracker {
  44  public:
  45   using Element = mozilla::dom::Element;
  46
  47   IDTracker();
  48
  49   ~IDTracker();
  50
  51   /**
  52    * Find which element, if any, is referenced.
  53    */
  54   Element* get() { return mElement; }
  55
  56   /**
  57    * Set up a reference to another element, identified by the fragment
  58    * identifier in aURI. If aURI identifies an element in a document that is
  59    * not aFrom's document, then an ExternalResourceLoad object will be created
  60    * to load and store that document in the background as a resource document
  61    * (until we, and any other observers, no longer observe it).
  62    *
  63    * This can be called multiple times with different URIs to change which
  64    * element is being tracked, but these changes do not trigger ElementChanged.
  65    *
  66    * @param aFrom The source element that has made the reference to aURI.
  67    * @param aURI A URI containing a fragment identifier that identifies the
  68    *   target element.
  69    * @param aReferrerInfo The referrerInfo for the source element. Needed if
  70    *   the referenced element is in an external resource document.
  71    * @param aReferenceImage Whether the reference comes from a -moz-element
  72    *   property (that is, we're creating a reference an "image element", which
  73    *   is subject to the document's mozSetImageElement overriding mechanism).
  74    */
  75   void ResetToURIWithFragmentID(nsIContent* aFrom, nsIURI* aURI,
  76                                 nsIReferrerInfo* aReferrerInfo,
  77                                 bool aReferenceImage = false);
  78
  79   /**
  80    * A variation on ResetToURIWithFragmentID() to set up a reference that
  81    * consists only of a fragment identifier, referencing an element in the same
  82    * document as aFrom.
  83    *
  84    * @param aFrom The source element that is making the reference.
  85    * @param aLocalRef The fragment identifier that identifies the target
  86    *   element. Must begin with "#".
  87    */
  88   void ResetToLocalFragmentID(Element& aFrom, const nsAString& aLocalRef);
  89
  90   /**
  91    * A variation on ResetToURIWithFragmentID() to set up a reference that
  92    * consists of a pre-parsed ID, referencing an element in the same document
  93    * as aFrom.
  94    *
  95    * @param aFrom The source element that is making the reference.
  96    * @param aID The ID of the target element.
  97    */
  98   void ResetToID(Element& aFrom, nsAtom* aID);
  99
 100   /**
 101    * Clears the reference. ElementChanged is not triggered. get() will return
 102    * null.
 103    */
 104   void Unlink();
 105
 106   void Traverse(nsCycleCollectionTraversalCallback* aCB);
 107
 108  protected:
 109   /**
 110    * Override this to be notified of element changes. Don't forget
 111    * to call this superclass method to change mElement. This is called
 112    * at script-runnable time.
 113    */
 114   virtual void ElementChanged(Element* aFrom, Element* aTo);
 115
 116   /**
 117    * Override this to convert from a single-shot notification to
 118    * a persistent notification.
 119    */
 120   virtual bool IsPersistent() { return false; }
 121
 122   /**
 123    * Set ourselves up with our new document.  Note that aDocument might be
 124    * null.  Either aWatch must be false or aRef must be empty.
 125    */
 126   void HaveNewDocumentOrShadowRoot(DocumentOrShadowRoot*, bool aWatch,
 127                                    const nsString& aRef);
 128
 129  private:
 130   static bool Observe(Element* aOldElement, Element* aNewElement, void* aData);
 131
 132   class Notification : public nsISupports {
 133    public:
 134     virtual void SetTo(Element* aTo) = 0;
 135     virtual void Clear() { mTarget = nullptr; }
 136     virtual ~Notification() = default;
 137
 138    protected:
 139     explicit Notification(IDTracker* aTarget) : mTarget(aTarget) {
 140       MOZ_ASSERT(aTarget, "Must have a target");
 141     }
 142     IDTracker* mTarget;
 143   };
 144
 145   class ChangeNotification : public mozilla::Runnable, public Notification {
 146    public:
 147     ChangeNotification(IDTracker* aTarget, Element* aFrom, Element* aTo);
 148
 149     // We need to actually declare all of nsISupports, because
 150     // Notification inherits from it but doesn't declare it.
 151     NS_DECL_ISUPPORTS_INHERITED
 152     NS_IMETHOD Run() override {
 153       if (mTarget) {
 154         mTarget->mPendingNotification = nullptr;
 155         mTarget->ElementChanged(mFrom, mTo);
 156       }
 157       return NS_OK;
 158     }
 159     void SetTo(Element* aTo) override;
 160     void Clear() override;
 161
 162    protected:
 163     virtual ~ChangeNotification();
 164
 165     RefPtr<Element> mFrom;
 166     RefPtr<Element> mTo;
 167   };
 168   friend class ChangeNotification;
 169
 170   class DocumentLoadNotification : public Notification, public nsIObserver {
 171    public:
 172     DocumentLoadNotification(IDTracker* aTarget, const nsString& aRef)
 173         : Notification(aTarget) {
 174       if (!mTarget->IsPersistent()) {
 175         mRef = aRef;
 176       }
 177     }
 178
 179     NS_DECL_ISUPPORTS
 180     NS_DECL_NSIOBSERVER
 181    private:
 182     virtual ~DocumentLoadNotification() = default;
 183
 184     virtual void SetTo(Element* aTo) override {}
 185
 186     nsString mRef;
 187   };
 188   friend class DocumentLoadNotification;
 189
 190   DocumentOrShadowRoot* GetWatchDocOrShadowRoot() const;
 191
 192   RefPtr<nsAtom> mWatchID;
 193   nsCOMPtr<nsINode>
 194       mWatchDocumentOrShadowRoot;  // Always a `DocumentOrShadowRoot`.
 195   RefPtr<Element> mElement;
 196   RefPtr<Notification> mPendingNotification;
 197   bool mReferencingImage = false;
 198 };
 199
 200 inline void ImplCycleCollectionUnlink(IDTracker& aField) { aField.Unlink(); }
 201
 202 inline void ImplCycleCollectionTraverse(
 203     nsCycleCollectionTraversalCallback& aCallback, IDTracker& aField,
 204     const char* aName, uint32_t aFlags = 0) {
 205   aField.Traverse(&aCallback);
 206 }
 207
 208 }  // namespace mozilla::dom
 209
 210 #endif /* mozilla_dom_IDTracker_h_ */