Flutter iOS Embedder
SemanticsObject.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter 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 FLUTTER_SHELL_PLATFORM_DARWIN_IOS_FRAMEWORK_SOURCE_SEMANTICSOBJECT_H_
6 #define FLUTTER_SHELL_PLATFORM_DARWIN_IOS_FRAMEWORK_SOURCE_SEMANTICSOBJECT_H_
7 
8 #import <UIKit/UIKit.h>
9 
10 #include "flutter/fml/macros.h"
11 #include "flutter/fml/memory/weak_ptr.h"
12 #include "flutter/lib/ui/semantics/semantics_node.h"
15 
17 
18 constexpr int32_t kRootNodeId = 0;
19 // This can be arbitrary number as long as it is bigger than 0.
20 constexpr float kScrollExtentMaxForInf = 1000;
21 
25 
26 /**
27  * A node in the iOS semantics tree. This object is a wrapper over a native accessibiliy
28  * object, which is stored in the property `nativeAccessibility`. In the most case, the
29  * `nativeAccessibility` directly returns this object. Some subclasses such as the
30  * `FlutterScrollableSemanticsObject` creates a native `UIScrollView` as its `nativeAccessibility`
31  * so that it can interact with iOS.
32  */
33 @interface SemanticsObject : UIAccessibilityElement
34 
35 /**
36  * The globally unique identifier for this node.
37  */
38 @property(nonatomic, readonly) int32_t uid;
39 
40 /**
41  * The parent of this node in the node tree. Will be nil for the root node and
42  * during transient state changes.
43  */
44 @property(nonatomic, weak, readonly, nullable) SemanticsObject* parent;
45 
46 /**
47  * The semantics node used to produce this semantics object.
48  */
49 @property(nonatomic, readonly) flutter::SemanticsNode node;
50 
51 /**
52  * Whether this semantics object has child semantics objects.
53  */
54 @property(nonatomic, readonly) BOOL hasChildren;
55 
56 /**
57  * Direct children of this semantics object. Each child's `parent` property must
58  * be equal to this object.
59  */
60 @property(nonatomic, copy) NSArray<SemanticsObject*>* children;
61 
62 /**
63  * Direct children of this semantics object in hit test order. Each child's `parent` property
64  * must be equal to this object.
65  */
66 @property(nonatomic, copy, nullable) NSArray<SemanticsObject*>* childrenInHitTestOrder;
67 
68 /**
69  * The UIAccessibility that represents this object.
70  *
71  * By default, this return self. Subclasses can override to return different
72  * objects to represent them. For example, FlutterScrollableSemanticsObject[s]
73  * maintain UIScrollView[s] to represent their UIAccessibility[s].
74  */
75 @property(nonatomic, readonly) id nativeAccessibility;
76 
77 /**
78  * Due to the fact that VoiceOver may hold onto SemanticObjects even after it shuts down,
79  * there can be situations where the AccessibilityBridge is shutdown, but the SemanticObject
80  * will still be alive. If VoiceOver is turned on again, it may try to access this orphaned
81  * SemanticObject. Methods that are called from the accessibility framework should use
82  * `bridge` (or `bridgeView`) to guard against this case by just returning early if its bridge
83  * has been shutdown.
84  *
85  * See https://github.com/flutter/flutter/issues/43795 for more information.
86  *
87  * Returns a raw pointer to the AccessibilityBridge if it is still alive, or nullptr if destroyed.
88  */
89 - (nullable flutter::AccessibilityBridgeIos*)bridge;
90 
91 /**
92  * Returns the underlying UIView from the bridge if alive, or nil if destroyed.
93  */
94 - (nullable UIView*)bridgeView;
95 
96 /**
97  * Updates this semantics object using data from the `node` argument.
98  */
99 - (void)setSemanticsNode:(const flutter::SemanticsNode*)node NS_REQUIRES_SUPER;
100 
101 - (void)replaceChildAtIndex:(NSInteger)index withChild:(SemanticsObject*)child;
102 
103 - (BOOL)nodeWillCauseLayoutChange:(const flutter::SemanticsNode*)node;
104 
105 - (BOOL)nodeWillCauseScroll:(const flutter::SemanticsNode*)node;
106 
107 - (BOOL)nodeShouldTriggerAnnouncement:(nullable const flutter::SemanticsNode*)node;
108 
109 - (void)collectRoutes:(NSMutableArray<SemanticsObject*>*)edges;
110 
111 - (nullable NSString*)routeName;
112 
113 - (BOOL)onCustomAccessibilityAction:(FlutterCustomAccessibilityAction*)action;
114 
115 /**
116  * Called after accessibility bridge finishes a semantics update.
117  *
118  * Subclasses can override this method if they contain states that can only be
119  * updated once every node in the accessibility tree has finished updating.
120  */
122 
123 /**
124  * Called when the root view associated with this node's accessibility bridge changes.
125  *
126  * Subclasses can override this method if they own native UIKit views that must
127  * remain attached to the current Flutter view.
128  */
130 
131 #pragma mark - Designated initializers
132 
133 - (instancetype)init __attribute__((unavailable("Use initWithBridge instead")));
134 - (instancetype)initWithBridge:(fml::WeakPtr<flutter::AccessibilityBridgeIos>)bridge
135  uid:(int32_t)uid NS_DESIGNATED_INITIALIZER;
136 
137 @end
138 
139 /**
140  * An implementation of UIAccessibilityCustomAction which also contains the
141  * Flutter uid.
142  */
143 @interface FlutterCustomAccessibilityAction : UIAccessibilityCustomAction
144 
145 /**
146  * The uid of the action defined by the flutter application.
147  */
148 @property(nonatomic) int32_t uid;
149 
150 @end
151 
152 /**
153  * The default implementation of `SemanticsObject` for most accessibility elements
154  * in the iOS accessibility tree.
155  *
156  * Use this implementation for nodes that do not need to be expressed via UIKit-specific
157  * protocols (it only implements NSObject).
158  *
159  * See also:
160  * * TextInputSemanticsObject, which implements `UITextInput` protocol to expose
161  * editable text widgets to a11y.
162  */
164 @end
165 
166 /**
167  * Designated to act as an accessibility container of a platform view.
168  *
169  * This object does not take any accessibility actions on its own, nor has any accessibility
170  * label/value/trait/hint... on its own. The accessibility data will be handled by the platform
171  * view.
172  *
173  * See also:
174  * * `SemanticsObject` for the other type of semantics objects.
175  * * `FlutterSemanticsObject` for default implementation of `SemanticsObject`.
176  */
178 
179 - (instancetype)initWithBridge:(fml::WeakPtr<flutter::AccessibilityBridgeIos>)bridge
180  uid:(int32_t)uid NS_UNAVAILABLE;
181 
182 - (instancetype)initWithBridge:(fml::WeakPtr<flutter::AccessibilityBridgeIos>)bridge
183  uid:(int32_t)uid
184  platformView:(FlutterTouchInterceptingView*)platformView
185  NS_DESIGNATED_INITIALIZER;
186 
187 @end
188 
189 /// The semantics object for switch buttons. This class creates an UISwitch to interact with the
190 /// iOS.
192 
193 @end
194 
195 /// The semantics object for scrollable. This class creates an UIScrollView to interact with the
196 /// iOS.
198 @property(nonatomic, readonly) FlutterSemanticsScrollView* scrollView;
199 @end
200 
201 /**
202  * Represents a semantics object that has children and hence has to be presented to the OS as a
203  * UIAccessibilityContainer.
204  *
205  * The SemanticsObject class cannot implement the UIAccessibilityContainer protocol because an
206  * object that returns YES for isAccessibilityElement cannot also implement
207  * UIAccessibilityContainer.
208  *
209  * With the help of SemanticsObjectContainer, the hierarchy of semantic objects received from
210  * the framework, such as:
211  *
212  * SemanticsObject1
213  * SemanticsObject2
214  * SemanticsObject3
215  * SemanticsObject4
216  *
217  * is translated into the following hierarchy, which is understood by iOS:
218  *
219  * SemanticsObjectContainer1
220  * SemanticsObject1
221  * SemanticsObjectContainer2
222  * SemanticsObject2
223  * SemanticsObject3
224  * SemanticsObject4
225  *
226  * From Flutter's view of the world (the first tree seen above), we construct iOS's view of the
227  * world (second tree) as follows: We replace each SemanticsObjects that has children with a
228  * SemanticsObjectContainer, which has the original SemanticsObject and its children as children.
229  *
230  * SemanticsObjects have semantic information attached to them which is interpreted by
231  * VoiceOver (they return YES for isAccessibilityElement). The SemanticsObjectContainers are just
232  * there for structure and they don't provide any semantic information to VoiceOver (they return
233  * NO for isAccessibilityElement).
234  */
235 @interface SemanticsObjectContainer : UIAccessibilityElement
236 - (instancetype)init NS_UNAVAILABLE;
237 + (instancetype)new NS_UNAVAILABLE;
238 - (instancetype)initWithAccessibilityContainer:(id)container NS_UNAVAILABLE;
239 - (instancetype)initWithSemanticsObject:(SemanticsObject*)semanticsObject NS_DESIGNATED_INITIALIZER;
240 
241 @property(nonatomic, weak, nullable) SemanticsObject* semanticsObject;
242 
243 @end
244 
246 
247 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_IOS_FRAMEWORK_SOURCE_SEMANTICSOBJECT_H_
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
instancetype init NS_UNAVAILABLE
constexpr NS_ASSUME_NONNULL_BEGIN int32_t kRootNodeId
constexpr float kScrollExtentMaxForInf
SemanticsObject * semanticsObject
void accessibilityBridgeDidChangeView()
NSArray< SemanticsObject * > * children
SemanticsObject * parent
nullable UIView * bridgeView()
NSArray< SemanticsObject * > * childrenInHitTestOrder
(unavailable("Use initWithBridge instead" __attribute__()
void accessibilityBridgeDidFinishUpdate()
nullable NSString * routeName()
flutter::SemanticsNode node