dom/svg/DOMSVGPathSegList.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 DOM_SVG_DOMSVGPATHSEGLIST_H_
   8 #define DOM_SVG_DOMSVGPATHSEGLIST_H_
   9
  10 #include "mozAutoDocUpdate.h"
  11 #include "nsCycleCollectionParticipant.h"
  12 #include "nsDebug.h"
  13 #include "nsTArray.h"
  14 #include "SVGPathData.h"  // IWYU pragma: keep
  15 #include "mozilla/Attributes.h"
  16 #include "mozilla/RefPtr.h"
  17 #include "mozilla/dom/SVGElement.h"
  18
  19 namespace mozilla {
  20
  21 class ErrorResult;
  22 class SVGAnimatedPathSegList;
  23
  24 namespace dom {
  25
  26 class DOMSVGPathSeg;
  27
  28 //----------------------------------------------------------------------
  29 // Helper class: AutoChangePathSegListNotifier
  30 // Stack-based helper class to pair calls to WillChangePathSegList and
  31 // DidChangePathSegList. Used by DOMSVGPathSeg and DOMSVGPathSegList.
  32 template <class T>
  33 class MOZ_RAII AutoChangePathSegListNotifier : public mozAutoDocUpdate {
  34  public:
  35   explicit AutoChangePathSegListNotifier(T* aValue)
  36       : mozAutoDocUpdate(aValue->Element()->GetComposedDoc(), true),
  37         mValue(aValue) {
  38     MOZ_ASSERT(mValue, "Expecting non-null value");
  39     mEmptyOrOldValue = mValue->Element()->WillChangePathSegList(*this);
  40   }
  41
  42   ~AutoChangePathSegListNotifier() {
  43     mValue->Element()->DidChangePathSegList(mEmptyOrOldValue, *this);
  44     if (mValue->AttrIsAnimating()) {
  45       mValue->Element()->AnimationNeedsResample();
  46     }
  47   }
  48
  49  private:
  50   T* const mValue;
  51   nsAttrValue mEmptyOrOldValue;
  52 };
  53
  54 /**
  55  * Class DOMSVGPathSegList
  56  *
  57  * This class is used to create the DOM tearoff objects that wrap internal
  58  * SVGPathData objects.
  59  *
  60  * See the architecture comment in DOMSVGAnimatedLengthList.h first (that's
  61  * LENGTH list), then continue reading the remainder of this comment.
  62  *
  63  * The architecture of this class is very similar to that of DOMSVGLengthList
  64  * except that, since there is no nsIDOMSVGAnimatedPathSegList interface
  65  * in SVG, we have no parent DOMSVGAnimatedPathSegList (unlike DOMSVGLengthList
  66  * which has a parent DOMSVGAnimatedLengthList class). (There is an
  67  * SVGAnimatedPathData interface, but that is quite different to
  68  * DOMSVGAnimatedLengthList, since it is inherited by elements rather than
  69  * elements having members of that type.) As a consequence, much of the logic
  70  * that would otherwise be in DOMSVGAnimatedPathSegList (and is in
  71  * DOMSVGAnimatedLengthList) is contained in this class.
  72  *
  73  * This class is strongly intertwined with DOMSVGPathSeg. Our DOMSVGPathSeg
  74  * items are friends of us and responsible for nulling out our pointers to
  75  * them when they die.
  76  *
  77  * Our DOM items are created lazily on demand as and when script requests them.
  78  */
  79 class DOMSVGPathSegList final : public nsISupports, public nsWrapperCache {
  80   template <class T>
  81   friend class AutoChangePathSegListNotifier;
  82   friend class DOMSVGPathSeg;
  83
  84  public:
  85   NS_DECL_CYCLE_COLLECTING_ISUPPORTS
  86   NS_DECL_CYCLE_COLLECTION_SCRIPT_HOLDER_CLASS(DOMSVGPathSegList)
  87
  88   JSObject* WrapObject(JSContext* cx,
  89                        JS::Handle<JSObject*> aGivenProto) override;
  90
  91   nsISupports* GetParentObject() { return static_cast<nsIContent*>(mElement); }
  92
  93   /**
  94    * Factory method to create and return a DOMSVGPathSegList wrapper
  95    * for a given internal SVGPathData object. The factory takes care
  96    * of caching the object that it returns so that the same object can be
  97    * returned for the given SVGPathData each time it is requested.
  98    * The cached object is only removed from the cache when it is destroyed due
  99    * to there being no more references to it or to any of its descendant
 100    * objects. If that happens, any subsequent call requesting the DOM wrapper
 101    * for the SVGPathData will naturally result in a new
 102    * DOMSVGPathSegList being returned.
 103    *
 104    * It's unfortunate that aList is a void* instead of a typed argument. This
 105    * is because the mBaseVal and mAnimVal members of SVGAnimatedPathSegList are
 106    * of different types - a plain SVGPathData, and a SVGPathData*. We
 107    * use the addresses of these members as the key for the hash table, and
 108    * clearly SVGPathData* and a SVGPathData** are not the same type.
 109    */
 110   static already_AddRefed<DOMSVGPathSegList> GetDOMWrapper(
 111       void* aList, dom::SVGElement* aElement, bool aIsAnimValList);
 112
 113   /**
 114    * This method returns the DOMSVGPathSegList wrapper for an internal
 115    * SVGPathData object if it currently has a wrapper. If it does
 116    * not, then nullptr is returned.
 117    */
 118   static DOMSVGPathSegList* GetDOMWrapperIfExists(void* aList);
 119
 120   /**
 121    * This will normally be the same as InternalList().CountItems(), except if
 122    * we've hit OOM, in which case our length will be zero.
 123    */
 124   uint32_t LengthNoFlush() const {
 125     MOZ_ASSERT(
 126         mItems.Length() == 0 || mItems.Length() == InternalList().CountItems(),
 127         "DOM wrapper's list length is out of sync");
 128     return mItems.Length();
 129   }
 130
 131   /**
 132    * WATCH OUT! If you add code to call this on a baseVal wrapper, then you
 133    * must also call it on the animVal wrapper too if necessary!! See other
 134    * callers!
 135    *
 136    * Called by internal code to notify us when we need to sync the length of
 137    * this DOM list with its internal list. This is called immediately prior to
 138    * the length of the internal list being changed so that any DOM list items
 139    * that need to be removed from the DOM list can first copy their values from
 140    * their internal counterpart.
 141    *
 142    * The only time this method could fail is on OOM when trying to increase the
 143    * length of the DOM list. If that happens then this method simply clears the
 144    * list and returns. Callers just proceed as normal, and we simply accept
 145    * that the DOM list will be empty (until successfully set to a new value).
 146    */
 147   void InternalListWillChangeTo(const SVGPathData& aNewValue);
 148
 149   /**
 150    * Returns true if our attribute is animating (in which case our animVal is
 151    * not simply a mirror of our baseVal).
 152    */
 153   bool AttrIsAnimating() const;
 154   /**
 155    * Returns true if there is an animated list mirroring the base list.
 156    */
 157   bool AnimListMirrorsBaseList() const;
 158
 159   uint32_t NumberOfItems() const {
 160     if (IsAnimValList()) {
 161       Element()->FlushAnimations();
 162     }
 163     return LengthNoFlush();
 164   }
 165   void Clear(ErrorResult& aError);
 166   already_AddRefed<DOMSVGPathSeg> Initialize(DOMSVGPathSeg& aNewItem,
 167                                              ErrorResult& aError);
 168   already_AddRefed<DOMSVGPathSeg> GetItem(uint32_t index, ErrorResult& error);
 169   already_AddRefed<DOMSVGPathSeg> IndexedGetter(uint32_t index, bool& found,
 170                                                 ErrorResult& error);
 171   already_AddRefed<DOMSVGPathSeg> InsertItemBefore(DOMSVGPathSeg& aNewItem,
 172                                                    uint32_t aIndex,
 173                                                    ErrorResult& aError);
 174   already_AddRefed<DOMSVGPathSeg> ReplaceItem(DOMSVGPathSeg& aNewItem,
 175                                               uint32_t aIndex,
 176                                               ErrorResult& aError);
 177   already_AddRefed<DOMSVGPathSeg> RemoveItem(uint32_t aIndex,
 178                                              ErrorResult& aError);
 179   already_AddRefed<DOMSVGPathSeg> AppendItem(DOMSVGPathSeg& aNewItem,
 180                                              ErrorResult& aError) {
 181     return InsertItemBefore(aNewItem, LengthNoFlush(), aError);
 182   }
 183   uint32_t Length() const { return NumberOfItems(); }
 184
 185  private:
 186   /**
 187    * Only our static GetDOMWrapper() factory method may create objects of our
 188    * type.
 189    */
 190   DOMSVGPathSegList(dom::SVGElement* aElement, bool aIsAnimValList)
 191       : mElement(aElement), mIsAnimValList(aIsAnimValList) {
 192     InternalListWillChangeTo(InternalList());  // Sync mItems
 193   }
 194
 195   ~DOMSVGPathSegList();
 196
 197   dom::SVGElement* Element() const { return mElement.get(); }
 198
 199   /// Used to determine if this list is the baseVal or animVal list.
 200   bool IsAnimValList() const { return mIsAnimValList; }
 201
 202   /**
 203    * Get a reference to this object's corresponding internal SVGPathData.
 204    *
 205    * To simplify the code we just have this one method for obtaining both
 206    * base val and anim val internal lists. This means that anim val lists don't
 207    * get const protection, but our setter methods guard against changing
 208    * anim val lists.
 209    */
 210   SVGPathData& InternalList() const;
 211
 212   SVGAnimatedPathSegList& InternalAList() const;
 213
 214   /// Creates an instance of the appropriate DOMSVGPathSeg sub-class for
 215   // aIndex, if it doesn't already exist, and then returns it.
 216   already_AddRefed<DOMSVGPathSeg> GetItemAt(uint32_t aIndex);
 217
 218   void MaybeInsertNullInAnimValListAt(uint32_t aIndex, uint32_t aInternalIndex,
 219                                       uint32_t aArgCountForItem);
 220   void MaybeRemoveItemFromAnimValListAt(uint32_t aIndex,
 221                                         int32_t aArgCountForItem);
 222
 223   // Calls UpdateListIndex on all elements in |mItems| that satisfy ItemAt(),
 224   // from |aStartingIndex| to the end of |mItems|.  Also adjusts
 225   // |mItems.mInternalDataIndex| by the requested amount.
 226   void UpdateListIndicesFromIndex(uint32_t aStartingIndex,
 227                                   int32_t aInternalDataIndexDelta);
 228
 229   DOMSVGPathSeg*& ItemAt(uint32_t aIndex) { return mItems[aIndex].mItem; }
 230
 231   void RemoveFromTearoffTable();
 232
 233   /**
 234    * This struct is used in our array of mItems to provide us with somewhere to
 235    * store the indexes into the internal SVGPathData of the internal seg data
 236    * that our DOMSVGPathSeg items wrap (the internal segment data is or varying
 237    * length, so we can't just use the index of our DOMSVGPathSeg items
 238    * themselves). The reason that we have this separate struct rather than
 239    * just storing the internal indexes in the DOMSVGPathSeg items is because we
 240    * want to create the DOMSVGPathSeg items lazily on demand.
 241    */
 242   struct ItemProxy {
 243     ItemProxy() : mItem(nullptr), mInternalDataIndex(0) {}
 244     ItemProxy(DOMSVGPathSeg* aItem, uint32_t aInternalDataIndex)
 245         : mItem(aItem), mInternalDataIndex(aInternalDataIndex) {}
 246
 247     DOMSVGPathSeg* mItem;
 248     uint32_t mInternalDataIndex;
 249   };
 250
 251   // Weak refs to our DOMSVGPathSeg items. The items are friends and take care
 252   // of clearing our pointer to them when they die.
 253   FallibleTArray<ItemProxy> mItems;
 254
 255   // Strong ref to our element to keep it alive. We hold this not only for
 256   // ourself, but also for our DOMSVGPathSeg items too.
 257   RefPtr<dom::SVGElement> mElement;
 258
 259   bool mIsAnimValList;
 260 };
 261
 262 }  // namespace dom
 263 }  // namespace mozilla
 264
 265 #endif  // DOM_SVG_DOMSVGPATHSEGLIST_H_