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 a local reference of an element in the same document as aFrom.
76 * @param aFrom the source element for context
77 * @param aLocalRef the local reference 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 ResetWithLocalRef(Element
& aFrom
, const nsAString
& aLocalRef
,
86 * A variation on ResetToURIFragmentID() to set up a reference that consists
87 * of the ID of an element in the same document as aFrom.
88 * @param aFrom the source element for context
89 * @param aID the ID of the element
90 * @param aWatch if false, then we do not set up the notifications to track
91 * changes, so ElementChanged won't fire and get() will always return the same
92 * value, the current element for the ID.
94 void ResetWithID(Element
& aFrom
, nsAtom
* aID
, bool aWatch
= true);
97 * Clears the reference. ElementChanged is not triggered. get() will return
102 void Traverse(nsCycleCollectionTraversalCallback
* aCB
);
106 * Override this to be notified of element changes. Don't forget
107 * to call this superclass method to change mElement. This is called
108 * at script-runnable time.
110 virtual void ElementChanged(Element
* aFrom
, Element
* aTo
);
113 * Override this to convert from a single-shot notification to
114 * a persistent notification.
116 virtual bool IsPersistent() { return false; }
119 * Set ourselves up with our new document. Note that aDocument might be
120 * null. Either aWatch must be false or aRef must be empty.
122 void HaveNewDocumentOrShadowRoot(DocumentOrShadowRoot
*, bool aWatch
,
123 const nsString
& aRef
);
126 static bool Observe(Element
* aOldElement
, Element
* aNewElement
, void* aData
);
128 class Notification
: public nsISupports
{
130 virtual void SetTo(Element
* aTo
) = 0;
131 virtual void Clear() { mTarget
= nullptr; }
132 virtual ~Notification() = default;
135 explicit Notification(IDTracker
* aTarget
) : mTarget(aTarget
) {
136 MOZ_ASSERT(aTarget
, "Must have a target");
141 class ChangeNotification
: public mozilla::Runnable
, public Notification
{
143 ChangeNotification(IDTracker
* aTarget
, Element
* aFrom
, Element
* aTo
);
145 // We need to actually declare all of nsISupports, because
146 // Notification inherits from it but doesn't declare it.
147 NS_DECL_ISUPPORTS_INHERITED
148 NS_IMETHOD
Run() override
{
150 mTarget
->mPendingNotification
= nullptr;
151 mTarget
->ElementChanged(mFrom
, mTo
);
155 void SetTo(Element
* aTo
) override
;
156 void Clear() override
;
159 virtual ~ChangeNotification();
161 RefPtr
<Element
> mFrom
;
164 friend class ChangeNotification
;
166 class DocumentLoadNotification
: public Notification
, public nsIObserver
{
168 DocumentLoadNotification(IDTracker
* aTarget
, const nsString
& aRef
)
169 : Notification(aTarget
) {
170 if (!mTarget
->IsPersistent()) {
178 virtual ~DocumentLoadNotification() = default;
180 virtual void SetTo(Element
* aTo
) override
{}
184 friend class DocumentLoadNotification
;
186 DocumentOrShadowRoot
* GetWatchDocOrShadowRoot() const;
188 RefPtr
<nsAtom
> mWatchID
;
190 mWatchDocumentOrShadowRoot
; // Always a `DocumentOrShadowRoot`.
191 RefPtr
<Element
> mElement
;
192 RefPtr
<Notification
> mPendingNotification
;
193 bool mReferencingImage
= false;
196 inline void ImplCycleCollectionUnlink(IDTracker
& aField
) { aField
.Unlink(); }
198 inline void ImplCycleCollectionTraverse(
199 nsCycleCollectionTraversalCallback
& aCallback
, IDTracker
& aField
,
200 const char* aName
, uint32_t aFlags
= 0) {
201 aField
.Traverse(&aCallback
);
204 } // namespace mozilla::dom
206 #endif /* mozilla_dom_IDTracker_h_ */