// Copyright (c) 2012 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 CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_
#define CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_
#include <map>
#include <utility>
#include <vector>
#include "base/basictypes.h"
#include "base/strings/string16.h"
#include "build/build_config.h"
#include "content/common/content_export.h"
#include "third_party/WebKit/public/web/WebAXEnums.h"
#include "ui/accessibility/ax_node_data.h"
#if defined(OS_MACOSX) && __OBJC__
@class BrowserAccessibilityCocoa;
#endif
namespace content {
class BrowserAccessibilityManager;
#if defined(OS_WIN)
class BrowserAccessibilityWin;
#elif defined(TOOLKIT_GTK)
class BrowserAccessibilityGtk;
#endif
////////////////////////////////////////////////////////////////////////////////
//
// BrowserAccessibility
//
// Class implementing the cross platform interface for the Browser-Renderer
// communication of accessibility information, providing accessibility
// to be used by screen readers and other assistive technology (AT).
//
// An implementation for each platform handles platform specific accessibility
// APIs.
//
////////////////////////////////////////////////////////////////////////////////
class CONTENT_EXPORT BrowserAccessibility {
public:
// Creates a platform specific BrowserAccessibility. Ownership passes to the
// caller.
static BrowserAccessibility* Create();
virtual ~BrowserAccessibility();
// Detach all descendants of this subtree and push all of the node pointers,
// including this node, onto the end of |nodes|.
virtual void DetachTree(std::vector<BrowserAccessibility*>* nodes);
// Perform platform-specific initialization. This can be called multiple times
// during the lifetime of this instance after the members of this base object
// have been reset with new values from the renderer process.
// Child dependent initialization can be done here.
virtual void PostInitialize() {}
// Returns true if this is a native platform-specific object, vs a
// cross-platform generic object.
virtual bool IsNative() const;
// Initialize the tree structure of this object.
void InitializeTreeStructure(
BrowserAccessibilityManager* manager,
BrowserAccessibility* parent,
int32 renderer_id,
int32 index_in_parent);
// Initialize this object's data.
void InitializeData(const ui::AXNodeData& src);
virtual void SwapChildren(std::vector<BrowserAccessibility*>& children);
// Update the parent and index in parent if this node has been moved.
void UpdateParent(BrowserAccessibility* parent, int index_in_parent);
// Update this node's location, leaving everything else the same.
virtual void SetLocation(const gfx::Rect& new_location);
// Return true if this object is equal to or a descendant of |ancestor|.
bool IsDescendantOf(BrowserAccessibility* ancestor);
// Returns the parent of this object, or NULL if it's the root.
BrowserAccessibility* parent() const { return parent_; }
// Returns the number of children of this object.
uint32 child_count() const { return children_.size(); }
// Returns true if this is a leaf node on this platform, meaning any
// children should not be exposed to this platform's native accessibility
// layer. Each platform subclass should implement this itself.
// The definition of a leaf may vary depending on the platform,
// but a leaf node should never have children that are focusable or
// that might send notifications.
virtual bool PlatformIsLeaf() const;
// Returns the number of children of this object, or 0 if PlatformIsLeaf()
// returns true.
uint32 PlatformChildCount() const;
// Return a pointer to the child at the given index, or NULL for an
// invalid index. Returns NULL if PlatformIsLeaf() returns true.
BrowserAccessibility* PlatformGetChild(uint32 child_index) const;
// Return the previous sibling of this object, or NULL if it's the first
// child of its parent.
BrowserAccessibility* GetPreviousSibling();
// Return the next sibling of this object, or NULL if it's the last child
// of its parent.
BrowserAccessibility* GetNextSibling();
// Returns the bounds of this object in coordinates relative to the
// top-left corner of the overall web area.
gfx::Rect GetLocalBoundsRect() const;
// Returns the bounds of this object in screen coordinates.
gfx::Rect GetGlobalBoundsRect() const;
// Returns the bounds of the given range in coordinates relative to the
// top-left corner of the overall web area. Only valid when the
// role is WebAXRoleStaticText.
gfx::Rect GetLocalBoundsForRange(int start, int len) const;
// Same as GetLocalBoundsForRange, in screen coordinates. Only valid when
// the role is WebAXRoleStaticText.
gfx::Rect GetGlobalBoundsForRange(int start, int len) const;
// Returns the deepest descendant that contains the specified point
// (in global screen coordinates).
BrowserAccessibility* BrowserAccessibilityForPoint(const gfx::Point& point);
// Marks this object for deletion, releases our reference to it, and
// recursively calls Destroy() on its children. May not delete
// immediately due to reference counting.
//
// Reference counting is used on some platforms because the
// operating system may hold onto a reference to a BrowserAccessibility
// object even after we're through with it. When a BrowserAccessibility
// has had Destroy() called but its reference count is not yet zero,
// queries on this object return failure
virtual void Destroy();
// Subclasses should override this to support platform reference counting.
virtual void NativeAddReference() { }
// Subclasses should override this to support platform reference counting.
virtual void NativeReleaseReference();
//
// Accessors
//
const std::vector<BrowserAccessibility*>& children() const {
return children_;
}
const std::vector<std::pair<std::string, std::string> >&
html_attributes() const {
return html_attributes_;
}
int32 index_in_parent() const { return index_in_parent_; }
gfx::Rect location() const { return location_; }
BrowserAccessibilityManager* manager() const { return manager_; }
const std::string& name() const { return name_; }
const std::string& value() const { return value_; }
int32 renderer_id() const { return renderer_id_; }
int32 role() const { return role_; }
int32 state() const { return state_; }
bool instance_active() const { return instance_active_; }
void set_name(const std::string& name) { name_ = name; }
void set_value(const std::string& value) { value_ = value; }
#if defined(OS_MACOSX) && __OBJC__
BrowserAccessibilityCocoa* ToBrowserAccessibilityCocoa();
#elif defined(OS_WIN)
BrowserAccessibilityWin* ToBrowserAccessibilityWin();
#elif defined(TOOLKIT_GTK)
BrowserAccessibilityGtk* ToBrowserAccessibilityGtk();
#endif
// Accessing accessibility attributes:
//
// There are dozens of possible attributes for an accessibility node,
// but only a few tend to apply to any one object, so we store them
// in sparse arrays of <attribute id, attribute value> pairs, organized
// by type (bool, int, float, string, int list).
//
// There are three accessors for each type of attribute: one that returns
// true if the attribute is present and false if not, one that takes a
// pointer argument and returns true if the attribute is present (if you
// need to distinguish between the default value and a missing attribute),
// and another that returns the default value for that type if the
// attribute is not present. In addition, strings can be returned as
// either std::string or base::string16, for convenience.
bool HasBoolAttribute(ui::AXBoolAttribute attr) const;
bool GetBoolAttribute(ui::AXBoolAttribute attr) const;
bool GetBoolAttribute(ui::AXBoolAttribute attr, bool* value) const;
bool HasFloatAttribute(ui::AXFloatAttribute attr) const;
float GetFloatAttribute(ui::AXFloatAttribute attr) const;
bool GetFloatAttribute(ui::AXFloatAttribute attr, float* value) const;
bool HasIntAttribute(ui::AXIntAttribute attribute) const;
int GetIntAttribute(ui::AXIntAttribute attribute) const;
bool GetIntAttribute(ui::AXIntAttribute attribute, int* value) const;
bool HasStringAttribute(
ui::AXStringAttribute attribute) const;
const std::string& GetStringAttribute(ui::AXStringAttribute attribute) const;
bool GetStringAttribute(ui::AXStringAttribute attribute,
std::string* value) const;
bool GetString16Attribute(ui::AXStringAttribute attribute,
base::string16* value) const;
base::string16 GetString16Attribute(
ui::AXStringAttribute attribute) const;
bool HasIntListAttribute(ui::AXIntListAttribute attribute) const;
const std::vector<int32>& GetIntListAttribute(
ui::AXIntListAttribute attribute) const;
bool GetIntListAttribute(ui::AXIntListAttribute attribute,
std::vector<int32>* value) const;
void SetStringAttribute(ui::AXStringAttribute attribute,
const std::string& value);
// Retrieve the value of a html attribute from the attribute map and
// returns true if found.
bool GetHtmlAttribute(const char* attr, base::string16* value) const;
bool GetHtmlAttribute(const char* attr, std::string* value) const;
// Utility method to handle special cases for ARIA booleans, tristates and
// booleans which have a "mixed" state.
//
// Warning: the term "Tristate" is used loosely by the spec and here,
// as some attributes support a 4th state.
//
// The following attributes are appropriate to use with this method:
// aria-selected (selectable)
// aria-grabbed (grabbable)
// aria-expanded (expandable)
// aria-pressed (toggleable/pressable) -- supports 4th "mixed" state
// aria-checked (checkable) -- supports 4th "mixed state"
bool GetAriaTristate(const char* attr_name,
bool* is_defined,
bool* is_mixed) const;
// Returns true if the bit corresponding to the given state enum is 1.
bool HasState(ui::AXState state_enum) const;
// Returns true if this node is an editable text field of any kind.
bool IsEditableText() const;
// Append the text from this node and its children.
std::string GetTextRecursive() const;
protected:
// Perform platform specific initialization. This can be called multiple times
// during the lifetime of this instance after the members of this base object
// have been reset with new values from the renderer process.
// Perform child independent initialization in this method.
virtual void PreInitialize() {}
BrowserAccessibility();
// The manager of this tree of accessibility objects; needed for
// global operations like focus tracking.
BrowserAccessibilityManager* manager_;
// The parent of this object, may be NULL if we're the root object.
BrowserAccessibility* parent_;
private:
// Return the sum of the lengths of all static text descendants,
// including this object if it's static text.
int GetStaticTextLenRecursive() const;
// The index of this within its parent object.
int32 index_in_parent_;
// The ID of this object in the renderer process.
int32 renderer_id_;
// The children of this object.
std::vector<BrowserAccessibility*> children_;
// Accessibility metadata from the renderer
std::string name_;
std::string value_;
std::vector<std::pair<
ui::AXBoolAttribute, bool> > bool_attributes_;
std::vector<std::pair<
ui::AXFloatAttribute, float> > float_attributes_;
std::vector<std::pair<
ui::AXIntAttribute, int> > int_attributes_;
std::vector<std::pair<
ui::AXStringAttribute, std::string> > string_attributes_;
std::vector<std::pair<
ui::AXIntListAttribute, std::vector<int32> > >
intlist_attributes_;
std::vector<std::pair<std::string, std::string> > html_attributes_;
int32 role_;
int32 state_;
gfx::Rect location_;
// BrowserAccessibility objects are reference-counted on some platforms.
// When we're done with this object and it's removed from our accessibility
// tree, a client may still be holding onto a pointer to this object, so
// we mark it as inactive so that calls to any of this object's methods
// immediately return failure.
bool instance_active_;
private:
DISALLOW_COPY_AND_ASSIGN(BrowserAccessibility);
};
} // namespace content
#endif // CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_