accessible/base/TreeWalker.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef mozilla_a11y_TreeWalker_h_
   7 #define mozilla_a11y_TreeWalker_h_
   8
   9 #include "mozilla/Attributes.h"
  10 #include <stdint.h>
  11 #include "mozilla/dom/ChildIterator.h"
  12 #include "nsCOMPtr.h"
  13
  14 class nsIContent;
  15
  16 namespace mozilla {
  17 namespace a11y {
  18
  19 class LocalAccessible;
  20 class DocAccessible;
  21
  22 /**
  23  * This class is used to walk the DOM tree to create accessible tree.
  24  */
  25 class TreeWalker final {
  26  public:
  27   enum {
  28     // used to walk the existing tree of the given node
  29     eWalkCache = 1,
  30     // used to walk the context tree starting from given node
  31     eWalkContextTree = 2 | eWalkCache,
  32     eScoped = 4
  33   };
  34
  35   /**
  36    * Used to navigate and create if needed the accessible children.
  37    */
  38   explicit TreeWalker(LocalAccessible* aContext);
  39
  40   /**
  41    * Used to navigate the accessible children relative to the anchor.
  42    *
  43    * @param aContext [in] container accessible for the given node, used to
  44    *                   define accessible context
  45    * @param aAnchorNode [in] the node the search will be prepared relative to
  46    * @param aFlags   [in] flags (see enum above)
  47    */
  48   TreeWalker(LocalAccessible* aContext, nsIContent* aAnchorNode,
  49              uint32_t aFlags = eWalkCache);
  50
  51   /**
  52    * Navigates the accessible children within the anchor node subtree.
  53    */
  54   TreeWalker(DocAccessible* aDocument, nsIContent* aAnchorNode);
  55
  56   ~TreeWalker();
  57
  58   /**
  59    * Resets the walker state, and sets the given node as an anchor. Returns a
  60    * first accessible element within the node including the node itself.
  61    */
  62   LocalAccessible* Scope(nsIContent* aAnchorNode);
  63
  64   /**
  65    * Resets the walker state.
  66    */
  67   void Reset() {
  68     mPhase = eAtStart;
  69     mStateStack.Clear();
  70     mARIAOwnsIdx = 0;
  71   }
  72
  73   /**
  74    * Sets the walker state to the given child node if it's within the anchor.
  75    */
  76   bool Seek(nsIContent* aChildNode);
  77
  78   /**
  79    * Return the next/prev accessible.
  80    *
  81    * @note Returned accessible is bound to the document, if the accessible is
  82    *       rejected during tree creation then the caller should be unbind it
  83    *       from the document.
  84    */
  85   LocalAccessible* Next();
  86   LocalAccessible* Prev();
  87
  88   LocalAccessible* Context() const { return mContext; }
  89   DocAccessible* Document() const { return mDoc; }
  90
  91  private:
  92   TreeWalker();
  93   TreeWalker(const TreeWalker&);
  94   TreeWalker& operator=(const TreeWalker&);
  95
  96   /**
  97    * Return an accessible for the given node if any.
  98    */
  99   LocalAccessible* AccessibleFor(nsIContent* aNode, uint32_t aFlags,
 100                                  bool* aSkipSubtree);
 101
 102   /**
 103    * Create new state for the given node and push it on top of stack / at bottom
 104    * of stack.
 105    *
 106    * @note State stack is used to navigate up/down the DOM subtree during
 107    *        accessible children search.
 108    */
 109   dom::AllChildrenIterator* PushState(nsIContent* aContent,
 110                                       bool aStartAtBeginning) {
 111     return mStateStack.AppendElement(
 112         dom::AllChildrenIterator(aContent, mChildFilter, aStartAtBeginning));
 113   }
 114   dom::AllChildrenIterator* PrependState(nsIContent* aContent,
 115                                          bool aStartAtBeginning) {
 116     return mStateStack.InsertElementAt(
 117         0, dom::AllChildrenIterator(aContent, mChildFilter, aStartAtBeginning));
 118   }
 119
 120   /**
 121    * Pop state from stack.
 122    */
 123   dom::AllChildrenIterator* PopState();
 124
 125   DocAccessible* mDoc;
 126   LocalAccessible* mContext;
 127   nsIContent* mAnchorNode;
 128
 129   AutoTArray<dom::AllChildrenIterator, 20> mStateStack;
 130   uint32_t mARIAOwnsIdx;
 131
 132   int32_t mChildFilter;
 133   uint32_t mFlags;
 134
 135   enum Phase { eAtStart, eAtDOM, eAtARIAOwns, eAtEnd };
 136   Phase mPhase;
 137 };
 138
 139 }  // namespace a11y
 140 }  // namespace mozilla
 141
 142 #endif  // mozilla_a11y_TreeWalker_h_