Line data    Source code

       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 Accessible;
      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             : {
      27             : public:
      28             :   enum {
      29             :     // used to walk the existing tree of the given node
      30             :     eWalkCache = 1,
      31             :     // used to walk the context tree starting from given node
      32             :     eWalkContextTree = 2 | eWalkCache
      33             :   };
      34             : 
      35             :   /**
      36             :    * Used to navigate and create if needed the accessible children.
      37             :    */
      38             :   explicit TreeWalker(Accessible* 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(Accessible* aContext, nsIContent* aAnchorNode, uint32_t aFlags = eWalkCache);
      49             : 
      50             :   /**
      51             :    * Navigates the accessible children within the anchor node subtree.
      52             :    */
      53             :   TreeWalker(DocAccessible* aDocument, nsIContent* aAnchorNode);
      54             : 
      55             :   ~TreeWalker();
      56             : 
      57             :   /**
      58             :    * Resets the walker state, and sets the given node as an anchor. Returns a
      59             :    * first accessible element within the node including the node itself.
      60             :    */
      61             :   Accessible* Scope(nsIContent* aAnchorNode);
      62             : 
      63             :   /**
      64             :    * Resets the walker state.
      65             :    */
      66           0 :   void Reset()
      67             :   {
      68           0 :     mPhase = eAtStart;
      69           0 :     mStateStack.Clear();
      70           0 :     mARIAOwnsIdx = 0;
      71           0 :   }
      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             :   Accessible* Next();
      86             :   Accessible* Prev();
      87             : 
      88           0 :   Accessible* Context() const { return mContext; }
      89           0 :   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             :   Accessible* 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           0 :   dom::AllChildrenIterator* PushState(nsIContent* aContent,
     110             :                                       bool aStartAtBeginning)
     111             :   {
     112           0 :     return mStateStack.AppendElement(
     113           0 :       dom::AllChildrenIterator(aContent, mChildFilter, aStartAtBeginning));
     114             :   }
     115           0 :   dom::AllChildrenIterator* PrependState(nsIContent* aContent,
     116             :                                          bool aStartAtBeginning)
     117             :   {
     118           0 :     return mStateStack.InsertElementAt(0,
     119           0 :       dom::AllChildrenIterator(aContent, mChildFilter, aStartAtBeginning));
     120             :   }
     121             : 
     122             :   /**
     123             :    * Pop state from stack.
     124             :    */
     125             :   dom::AllChildrenIterator* PopState();
     126             : 
     127             :   DocAccessible* mDoc;
     128             :   Accessible* mContext;
     129             :   nsIContent* mAnchorNode;
     130             : 
     131             :   AutoTArray<dom::AllChildrenIterator, 20> mStateStack;
     132             :   uint32_t mARIAOwnsIdx;
     133             : 
     134             :   int32_t mChildFilter;
     135             :   uint32_t mFlags;
     136             : 
     137             :   enum Phase {
     138             :     eAtStart,
     139             :     eAtDOM,
     140             :     eAtARIAOwns,
     141             :     eAtEnd
     142             :   };
     143             :   Phase mPhase;
     144             : };
     145             : 
     146             : } // namespace a11y
     147             : } // namespace mozilla
     148             : 
     149             : #endif // mozilla_a11y_TreeWalker_h_