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/. */
7 #ifndef mozilla_dom_IDTracker_h_
8 #define mozilla_dom_IDTracker_h_
10 #include "mozilla/Attributes.h"
11 #include "nsIObserver.h"
12 #include "nsThreadUtils.h"
18 class nsIReferrerInfo
;
20 namespace mozilla::dom
{
23 class DocumentOrShadowRoot
;
27 * Class to track what element is referenced by a given ID.
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).
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
45 using Element
= mozilla::dom::Element
;
52 * Find which element, if any, is referenced.
54 Element
* get() { return mElement
; }
57 * Set up the reference. This can be called multiple times to
58 * change which reference is being tracked, but these changes
59 * do not trigger ElementChanged.
60 * @param aFrom the source element for context
61 * @param aURI the URI containing a hash-reference to the element
62 * @param aReferrerInfo the referrerInfo for loading external resource
63 * @param aWatch if false, then we do not set up the notifications to track
64 * changes, so ElementChanged won't fire and get() will always return the same
65 * value, the current element for the ID.
66 * @param aReferenceImage whether the ID references image elements which are
67 * subject to the document's mozSetImageElement overriding mechanism.
69 void ResetToURIFragmentID(nsIContent
* aFrom
, nsIURI
* aURI
,
70 nsIReferrerInfo
* aReferrerInfo
, bool aWatch
= true,
71 bool aReferenceImage
= false);
74 * A variation on ResetToURIFragmentID() to set up a reference that consists
75 * of the ID of an element in the same document as aFrom.
76 * @param aFrom the source element for context
77 * @param aID the ID of the element
78 * @param aWatch if false, then we do not set up the notifications to track
79 * changes, so ElementChanged won't fire and get() will always return the same
80 * value, the current element for the ID.
82 void ResetWithID(Element
& aFrom
, nsAtom
* aID
, bool aWatch
= true);
85 * Clears the reference. ElementChanged is not triggered. get() will return
90 void Traverse(nsCycleCollectionTraversalCallback
* aCB
);
94 * Override this to be notified of element changes. Don't forget
95 * to call this superclass method to change mElement. This is called
96 * at script-runnable time.
98 virtual void ElementChanged(Element
* aFrom
, Element
* aTo
);
101 * Override this to convert from a single-shot notification to
102 * a persistent notification.
104 virtual bool IsPersistent() { return false; }
107 * Set ourselves up with our new document. Note that aDocument might be
108 * null. Either aWatch must be false or aRef must be empty.
110 void HaveNewDocumentOrShadowRoot(DocumentOrShadowRoot
*, bool aWatch
,
111 const nsString
& aRef
);
114 static bool Observe(Element
* aOldElement
, Element
* aNewElement
, void* aData
);
116 class Notification
: public nsISupports
{
118 virtual void SetTo(Element
* aTo
) = 0;
119 virtual void Clear() { mTarget
= nullptr; }
120 virtual ~Notification() = default;
123 explicit Notification(IDTracker
* aTarget
) : mTarget(aTarget
) {
124 MOZ_ASSERT(aTarget
, "Must have a target");
129 class ChangeNotification
: public mozilla::Runnable
, public Notification
{
131 ChangeNotification(IDTracker
* aTarget
, Element
* aFrom
, Element
* aTo
);
133 // We need to actually declare all of nsISupports, because
134 // Notification inherits from it but doesn't declare it.
135 NS_DECL_ISUPPORTS_INHERITED
136 NS_IMETHOD
Run() override
{
138 mTarget
->mPendingNotification
= nullptr;
139 mTarget
->ElementChanged(mFrom
, mTo
);
143 void SetTo(Element
* aTo
) override
;
144 void Clear() override
;
147 virtual ~ChangeNotification();
149 RefPtr
<Element
> mFrom
;
152 friend class ChangeNotification
;
154 class DocumentLoadNotification
: public Notification
, public nsIObserver
{
156 DocumentLoadNotification(IDTracker
* aTarget
, const nsString
& aRef
)
157 : Notification(aTarget
) {
158 if (!mTarget
->IsPersistent()) {
166 virtual ~DocumentLoadNotification() = default;
168 virtual void SetTo(Element
* aTo
) override
{}
172 friend class DocumentLoadNotification
;
174 DocumentOrShadowRoot
* GetWatchDocOrShadowRoot() const;
176 RefPtr
<nsAtom
> mWatchID
;
178 mWatchDocumentOrShadowRoot
; // Always a `DocumentOrShadowRoot`.
179 RefPtr
<Element
> mElement
;
180 RefPtr
<Notification
> mPendingNotification
;
181 bool mReferencingImage
= false;
184 inline void ImplCycleCollectionUnlink(IDTracker
& aField
) { aField
.Unlink(); }
186 inline void ImplCycleCollectionTraverse(
187 nsCycleCollectionTraversalCallback
& aCallback
, IDTracker
& aField
,
188 const char* aName
, uint32_t aFlags
= 0) {
189 aField
.Traverse(&aCallback
);
192 } // namespace mozilla::dom
194 #endif /* mozilla_dom_IDTracker_h_ */