dom/base/Highlight.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   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_Highlight_h
   8 #define mozilla_dom_Highlight_h
   9
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/dom/BindingDeclarations.h"
  12 #include "mozilla/dom/HighlightBinding.h"
  13
  14 #include "nsCycleCollectionParticipant.h"
  15 #include "nsAtomHashKeys.h"
  16 #include "nsTHashSet.h"
  17 #include "nsTArray.h"
  18 #include "nsWrapperCache.h"
  19
  20 class nsFrameSelection;
  21 class nsPIDOMWindowInner;
  22 namespace mozilla {
  23 class ErrorResult;
  24 }
  25
  26 namespace mozilla::dom {
  27 class AbstractRange;
  28 class Document;
  29 class HighlightRegistry;
  30 class Selection;
  31
  32 /**
  33  * @brief Collection of all data of a highlight instance.
  34  *
  35  * This struct is intended to be allocated on the stack and passed on
  36  * to the `nsFrameSelection` and layout code.
  37  */
  38 struct HighlightSelectionData {
  39   RefPtr<nsAtom> mHighlightName;
  40   RefPtr<Highlight> mHighlight;
  41 };
  42
  43 /**
  44  * @brief Representation of a custom `Highlight`.
  45  *
  46  * A `Highlight` is defined in JS as a collection of `AbstractRange`s.
  47  * Furthermore, a custom highlight contains the highlight type and priority.
  48  *
  49  * A highlight is added to a document using the `HighlightRegistry` interface.
  50  * A highlight can be added to a document using different names as well as to
  51  * multiple `HighlightRegistries`.
  52  * To propagate runtime changes of the highlight to its registries, an
  53  * observer pattern is implemented.
  54  *
  55  * The spec defines this class as a `setlike`. To allow access and iteration
  56  * of the setlike contents from C++, the insertion and deletion operations are
  57  * overridden and the Ranges are also stored internally in an Array.
  58  *
  59  * @see https://drafts.csswg.org/css-highlight-api-1/#creation
  60  */
  61 class Highlight final : public nsISupports, public nsWrapperCache {
  62  public:
  63   NS_DECL_CYCLE_COLLECTING_ISUPPORTS
  64   NS_DECL_CYCLE_COLLECTION_WRAPPERCACHE_CLASS(Highlight)
  65
  66  protected:
  67   MOZ_CAN_RUN_SCRIPT Highlight(
  68       const Sequence<OwningNonNull<AbstractRange>>& aInitialRanges,
  69       nsPIDOMWindowInner* aWindow, ErrorResult& aRv);
  70   ~Highlight() = default;
  71
  72  public:
  73   /**
  74    * @brief Adds `this` to `aHighlightRegistry`.
  75    *
  76    * Highlights must know of all registry objects which contain them, so that
  77    * the registries can be notified when a property of the Highlight changes.
  78    *
  79    * Since a Highlight can be part of a registry using different names,
  80    * the name has to be provided as well.
  81    */
  82   void AddToHighlightRegistry(HighlightRegistry& aHighlightRegistry,
  83                               nsAtom& aHighlightName);
  84
  85   /**
  86    * @brief Removes `this` from `aHighlightRegistry`.
  87    */
  88   void RemoveFromHighlightRegistry(HighlightRegistry& aHighlightRegistry,
  89                                    nsAtom& aHighlightName);
  90
  91   /**
  92    * @brief Creates a Highlight Selection using the given ranges.
  93    */
  94   MOZ_CAN_RUN_SCRIPT already_AddRefed<Selection> CreateHighlightSelection(
  95       nsAtom* aHighlightName, nsFrameSelection* aFrameSelection);
  96
  97   // WebIDL interface
  98   nsPIDOMWindowInner* GetParentObject() const { return mWindow; }
  99
 100   JSObject* WrapObject(JSContext* aCx,
 101                        JS::Handle<JSObject*> aGivenProto) override;
 102
 103   static MOZ_CAN_RUN_SCRIPT_BOUNDARY already_AddRefed<Highlight> Constructor(
 104       const GlobalObject& aGlobal,
 105       const Sequence<OwningNonNull<AbstractRange>>& aInitialRanges,
 106       ErrorResult& aRv);
 107
 108   /**
 109    * @brief Priority of this highlight.
 110    *
 111    * Priority is used to stack overlapping highlights.
 112    */
 113   int32_t Priority() const { return mPriority; }
 114
 115   /**
 116    * @brief Set the priority of this Highlight.
 117    *
 118    * Priority is used to stack overlapping highlights.
 119    */
 120   void SetPriority(int32_t aPriority) { mPriority = aPriority; }
 121
 122   /**
 123    * @brief The HighlightType of this Highlight (Highlight, Spelling Error,
 124    * Grammar Error)
 125    */
 126   HighlightType Type() const { return mHighlightType; }
 127
 128   /**
 129    * @brief Sets the HighlightType (Highlight, Spelling Error, Grammar Error)
 130    */
 131   void SetType(HighlightType aHighlightType) {
 132     mHighlightType = aHighlightType;
 133   }
 134
 135   /**
 136    * @brief This mirrors the `size` property in JS world (_not_ exposed via
 137    * webIDL)
 138    */
 139   uint32_t Size() const { return mRanges.Length(); }
 140
 141   /**
 142    * @brief Adds a `Range` to this highlight.
 143    *
 144    * This adds `aRange` both to the setlike data storage and the internal one
 145    * needed for iteration, if it is not yet present.
 146    *
 147    * Also notifies all `HighlightRegistry` instances.
 148    */
 149   MOZ_CAN_RUN_SCRIPT void Add(AbstractRange& aRange, ErrorResult& aRv);
 150
 151   /**
 152    * @brief Removes all ranges from this highlight.
 153    *
 154    * This removes all highlights from the setlike data structure as well as from
 155    * the internal one.
 156    *
 157    * Also notifies all `HighlightRegistry` instances.
 158    */
 159   MOZ_CAN_RUN_SCRIPT void Clear(ErrorResult& aRv);
 160
 161   /**
 162    * @brief Removes `aRange` from this highlight.
 163    *
 164    * This removes `aRange` from the setlike data structure as well as from the
 165    * internal one.
 166    *
 167    * Also notifies all `HighlightRegistry` instances.
 168    *
 169    * @return As per spec, returns true if the range was deleted.
 170    */
 171   MOZ_CAN_RUN_SCRIPT bool Delete(AbstractRange& aRange, ErrorResult& aRv);
 172
 173  private:
 174   RefPtr<nsPIDOMWindowInner> mWindow;
 175
 176   /**
 177    * All Range objects contained in this highlight.
 178    */
 179   nsTArray<RefPtr<AbstractRange>> mRanges;
 180
 181   /**
 182    * Type of this highlight.
 183    * @see HighlightType
 184    */
 185   HighlightType mHighlightType{HighlightType::Highlight};
 186
 187   /**
 188    * Priority of this highlight.
 189    *
 190    * If highlights are overlapping, the priority can
 191    * be used to prioritize. If the priorities of all
 192    * Highlights involved are equal, the highlights are
 193    * stacked in order of ther insertion into the
 194    * `HighlightRegistry`.
 195    */
 196   int32_t mPriority{0};
 197
 198   /**
 199    * All highlight registries that contain this Highlight.
 200    *
 201    * A highlight can be included in several registries
 202    * using several names.
 203    *
 204    * Note: Storing `HighlightRegistry` as raw pointer is safe here
 205    * because it unregisters itself from `this` when it is destroyed/CC'd
 206    */
 207   nsTHashMap<nsPtrHashKey<HighlightRegistry>, nsTHashSet<RefPtr<nsAtom>>>
 208       mHighlightRegistries;
 209 };
 210
 211 }  // namespace mozilla::dom
 212
 213 #endif  // mozilla_dom_Highlight_h