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. This is typically used to query
  71  * implicit reverse relations; e.g. calculating the LABEL_FOR relation for a
  72  * label where that label was referenced using aria-labelledby.
  73  */
  74 class RelatedAccIterator : public AccIterable {
  75  public:
  76   /**
  77    * Constructor.
  78    *
  79    * @param aDocument         [in] the document accessible the related
  80    * &                         accessibles belong to.
  81    * @param aDependentContent [in] the content of dependent accessible that
  82    *                           relations were requested for
  83    * @param aRelAttr          [in] relation attribute that relations are
  84    *                           pointed by, null for all relations
  85    */
  86   RelatedAccIterator(DocAccessible* aDocument, nsIContent* aDependentContent,
  87                      nsAtom* aRelAttr);
  88
  89   virtual ~RelatedAccIterator() {}
  90
  91   /**
  92    * Return next related accessible for the given dependent accessible.
  93    */
  94   virtual LocalAccessible* Next() override;
  95
  96  private:
  97   RelatedAccIterator();
  98   RelatedAccIterator(const RelatedAccIterator&);
  99   RelatedAccIterator& operator=(const RelatedAccIterator&);
 100
 101   DocAccessible* mDocument;
 102   nsIContent* mDependentContent;
 103   nsAtom* mRelAttr;
 104   DocAccessible::AttrRelProviders* mProviders;
 105   uint32_t mIndex;
 106   bool mIsWalkingDependentElements;
 107 };
 108
 109 /**
 110  * Used to iterate through HTML labels associated with the given accessible.
 111  */
 112 class HTMLLabelIterator : public AccIterable {
 113  public:
 114   enum LabelFilter { eAllLabels, eSkipAncestorLabel };
 115
 116   HTMLLabelIterator(DocAccessible* aDocument,
 117                     const LocalAccessible* aAccessible,
 118                     LabelFilter aFilter = eAllLabels);
 119
 120   virtual ~HTMLLabelIterator() {}
 121
 122   /**
 123    * Return next label accessible associated with the given element.
 124    */
 125   virtual LocalAccessible* Next() override;
 126
 127  private:
 128   HTMLLabelIterator();
 129   HTMLLabelIterator(const HTMLLabelIterator&);
 130   HTMLLabelIterator& operator=(const HTMLLabelIterator&);
 131
 132   bool IsLabel(LocalAccessible* aLabel);
 133
 134   RelatedAccIterator mRelIter;
 135   // XXX: replace it on weak reference (bug 678429), it's safe to use raw
 136   // pointer now because iterators life cycle is short.
 137   const LocalAccessible* mAcc;
 138   LabelFilter mLabelFilter;
 139 };
 140
 141 /**
 142  * Used to iterate through HTML outputs associated with the given element.
 143  */
 144 class HTMLOutputIterator : public AccIterable {
 145  public:
 146   HTMLOutputIterator(DocAccessible* aDocument, nsIContent* aElement);
 147   virtual ~HTMLOutputIterator() {}
 148
 149   /**
 150    * Return next output accessible associated with the given element.
 151    */
 152   virtual LocalAccessible* Next() override;
 153
 154  private:
 155   HTMLOutputIterator();
 156   HTMLOutputIterator(const HTMLOutputIterator&);
 157   HTMLOutputIterator& operator=(const HTMLOutputIterator&);
 158
 159   RelatedAccIterator mRelIter;
 160 };
 161
 162 /**
 163  * Used to iterate through XUL labels associated with the given element.
 164  */
 165 class XULLabelIterator : public AccIterable {
 166  public:
 167   XULLabelIterator(DocAccessible* aDocument, nsIContent* aElement);
 168   virtual ~XULLabelIterator() {}
 169
 170   /**
 171    * Return next label accessible associated with the given element.
 172    */
 173   virtual LocalAccessible* Next() override;
 174
 175  private:
 176   XULLabelIterator();
 177   XULLabelIterator(const XULLabelIterator&);
 178   XULLabelIterator& operator=(const XULLabelIterator&);
 179
 180   RelatedAccIterator mRelIter;
 181 };
 182
 183 /**
 184  * Used to iterate through XUL descriptions associated with the given element.
 185  */
 186 class XULDescriptionIterator : public AccIterable {
 187  public:
 188   XULDescriptionIterator(DocAccessible* aDocument, nsIContent* aElement);
 189   virtual ~XULDescriptionIterator() {}
 190
 191   /**
 192    * Return next description accessible associated with the given element.
 193    */
 194   virtual LocalAccessible* Next() override;
 195
 196  private:
 197   XULDescriptionIterator();
 198   XULDescriptionIterator(const XULDescriptionIterator&);
 199   XULDescriptionIterator& operator=(const XULDescriptionIterator&);
 200
 201   RelatedAccIterator mRelIter;
 202 };
 203
 204 /**
 205  * Used to iterate through IDs, elements or accessibles pointed by IDRefs
 206  * attribute. Note, any method used to iterate through IDs, elements, or
 207  * accessibles moves iterator to next position.
 208  */
 209 class IDRefsIterator : public AccIterable {
 210  public:
 211   IDRefsIterator(DocAccessible* aDoc, nsIContent* aContent,
 212                  nsAtom* aIDRefsAttr);
 213   virtual ~IDRefsIterator() {}
 214
 215   /**
 216    * Return next ID.
 217    */
 218   const nsDependentSubstring NextID();
 219
 220   /**
 221    * Return next element.
 222    */
 223   nsIContent* NextElem();
 224
 225   /**
 226    * Return the element with the given ID.
 227    */
 228   static dom::Element* GetElem(nsIContent* aContent, const nsAString& aID);
 229   dom::Element* GetElem(const nsDependentSubstring& aID);
 230
 231   // AccIterable
 232   virtual LocalAccessible* Next() override;
 233
 234  private:
 235   IDRefsIterator();
 236   IDRefsIterator(const IDRefsIterator&);
 237   IDRefsIterator operator=(const IDRefsIterator&);
 238
 239   nsString mIDs;
 240   nsIContent* mContent;
 241   DocAccessible* mDoc;
 242   nsAString::index_type mCurrIdx;
 243 };
 244
 245 /**
 246  * Iterator that points to a single accessible returning it on the first call
 247  * to Next().
 248  */
 249 class SingleAccIterator : public AccIterable {
 250  public:
 251   explicit SingleAccIterator(Accessible* aTarget) : mAcc(aTarget) {}
 252   virtual ~SingleAccIterator() {}
 253
 254   virtual Accessible* Next() override;
 255
 256  private:
 257   SingleAccIterator();
 258   SingleAccIterator(const SingleAccIterator&);
 259   SingleAccIterator& operator=(const SingleAccIterator&);
 260
 261   Accessible* mAcc;
 262 };
 263
 264 /**
 265  * Used to iterate items of the given item container.
 266  */
 267 class ItemIterator : public AccIterable {
 268  public:
 269   explicit ItemIterator(const Accessible* aItemContainer)
 270       : mContainer(aItemContainer), mAnchor(nullptr) {}
 271
 272   virtual Accessible* Next() override;
 273
 274  private:
 275   ItemIterator() = delete;
 276   ItemIterator(const ItemIterator&) = delete;
 277   ItemIterator& operator=(const ItemIterator&) = delete;
 278
 279   const Accessible* mContainer;
 280   Accessible* mAnchor;
 281 };
 282
 283 /**
 284  * Used to iterate through XUL tree items of the same level.
 285  */
 286 class XULTreeItemIterator : public AccIterable {
 287  public:
 288   XULTreeItemIterator(const XULTreeAccessible* aXULTree, nsITreeView* aTreeView,
 289                       int32_t aRowIdx);
 290   virtual ~XULTreeItemIterator() {}
 291
 292   virtual LocalAccessible* Next() override;
 293
 294  private:
 295   XULTreeItemIterator() = delete;
 296   XULTreeItemIterator(const XULTreeItemIterator&) = delete;
 297   XULTreeItemIterator& operator=(const XULTreeItemIterator&) = delete;
 298
 299   const XULTreeAccessible* mXULTree;
 300   nsITreeView* mTreeView;
 301   int32_t mRowCount;
 302   int32_t mContainerLevel;
 303   int32_t mCurrRowIdx;
 304 };
 305
 306 /**
 307  * Used to iterate through a sequence of RemoteAccessibles supplied as an array
 308  * of ids. Such id arrays are included in the RemoteAccessible cache.
 309  */
 310 class RemoteAccIterator : public AccIterable {
 311  public:
 312   /**
 313    * Construct with a reference to an array owned somewhere else; e.g. a
 314    * RemoteAccessible cache.
 315    */
 316   RemoteAccIterator(const nsTArray<uint64_t>& aIds, DocAccessibleParent* aDoc)
 317       : mIds(aIds), mDoc(aDoc), mIndex(0) {}
 318
 319   virtual ~RemoteAccIterator() = default;
 320
 321   virtual Accessible* Next() override;
 322
 323  private:
 324   const nsTArray<uint64_t>& mIds;
 325   DocAccessibleParent* mDoc;
 326   uint32_t mIndex;
 327 };
 328
 329 }  // namespace a11y
 330 }  // namespace mozilla
 331
 332 #endif