Creates AXPosition to uniquely identify a position in the accessibility tree

ui/accessibility/ax_position.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef UI_ACCESSIBILITY_AX_POSITION_H_
+#define UI_ACCESSIBILITY_AX_POSITION_H_
+
+#include <stdint.h>
+
+#include "ui/accessibility/ax_enums.h"
+#include "ui/accessibility/ax_node.h"
+
+namespace ui {
+
+// Defines the type of position in the accessibility tree.
+enum class AXPositionType { NullPosition, TreePosition, TextPosition };

[David Tseng, 2016/10/07 21:02:42]

Please expand a little on these. What exactly is a null position?

+
+// A position in the |AXTree|.
+// It could either indicate a non-textual node in the accessibility tree, or a
+// text node and a character offset.

[David Tseng, 2016/10/07 21:02:41]

What is a text node?

+template <class AXNodeType>
+class AXPosition {
+ public:
+  virtual ~AXPosition();
+
+  static typename AXNodeType::AXPosition* CreateNullPosition();
+  static typename AXNodeType::AXPosition* CreateTreePosition(int tree_id,
+                                                             int32_t anchor_id,
+                                                             int child_index);
+  static typename AXNodeType::AXPosition* CreateTextPosition(int tree_id,
+                                                             int32_t anchor_id,
+                                                             int text_offset);
+
+  int get_tree_id() const { return tree_id_; }

[David Tseng, 2016/10/07 21:02:42]

Remove the get_ here

+  int32_t get_anchor_id() const { return anchor_id_; }

[David Tseng, 2016/10/07 21:02:41]

Remove the get_ here

+  AXNodeType* GetAnchor() const;
+  int get_child_index() const { return child_index_; }
+  int get_text_offset() const { return text_offset_; }

[David Tseng, 2016/10/07 21:02:42]

I think we should re-think the design here.

either:
- don't explicitly include tree vs text positions and simply have one offset
(i.e. yuou could have two methods, IsTextPosition/IsTreePosition which simply
checks the node is/isn't a text node).
- create subclasses AXTextPosition/AXTreePosition.

+  ui::AXTextAffinity get_affinity() const { return affinity_; }
+  void set_affinity(ui::AXTextAffinity affinity) { affinity_ = affinity; }

[David Tseng, 2016/10/07 21:02:42]

I think it would make more sense to make all properties read-only (i.e. set on
construction).

+
+  bool IsNullPosition() const {
+    return type_ == AXPositionType::NullPosition || !GetAnchor();
+  }
+  bool IsTreePosition() const {
+    return GetAnchor() && type_ == AXPositionType::TreePosition;
+  }
+  bool IsTextPosition() const {
+    return GetAnchor() && type_ == AXPositionType::TextPosition;

[David Tseng, 2016/10/07 21:02:42]

So, in theory, I could construct an AXPosition (w char offset) on a non-text
node? I thought that wasn't allowed:
+// It could either indicate a non-textual node in the accessibility tree, or a
+// text node and a character offset.

+  }
+
+  bool AtStartOfAnchor() const;
+  bool AtEndOfAnchor() const;

[David Tseng, 2016/10/07 21:02:41]

In Blink, the position types are:
offsetInAnchor, beforeAnchor, afterAnchor, beforeChildren, afterChildren.

Every time we deviate from what Blink does, it will make it that much harder to
map a position back to the DOM.

+
+  AXPosition* CommonAncestor(const AXPosition& second) const;
+
+  bool operator<(const AXPosition& position) const;

[David Tseng, 2016/10/07 21:02:42]

Please add some comments for all of these and above.

+  bool operator<=(const AXPosition& position) const;
+  bool operator>(const AXPosition& position) const;
+  bool operator>=(const AXPosition& position) const;
+
+  AXPosition* GetPositionAtStartOfAnchor() const;
+  AXPosition* GetPositionAtEndOfAnchor() const;
+
+  // The following methods work across anchors.
+
+  AXPosition* GetNextCharacterPosition() const;
+  AXPosition* GetPreviousCharacterPosition() const;
+  // TODO(nektar): Add word, line and paragraph navigation methods.
+
+ protected:
+  AXPosition(int tree_id,
+             int32_t anchor_id,
+             int child_index,
+             int text_offset,
+             AXPositionType type);
+
+  // Uses depth-first pre-order traversal.

[David Tseng, 2016/10/07 21:02:42]

What does this mean? The next tree or character position?

+  virtual AXPosition* GetNextAnchorPosition() const;
+  // Uses depth-first pre-order traversal.
+  virtual AXPosition* GetPreviousAnchorPosition() const;
+
+  virtual AXPosition* GetChildPositionAt(int child_index) const = 0;

[David Tseng, 2016/10/07 21:02:41]

The more I read this, the more I thnk we should separate into AXTextPosition and
AXTreePosition.

+  virtual AXPosition* GetParentPosition() const = 0;
+  virtual int AnchorChildCount() const = 0;
+  virtual int AnchorIndexInParent() const = 0;
+  virtual AXNodeType* GetNodeInTree(int tree_id, int32_t node_id) const = 0;
+  virtual int MaxTextOffset() const = 0;

[David Tseng, 2016/10/07 21:02:41]

Definitely needs comment.

+
+ private:
+  int tree_id_;
+  int32_t anchor_id_;
+
+  // For text positions, |child_index_| is initially set to |-1| and only
+  // computed on demand. The same with tree positions and |text_offset_|.
+  int child_index_;
+  int text_offset_;
+
+  AXPositionType type_;
+
+  // TODO(nektar): Get rid of affinity and make Blink handle affinity
+  // internally since inline text objects don't span lines.
+  ui::AXTextAffinity affinity_;
+};
+
+template <class AXNodeType>
+bool operator==(const AXPosition<AXNodeType>& first,
+                const AXPosition<AXNodeType>& second);
+template <class AXNodeType>
+bool operator!=(const AXPosition<AXNodeType>& first,
+                const AXPosition<AXNodeType>& second);
+
+class AX_EXPORT AXNodePosition : public AXPosition<AXNode> {
+ public:
+  ~AXNodePosition() override;
+
+ protected:
+  AXNodePosition(int tree_id,
+                 int32_t anchor_id,
+                 int child_index,
+                 int text_offset,
+                 AXPositionType type);
+
+  int AnchorChildCount() const override {
+    return GetAnchor() ? GetAnchor()->child_count() : -1;
+  }
+  AXPosition* GetChildPositionAt(int child_index) const override;
+  AXPosition* GetParentPosition() const override;
+  int AnchorIndexInParent() const override {
+    return GetAnchor() ? GetAnchor()->index_in_parent() : -1;
+  }
+};
+
+}  // namespace ui
+
+#endif  // UI_ACCESSIBILITY_AX_POSITION_H_