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