dom/base/AbstractRange.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_AbstractRange_h
   8 #define mozilla_dom_AbstractRange_h
   9
  10 #include <cstdint>
  11 #include <ostream>
  12 #include "ErrorList.h"
  13 #include "js/RootingAPI.h"
  14 #include "mozilla/Assertions.h"
  15 #include "mozilla/Maybe.h"
  16 #include "mozilla/RangeBoundary.h"
  17 #include "mozilla/RefPtr.h"
  18 #include "mozilla/WeakPtr.h"
  19 #include "nsCycleCollectionParticipant.h"
  20 #include "nsISupports.h"
  21 #include "nsWrapperCache.h"
  22
  23 class JSObject;
  24 class nsIContent;
  25 class nsINode;
  26 class nsRange;
  27 struct JSContext;
  28
  29 namespace mozilla::dom {
  30 class Document;
  31 class Selection;
  32 class StaticRange;
  33
  34 enum class AllowRangeCrossShadowBoundary : bool { No, Yes };
  35
  36 class AbstractRange : public nsISupports,
  37                       public nsWrapperCache,
  38                       // For linking together selection-associated ranges.
  39                       public mozilla::LinkedListElement<AbstractRange> {
  40   using AllowRangeCrossShadowBoundary =
  41       mozilla::dom::AllowRangeCrossShadowBoundary;
  42
  43  protected:
  44   explicit AbstractRange(nsINode* aNode, bool aIsDynamicRange);
  45   virtual ~AbstractRange();
  46
  47  public:
  48   AbstractRange() = delete;
  49   explicit AbstractRange(const AbstractRange& aOther) = delete;
  50
  51   /**
  52    * Called when the process is shutting down.
  53    */
  54   static void Shutdown();
  55
  56   NS_DECL_CYCLE_COLLECTING_ISUPPORTS
  57   NS_DECL_CYCLE_COLLECTION_WRAPPERCACHE_CLASS(AbstractRange)
  58
  59   /**
  60    * All of the MayCrossShadowBoundary* methods are used to get the boundary
  61    * endpoints that cross shadow boundaries. They would return
  62    * the same value as the non-MayCrossShadowBoundary* methods if the range
  63    * boundaries don't cross shadow boundaries.
  64    */
  65   const RangeBoundary& StartRef() const { return mStart; }
  66   const RangeBoundary& MayCrossShadowBoundaryStartRef() const;
  67
  68   const RangeBoundary& EndRef() const { return mEnd; }
  69   const RangeBoundary& MayCrossShadowBoundaryEndRef() const;
  70
  71   nsIContent* GetChildAtStartOffset() const {
  72     return mStart.GetChildAtOffset();
  73   }
  74   nsIContent* GetMayCrossShadowBoundaryChildAtStartOffset() const;
  75
  76   nsIContent* GetChildAtEndOffset() const { return mEnd.GetChildAtOffset(); }
  77   nsIContent* GetMayCrossShadowBoundaryChildAtEndOffset() const;
  78
  79   bool IsPositioned() const { return mIsPositioned; }
  80   /**
  81    * https://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor
  82    */
  83   nsINode* GetClosestCommonInclusiveAncestor(
  84       AllowRangeCrossShadowBoundary aAllowCrossShadowBoundary =
  85           AllowRangeCrossShadowBoundary::No) const;
  86
  87   // WebIDL
  88
  89   // If Range is created from JS, it's initialized with Document.createRange()
  90   // and it collaps the range to start of the Document.  Therefore, the
  91   // following WebIDL methods are called only when `mIsPositioned` is true.
  92   // So, it does not make sense to take `ErrorResult` as their parameter
  93   // since its destruction cost may appear in profile.  If you create range
  94   // object from C++ and needs to check whether it's positioned, should call
  95   // `IsPositioned()` directly.
  96
  97   nsINode* GetStartContainer() const { return mStart.Container(); }
  98   nsINode* GetMayCrossShadowBoundaryStartContainer() const;
  99
 100   nsINode* GetEndContainer() const { return mEnd.Container(); }
 101   nsINode* GetMayCrossShadowBoundaryEndContainer() const;
 102
 103   bool MayCrossShadowBoundary() const;
 104
 105   Document* GetComposedDocOfContainers() const {
 106     return mStart.Container() ? mStart.Container()->GetComposedDoc() : nullptr;
 107   }
 108
 109   // FYI: Returns 0 if it's not positioned.
 110   uint32_t StartOffset() const {
 111     return static_cast<uint32_t>(
 112         *mStart.Offset(RangeBoundary::OffsetFilter::kValidOrInvalidOffsets));
 113   }
 114   uint32_t MayCrossShadowBoundaryStartOffset() const;
 115
 116   // FYI: Returns 0 if it's not positioned.
 117   uint32_t EndOffset() const {
 118     return static_cast<uint32_t>(
 119         *mEnd.Offset(RangeBoundary::OffsetFilter::kValidOrInvalidOffsets));
 120   }
 121   uint32_t MayCrossShadowBoundaryEndOffset() const;
 122
 123   bool Collapsed() const {
 124     return !mIsPositioned || (mStart.Container() == mEnd.Container() &&
 125                               StartOffset() == EndOffset());
 126   }
 127
 128   nsINode* GetParentObject() const;
 129   virtual JSObject* WrapObject(JSContext* aCx,
 130                                JS::Handle<JSObject*> aGivenProto) override;
 131
 132   bool HasEqualBoundaries(const AbstractRange& aOther) const {
 133     return (mStart == aOther.mStart) && (mEnd == aOther.mEnd);
 134   }
 135   bool IsDynamicRange() const { return mIsDynamicRange; }
 136   bool IsStaticRange() const { return !mIsDynamicRange; }
 137   inline nsRange* AsDynamicRange();
 138   inline const nsRange* AsDynamicRange() const;
 139   inline StaticRange* AsStaticRange();
 140   inline const StaticRange* AsStaticRange() const;
 141
 142   /**
 143    * Return true if this range is part of a Selection object
 144    * and isn't detached.
 145    */
 146   bool IsInAnySelection() const { return !mSelections.IsEmpty(); }
 147
 148   MOZ_CAN_RUN_SCRIPT void RegisterSelection(
 149       mozilla::dom::Selection& aSelection);
 150
 151   void UnregisterSelection(const mozilla::dom::Selection& aSelection);
 152
 153   /**
 154    * Returns a list of all Selections the range is associated with.
 155    */
 156   const nsTArray<WeakPtr<Selection>>& GetSelections() const;
 157
 158   /**
 159    * Return true if this range is in |aSelection|.
 160    */
 161   bool IsInSelection(const mozilla::dom::Selection& aSelection) const;
 162
 163  protected:
 164   template <typename SPT, typename SRT, typename EPT, typename ERT,
 165             typename RangeType>
 166   static nsresult SetStartAndEndInternal(
 167       const RangeBoundaryBase<SPT, SRT>& aStartBoundary,
 168       const RangeBoundaryBase<EPT, ERT>& aEndBoundary, RangeType* aRange);
 169
 170   template <class RangeType>
 171   static bool MaybeCacheToReuse(RangeType& aInstance);
 172
 173   void Init(nsINode* aNode);
 174
 175   friend std::ostream& operator<<(std::ostream& aStream,
 176                                   const AbstractRange& aRange) {
 177     if (aRange.Collapsed()) {
 178       aStream << "{ mStart=mEnd=" << aRange.mStart;
 179     } else {
 180       aStream << "{ mStart=" << aRange.mStart << ", mEnd=" << aRange.mEnd;
 181     }
 182     return aStream << ", mIsGenerated="
 183                    << (aRange.mIsGenerated ? "true" : "false")
 184                    << ", mCalledByJS="
 185                    << (aRange.mIsPositioned ? "true" : "false")
 186                    << ", mIsDynamicRange="
 187                    << (aRange.mIsDynamicRange ? "true" : "false") << " }";
 188   }
 189
 190   /**
 191    * https://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor
 192    */
 193   void RegisterClosestCommonInclusiveAncestor(nsINode* aNode);
 194   /**
 195    * https://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor
 196    */
 197   void UnregisterClosestCommonInclusiveAncestor(nsINode* aNode,
 198                                                 bool aIsUnlinking);
 199
 200   void UpdateCommonAncestorIfNecessary();
 201
 202   static void MarkDescendants(const nsINode& aNode);
 203   static void UnmarkDescendants(const nsINode& aNode);
 204
 205  private:
 206   void ClearForReuse();
 207
 208  protected:
 209   RefPtr<Document> mOwner;
 210   RangeBoundary mStart;
 211   RangeBoundary mEnd;
 212
 213   // A Range can be part of multiple |Selection|s. This is a very rare use case.
 214   AutoTArray<WeakPtr<Selection>, 1> mSelections;
 215   // mRegisteredClosestCommonInclusiveAncestor is only non-null when the range
 216   // IsInAnySelection().
 217   nsCOMPtr<nsINode> mRegisteredClosestCommonInclusiveAncestor;
 218
 219   // `true` if `mStart` and `mEnd` are set for StaticRange or set and valid
 220   // for nsRange.
 221   bool mIsPositioned;
 222
 223   // Used by nsRange, but this should have this for minimizing the size.
 224   bool mIsGenerated;
 225   // Used by nsRange, but this should have this for minimizing the size.
 226   bool mCalledByJS;
 227
 228   // true if this is an `nsRange` object.
 229   const bool mIsDynamicRange;
 230
 231   static bool sHasShutDown;
 232 };
 233
 234 }  // namespace mozilla::dom
 235
 236 #endif  // #ifndef mozilla_dom_AbstractRange_h