accessible/base/AccIterator.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=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_a11y_AccIterator_h__
   8 #define mozilla_a11y_AccIterator_h__
   9
  10 #include "Filters.h"
  11 #include "mozilla/a11y/DocAccessible.h"
  12 #include "nsTArray.h"
  13
  14 #include <memory>
  15
  16 class nsITreeView;
  17
  18 namespace mozilla {
  19 namespace a11y {
  20 class DocAccessibleParent;
  21
  22 /**
  23  * AccIterable is a basic interface for iterators over accessibles.
  24  */
  25 class AccIterable {
  26  public:
  27   virtual ~AccIterable() {}
  28   virtual Accessible* Next() = 0;
  29
  30  private:
  31   friend class Relation;
  32   std::unique_ptr<AccIterable> mNextIter;
  33 };
  34
  35 /**
  36  * Allows to iterate through accessible children or subtree complying with
  37  * filter function.
  38  */
  39 class AccIterator : public AccIterable {
  40  public:
  41   AccIterator(const LocalAccessible* aRoot, filters::FilterFuncPtr aFilterFunc);
  42   virtual ~AccIterator();
  43
  44   /**
  45    * Return next accessible complying with filter function. Return the first
  46    * accessible for the first time.
  47    */
  48   virtual LocalAccessible* Next() override;
  49
  50  private:
  51   AccIterator();
  52   AccIterator(const AccIterator&);
  53   AccIterator& operator=(const AccIterator&);
  54
  55   struct IteratorState {
  56     explicit IteratorState(const LocalAccessible* aParent,
  57                            IteratorState* mParentState = nullptr);
  58
  59     const LocalAccessible* mParent;
  60     int32_t mIndex;
  61     IteratorState* mParentState;
  62   };
  63
  64   filters::FilterFuncPtr mFilterFunc;
  65   IteratorState* mState;
  66 };
  67
  68 /**
  69  * Allows to traverse through related accessibles that are pointing to the given
  70  * dependent accessible by relation attribute.
  71  */
  72 class RelatedAccIterator : public AccIterable {
  73  public:
  74   /**
  75    * Constructor.
  76    *
  77    * @param aDocument         [in] the document accessible the related
  78    * &                         accessibles belong to.
  79    * @param aDependentContent [in] the content of dependent accessible that
  80    *                           relations were requested for
  81    * @param aRelAttr          [in] relation attribute that relations are
  82    *                           pointed by
  83    */
  84   RelatedAccIterator(DocAccessible* aDocument, nsIContent* aDependentContent,
  85                      nsAtom* aRelAttr);
  86
  87   virtual ~RelatedAccIterator() {}
  88
  89   /**
  90    * Return next related accessible for the given dependent accessible.
  91    */
  92   virtual LocalAccessible* Next() override;
  93
  94  private:
  95   RelatedAccIterator();
  96   RelatedAccIterator(const RelatedAccIterator&);
  97   RelatedAccIterator& operator=(const RelatedAccIterator&);
  98
  99   DocAccessible* mDocument;
 100   nsAtom* mRelAttr;
 101   DocAccessible::AttrRelProviders* mProviders;
 102   uint32_t mIndex;
 103 };
 104
 105 /**
 106  * Used to iterate through HTML labels associated with the given accessible.
 107  */
 108 class HTMLLabelIterator : public AccIterable {
 109  public:
 110   enum LabelFilter { eAllLabels, eSkipAncestorLabel };
 111
 112   HTMLLabelIterator(DocAccessible* aDocument,
 113                     const LocalAccessible* aAccessible,
 114                     LabelFilter aFilter = eAllLabels);
 115
 116   virtual ~HTMLLabelIterator() {}
 117
 118   /**
 119    * Return next label accessible associated with the given element.
 120    */
 121   virtual LocalAccessible* Next() override;
 122
 123  private:
 124   HTMLLabelIterator();
 125   HTMLLabelIterator(const HTMLLabelIterator&);
 126   HTMLLabelIterator& operator=(const HTMLLabelIterator&);
 127
 128   bool IsLabel(LocalAccessible* aLabel);
 129
 130   RelatedAccIterator mRelIter;
 131   // XXX: replace it on weak reference (bug 678429), it's safe to use raw
 132   // pointer now because iterators life cycle is short.
 133   const LocalAccessible* mAcc;
 134   LabelFilter mLabelFilter;
 135 };
 136
 137 /**
 138  * Used to iterate through HTML outputs associated with the given element.
 139  */
 140 class HTMLOutputIterator : public AccIterable {
 141  public:
 142   HTMLOutputIterator(DocAccessible* aDocument, nsIContent* aElement);
 143   virtual ~HTMLOutputIterator() {}
 144
 145   /**
 146    * Return next output accessible associated with the given element.
 147    */
 148   virtual LocalAccessible* Next() override;
 149
 150  private:
 151   HTMLOutputIterator();
 152   HTMLOutputIterator(const HTMLOutputIterator&);
 153   HTMLOutputIterator& operator=(const HTMLOutputIterator&);
 154
 155   RelatedAccIterator mRelIter;
 156 };
 157
 158 /**
 159  * Used to iterate through XUL labels associated with the given element.
 160  */
 161 class XULLabelIterator : public AccIterable {
 162  public:
 163   XULLabelIterator(DocAccessible* aDocument, nsIContent* aElement);
 164   virtual ~XULLabelIterator() {}
 165
 166   /**
 167    * Return next label accessible associated with the given element.
 168    */
 169   virtual LocalAccessible* Next() override;
 170
 171  private:
 172   XULLabelIterator();
 173   XULLabelIterator(const XULLabelIterator&);
 174   XULLabelIterator& operator=(const XULLabelIterator&);
 175
 176   RelatedAccIterator mRelIter;
 177 };
 178
 179 /**
 180  * Used to iterate through XUL descriptions associated with the given element.
 181  */
 182 class XULDescriptionIterator : public AccIterable {
 183  public:
 184   XULDescriptionIterator(DocAccessible* aDocument, nsIContent* aElement);
 185   virtual ~XULDescriptionIterator() {}
 186
 187   /**
 188    * Return next description accessible associated with the given element.
 189    */
 190   virtual LocalAccessible* Next() override;
 191
 192  private:
 193   XULDescriptionIterator();
 194   XULDescriptionIterator(const XULDescriptionIterator&);
 195   XULDescriptionIterator& operator=(const XULDescriptionIterator&);
 196
 197   RelatedAccIterator mRelIter;
 198 };
 199
 200 /**
 201  * Used to iterate through IDs, elements or accessibles pointed by IDRefs
 202  * attribute. Note, any method used to iterate through IDs, elements, or
 203  * accessibles moves iterator to next position.
 204  */
 205 class IDRefsIterator : public AccIterable {
 206  public:
 207   IDRefsIterator(DocAccessible* aDoc, nsIContent* aContent,
 208                  nsAtom* aIDRefsAttr);
 209   virtual ~IDRefsIterator() {}
 210
 211   /**
 212    * Return next ID.
 213    */
 214   const nsDependentSubstring NextID();
 215
 216   /**
 217    * Return next element.
 218    */
 219   nsIContent* NextElem();
 220
 221   /**
 222    * Return the element with the given ID.
 223    */
 224   static dom::Element* GetElem(nsIContent* aContent, const nsAString& aID);
 225   dom::Element* GetElem(const nsDependentSubstring& aID);
 226
 227   // AccIterable
 228   virtual LocalAccessible* Next() override;
 229
 230  private:
 231   IDRefsIterator();
 232   IDRefsIterator(const IDRefsIterator&);
 233   IDRefsIterator operator=(const IDRefsIterator&);
 234
 235   nsString mIDs;
 236   nsIContent* mContent;
 237   DocAccessible* mDoc;
 238   nsAString::index_type mCurrIdx;
 239 };
 240
 241 /**
 242  * Iterator that points to a single accessible returning it on the first call
 243  * to Next().
 244  */
 245 class SingleAccIterator : public AccIterable {
 246  public:
 247   explicit SingleAccIterator(Accessible* aTarget) : mAcc(aTarget) {}
 248   virtual ~SingleAccIterator() {}
 249
 250   virtual Accessible* Next() override;
 251
 252  private:
 253   SingleAccIterator();
 254   SingleAccIterator(const SingleAccIterator&);
 255   SingleAccIterator& operator=(const SingleAccIterator&);
 256
 257   Accessible* mAcc;
 258 };
 259
 260 /**
 261  * Used to iterate items of the given item container.
 262  */
 263 class ItemIterator : public AccIterable {
 264  public:
 265   explicit ItemIterator(const Accessible* aItemContainer)
 266       : mContainer(aItemContainer), mAnchor(nullptr) {}
 267
 268   virtual Accessible* Next() override;
 269
 270  private:
 271   ItemIterator() = delete;
 272   ItemIterator(const ItemIterator&) = delete;
 273   ItemIterator& operator=(const ItemIterator&) = delete;
 274
 275   const Accessible* mContainer;
 276   Accessible* mAnchor;
 277 };
 278
 279 /**
 280  * Used to iterate through XUL tree items of the same level.
 281  */
 282 class XULTreeItemIterator : public AccIterable {
 283  public:
 284   XULTreeItemIterator(const XULTreeAccessible* aXULTree, nsITreeView* aTreeView,
 285                       int32_t aRowIdx);
 286   virtual ~XULTreeItemIterator() {}
 287
 288   virtual LocalAccessible* Next() override;
 289
 290  private:
 291   XULTreeItemIterator() = delete;
 292   XULTreeItemIterator(const XULTreeItemIterator&) = delete;
 293   XULTreeItemIterator& operator=(const XULTreeItemIterator&) = delete;
 294
 295   const XULTreeAccessible* mXULTree;
 296   nsITreeView* mTreeView;
 297   int32_t mRowCount;
 298   int32_t mContainerLevel;
 299   int32_t mCurrRowIdx;
 300 };
 301
 302 /**
 303  * Used to iterate through a sequence of RemoteAccessibles supplied as an array
 304  * of ids. Such id arrays are included in the RemoteAccessible cache.
 305  */
 306 class RemoteAccIterator : public AccIterable {
 307  public:
 308   /**
 309    * Construct with a reference to an array owned somewhere else; e.g. a
 310    * RemoteAccessible cache.
 311    */
 312   RemoteAccIterator(const nsTArray<uint64_t>& aIds, DocAccessibleParent* aDoc)
 313       : mIds(aIds), mDoc(aDoc), mIndex(0) {}
 314
 315   virtual ~RemoteAccIterator() = default;
 316
 317   virtual Accessible* Next() override;
 318
 319  private:
 320   const nsTArray<uint64_t>& mIds;
 321   DocAccessibleParent* mDoc;
 322   uint32_t mIndex;
 323 };
 324
 325 }  // namespace a11y
 326 }  // namespace mozilla
 327
 328 #endif