1 // Copyright 2013 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef UI_ACCESSIBILITY_AX_NODE_DATA_H_
6 #define UI_ACCESSIBILITY_AX_NODE_DATA_H_
7 
8 #include <stdint.h>
9 
10 #include <map>
11 #include <memory>
12 #include <string>
13 #include <vector>
14 
15 #include "base/strings/string16.h"
16 #include "base/strings/string_split.h"
17 #include "ui/accessibility/ax_base_export.h"
18 #include "ui/accessibility/ax_enums.mojom-forward.h"
19 #include "ui/accessibility/ax_node_text_styles.h"
20 #include "ui/accessibility/ax_relative_bounds.h"
21 #include "ui/gfx/geometry/rect_f.h"
22 
23 namespace ui {
24 
25 // Return true if |attr| should be interpreted as the id of another node
26 // in the same tree.
27 AX_BASE_EXPORT bool IsNodeIdIntAttribute(ax::mojom::IntAttribute attr);
28 
29 // Return true if |attr| should be interpreted as a list of ids of
30 // nodes in the same tree.
31 AX_BASE_EXPORT bool IsNodeIdIntListAttribute(ax::mojom::IntListAttribute attr);
32 
33 // A compact representation of the accessibility information for a
34 // single accessible object, in a form that can be serialized and sent from
35 // one process to another.
36 struct AX_BASE_EXPORT AXNodeData {
37   AXNodeData();
38   virtual ~AXNodeData();
39 
40   AXNodeData(const AXNodeData& other);
41   AXNodeData(AXNodeData&& other);
42   AXNodeData& operator=(AXNodeData other);
43 
44   // Accessing accessibility attributes:
45   //
46   // There are dozens of possible attributes for an accessibility node,
47   // but only a few tend to apply to any one object, so we store them
48   // in sparse arrays of <attribute id, attribute value> pairs, organized
49   // by type (bool, int, float, string, int list).
50   //
51   // There are three accessors for each type of attribute: one that returns
52   // true if the attribute is present and false if not, one that takes a
53   // pointer argument and returns true if the attribute is present (if you
54   // need to distinguish between the default value and a missing attribute),
55   // and another that returns the default value for that type if the
56   // attribute is not present. In addition, strings can be returned as
57   // either std::string or base::string16, for convenience.
58 
59   bool HasBoolAttribute(ax::mojom::BoolAttribute attribute) const;
60   bool GetBoolAttribute(ax::mojom::BoolAttribute attribute) const;
61   bool GetBoolAttribute(ax::mojom::BoolAttribute attribute, bool* value) const;
62 
63   bool HasFloatAttribute(ax::mojom::FloatAttribute attribute) const;
64   float GetFloatAttribute(ax::mojom::FloatAttribute attribute) const;
65   bool GetFloatAttribute(ax::mojom::FloatAttribute attribute,
66                          float* value) const;
67 
68   bool HasIntAttribute(ax::mojom::IntAttribute attribute) const;
69   int GetIntAttribute(ax::mojom::IntAttribute attribute) const;
70   bool GetIntAttribute(ax::mojom::IntAttribute attribute, int* value) const;
71 
72   bool HasStringAttribute(ax::mojom::StringAttribute attribute) const;
73   const std::string& GetStringAttribute(
74       ax::mojom::StringAttribute attribute) const;
75   bool GetStringAttribute(ax::mojom::StringAttribute attribute,
76                           std::string* value) const;
77 
78   bool GetString16Attribute(ax::mojom::StringAttribute attribute,
79                             base::string16* value) const;
80   base::string16 GetString16Attribute(
81       ax::mojom::StringAttribute attribute) const;
82 
83   bool HasIntListAttribute(ax::mojom::IntListAttribute attribute) const;
84   const std::vector<int32_t>& GetIntListAttribute(
85       ax::mojom::IntListAttribute attribute) const;
86   bool GetIntListAttribute(ax::mojom::IntListAttribute attribute,
87                            std::vector<int32_t>* value) const;
88 
89   bool HasStringListAttribute(ax::mojom::StringListAttribute attribute) const;
90   const std::vector<std::string>& GetStringListAttribute(
91       ax::mojom::StringListAttribute attribute) const;
92   bool GetStringListAttribute(ax::mojom::StringListAttribute attribute,
93                               std::vector<std::string>* value) const;
94 
95   bool GetHtmlAttribute(const char* attribute, base::string16* value) const;
96   bool GetHtmlAttribute(const char* attribute, std::string* value) const;
97 
98   //
99   // Setting accessibility attributes.
100   //
101   // Replaces an attribute if present. This is safer than crashing via a DCHECK
102   // or doing nothing, because most likely replacing is what the caller would
103   // have wanted or what existing code already assumes.
104   //
105 
106   void AddStringAttribute(ax::mojom::StringAttribute attribute,
107                           const std::string& value);
108   void AddIntAttribute(ax::mojom::IntAttribute attribute, int32_t value);
109   void AddFloatAttribute(ax::mojom::FloatAttribute attribute, float value);
110   void AddBoolAttribute(ax::mojom::BoolAttribute attribute, bool value);
111   void AddIntListAttribute(ax::mojom::IntListAttribute attribute,
112                            const std::vector<int32_t>& value);
113   void AddStringListAttribute(ax::mojom::StringListAttribute attribute,
114                               const std::vector<std::string>& value);
115 
116   //
117   // Removing accessibility attributes.
118   //
119 
120   void RemoveStringAttribute(ax::mojom::StringAttribute attribute);
121   void RemoveIntAttribute(ax::mojom::IntAttribute attribute);
122   void RemoveFloatAttribute(ax::mojom::FloatAttribute attribute);
123   void RemoveBoolAttribute(ax::mojom::BoolAttribute attribute);
124   void RemoveIntListAttribute(ax::mojom::IntListAttribute attribute);
125   void RemoveStringListAttribute(ax::mojom::StringListAttribute attribute);
126 
127   //
128   // Text styles.
129   //
130   AXNodeTextStyles GetTextStyles() const;
131 
132   //
133   // Convenience functions.
134   //
135 
136   // Adds the name attribute or replaces it if already present.
137   void SetName(const std::string& name);
138   void SetName(const base::string16& name);
139 
140   // Allows nameless objects to pass accessibility checks.
141   void SetNameExplicitlyEmpty();
142 
143   // Adds the description attribute or replaces it if already present.
144   void SetDescription(const std::string& description);
145   void SetDescription(const base::string16& description);
146 
147   // Adds the value attribute or replaces it if already present.
148   void SetValue(const std::string& value);
149   void SetValue(const base::string16& value);
150 
151   // Returns true if the given enum bit is 1.
152   bool HasState(ax::mojom::State state) const;
153   bool HasAction(ax::mojom::Action action) const;
154   bool HasTextStyle(ax::mojom::TextStyle text_style) const;
155   // aria-dropeffect is deprecated in WAI-ARIA 1.1.
156   bool HasDropeffect(ax::mojom::Dropeffect dropeffect) const;
157 
158   // Set or remove bits in the given enum's corresponding bitfield.
159   void AddState(ax::mojom::State state);
160   void RemoveState(ax::mojom::State state);
161   void AddAction(ax::mojom::Action action);
162   void AddTextStyle(ax::mojom::TextStyle text_style);
163   // aria-dropeffect is deprecated in WAI-ARIA 1.1.
164   void AddDropeffect(ax::mojom::Dropeffect dropeffect);
165 
166   // Helper functions to get or set some common int attributes with some
167   // specific enum types. To remove an attribute, set it to None.
168   //
169   // Please keep in alphabetic order.
170   ax::mojom::CheckedState GetCheckedState() const;
171   void SetCheckedState(ax::mojom::CheckedState checked_state);
172   ax::mojom::DefaultActionVerb GetDefaultActionVerb() const;
173   void SetDefaultActionVerb(ax::mojom::DefaultActionVerb default_action_verb);
174   ax::mojom::HasPopup GetHasPopup() const;
175   void SetHasPopup(ax::mojom::HasPopup has_popup);
176   ax::mojom::InvalidState GetInvalidState() const;
177   void SetInvalidState(ax::mojom::InvalidState invalid_state);
178   ax::mojom::NameFrom GetNameFrom() const;
179   void SetNameFrom(ax::mojom::NameFrom name_from);
180   ax::mojom::DescriptionFrom GetDescriptionFrom() const;
181   void SetDescriptionFrom(ax::mojom::DescriptionFrom description_from);
182   ax::mojom::TextPosition GetTextPosition() const;
183   void SetTextPosition(ax::mojom::TextPosition text_position);
184   ax::mojom::Restriction GetRestriction() const;
185   void SetRestriction(ax::mojom::Restriction restriction);
186   ax::mojom::ListStyle GetListStyle() const;
187   void SetListStyle(ax::mojom::ListStyle list_style);
188   ax::mojom::TextDirection GetTextDirection() const;
189   void SetTextDirection(ax::mojom::TextDirection text_direction);
190   ax::mojom::ImageAnnotationStatus GetImageAnnotationStatus() const;
191   void SetImageAnnotationStatus(ax::mojom::ImageAnnotationStatus status);
192 
193   // Helper to determine if the data belongs to a node that can respond to
194   // clicks.
195   bool IsClickable() const;
196 
197   // Helper to determine if the data has the ignored state or ignored role.
198   bool IsIgnored() const;
199 
200   // Helper to determine if the data belongs to a node that is invocable.
201   bool IsInvocable() const;
202 
203   // Helper to determine if the data belongs to a node that is a plain
204   // textfield.
205   bool IsPlainTextField() const;
206 
207   // Helper to determine if |GetRestriction| is either ReadOnly or Disabled.
208   // By default, all nodes that can't be edited are readonly.
209   bool IsReadOnlyOrDisabled() const;
210 
211   // Helper to determine if the data belongs to a node that supports
212   // range-based value.
213   bool IsRangeValueSupported() const;
214 
215   // Helper to determine if the data belongs to a node that supports
216   // expand/collapse.
217   bool SupportsExpandCollapse() const;
218 
219   // Helper to determine if the node is in an active live region.
220   bool IsContainedInActiveLiveRegion() const;
221 
222   // Return a string representation of this data, for debugging.
223   virtual std::string ToString() const;
224 
225   // Return a string representation of |aria-dropeffect| values, for testing
226   // and debugging.
227   // aria-dropeffect is deprecated in WAI-ARIA 1.1.
228   std::string DropeffectBitfieldToString() const;
229 
230   // As much as possible this should behave as a simple, serializable,
231   // copyable struct.
232   int32_t id = -1;
233   ax::mojom::Role role;
234   uint32_t state;
235   uint64_t actions;
236   std::vector<std::pair<ax::mojom::StringAttribute, std::string>>
237       string_attributes;
238   std::vector<std::pair<ax::mojom::IntAttribute, int32_t>> int_attributes;
239   std::vector<std::pair<ax::mojom::FloatAttribute, float>> float_attributes;
240   std::vector<std::pair<ax::mojom::BoolAttribute, bool>> bool_attributes;
241   std::vector<std::pair<ax::mojom::IntListAttribute, std::vector<int32_t>>>
242       intlist_attributes;
243   std::vector<
244       std::pair<ax::mojom::StringListAttribute, std::vector<std::string>>>
245       stringlist_attributes;
246   base::StringPairs html_attributes;
247   std::vector<int32_t> child_ids;
248 
249   AXRelativeBounds relative_bounds;
250 };
251 
252 }  // namespace ui
253 
254 #endif  // UI_ACCESSIBILITY_AX_NODE_DATA_H_
255