dom/base/HighlightRegistry.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_HighlightRegistry_h
   8 #define mozilla_dom_HighlightRegistry_h
   9
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/CompactPair.h"
  12 #include "mozilla/dom/BindingDeclarations.h"
  13 #include "nsCycleCollectionParticipant.h"
  14 #include "nsHashKeys.h"
  15 #include "nsTHashMap.h"
  16 #include "nsHashtablesFwd.h"
  17 #include "nsWrapperCache.h"
  18
  19 class nsFrameSelection;
  20
  21 namespace mozilla {
  22 class ErrorResult;
  23 }
  24 namespace mozilla::dom {
  25
  26 class AbstractRange;
  27 class Document;
  28 class Highlight;
  29
  30 /**
  31  * @brief HighlightRegistry manages all `Highlight`s available to a `Document`.
  32  *
  33  * This class is exposed via `HighlightRegistry.webidl` and used to
  34  * add or remove `Highlight` instances to a document and binding it
  35  * to a highlight name.
  36  *
  37  * The HighlightRegistry idl interface defines this class to be a `maplike`.
  38  * To be able to access the members of the maplike without proper support
  39  * for iteration from C++, the insertion and deletion operations are
  40  * overridden and the data is also held inside of this class.
  41  *
  42  * @see https://drafts.csswg.org/css-highlight-api-1/#registration
  43  */
  44 class HighlightRegistry final : public nsISupports, public nsWrapperCache {
  45  public:
  46   NS_DECL_CYCLE_COLLECTING_ISUPPORTS
  47   NS_DECL_CYCLE_COLLECTION_WRAPPERCACHE_CLASS(HighlightRegistry)
  48
  49  public:
  50   explicit HighlightRegistry(Document* aDocument);
  51
  52  protected:
  53   ~HighlightRegistry();
  54
  55  public:
  56   /**
  57    * @brief Adds selections for all highlights to the `FrameSelection`.
  58    *
  59    * This method is called if highlights are added to the registry before
  60    * a `FrameSelection` is available.
  61    */
  62   MOZ_CAN_RUN_SCRIPT void AddHighlightSelectionsToFrameSelection();
  63
  64   /**
  65    * @brief Adds the Range to the Highlight Selection if it belongs to the same
  66    * Document.
  67    *
  68    * If no Highlight Selection for this highlight exists, it will be created.
  69    * This may occur when a Highlight is added to the Registry after the
  70    * nsFrameSelection is created.
  71    */
  72   MOZ_CAN_RUN_SCRIPT void MaybeAddRangeToHighlightSelection(
  73       AbstractRange& aRange, Highlight& aHighlight);
  74
  75   /**
  76    * @brief Removes the Range from the Highlight Selection if it belongs to the
  77    * same Document.
  78    *
  79    * @note If the last range of a highlight selection is removed, the selection
  80    * itself is *not* removed.
  81    */
  82   MOZ_CAN_RUN_SCRIPT void MaybeRemoveRangeFromHighlightSelection(
  83       AbstractRange& aRange, Highlight& aHighlight);
  84
  85   /**
  86    * @brief Removes the highlight selections associated with the highlight.
  87    *
  88    * This method is called when the Highlight is cleared
  89    * (i.e., all Ranges are removed).
  90    */
  91   MOZ_CAN_RUN_SCRIPT void RemoveHighlightSelection(Highlight& aHighlight);
  92
  93   // WebIDL interface
  94
  95   Document* GetParentObject() const { return mDocument; };
  96
  97   JSObject* WrapObject(JSContext* aCx,
  98                        JS::Handle<JSObject*> aGivenProto) override;
  99
 100   /**
 101    * @brief Adds a new `Highlight` to `this` using `aKey` as highlight name.
 102    *
 103    * Highlight instances are ordered by insertion.
 104    *
 105    * This call registers `this` and `aHighlightName` in the highlight given in
 106    * `aValue`.
 107    *
 108    * If a `FrameSelection` is present, a highlight selection is created.
 109    */
 110   MOZ_CAN_RUN_SCRIPT void Set(const nsAString& aKey, Highlight& aValue,
 111                               ErrorResult& aRv);
 112
 113   /**
 114    * @brief Removes all highlights from this registry.
 115    *
 116    * If a `FrameSelection` is present, all highlight selections are removed.
 117    */
 118   MOZ_CAN_RUN_SCRIPT void Clear(ErrorResult& aRv);
 119
 120   /**
 121    * @brief Removes the highlight named `aKey` from the registry.
 122    *
 123    * This call removes the combination of `this` and `aKey` from the highlight.
 124    * If a `FrameSelection` is present, the highlight selection is removed.
 125    *
 126    * @return true if `aKey` existed and was deleted.
 127    */
 128   MOZ_CAN_RUN_SCRIPT bool Delete(const nsAString& aKey, ErrorResult& aRv);
 129
 130   /**
 131    * @brief Get the `FrameSelection` object if available. Can return nullptr.
 132    */
 133   RefPtr<nsFrameSelection> GetFrameSelection();
 134
 135   /**
 136    * @brief Get the registry name-value tuples.
 137    */
 138   nsTArray<CompactPair<RefPtr<nsAtom>, RefPtr<Highlight>>> const&
 139   HighlightsOrdered() {
 140     return mHighlightsOrdered;
 141   }
 142
 143  private:
 144   /**
 145    * Parent document.
 146    */
 147   RefPtr<Document> mDocument;
 148
 149   /**
 150    * Highlight instances are stored as array of name-value tuples
 151    * instead of a hashmap in order to preserve the insertion order.
 152    *
 153    * This is done
 154    *    a) to keep the order in sync with the underlying
 155    *       data structure of the `maplike` interface and
 156    *    b) because the insertion order defines the stacking order of
 157    *       of highlights that have the same priority.
 158    */
 159   nsTArray<CompactPair<RefPtr<nsAtom>, RefPtr<Highlight>>> mHighlightsOrdered;
 160 };
 161
 162 }  // namespace mozilla::dom
 163
 164 #endif  // mozilla_dom_HighlightRegistry_h