1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#ifndef QACCESSIBLE_BASE_H
5#define QACCESSIBLE_BASE_H
6
7#include <QtGui/qtguiglobal.h>
8#if QT_CONFIG(accessibility)
9
10#if 0
11// QAccessible class is handled in qaccessible.h
12#pragma qt_sync_stop_processing
13#endif
14
15#include <QtCore/qobjectdefs.h>
16
17#include <cstring> // memset, memcmp
18
19QT_BEGIN_NAMESPACE
20
21class QAccessibleInterface;
22class QAccessibleEvent;
23class QTextCursor;
24
25class Q_GUI_EXPORT QAccessible
26{
27 Q_GADGET
28public:
29
30 enum Event {
31 SoundPlayed = 0x0001,
32 Alert = 0x0002,
33 ForegroundChanged = 0x0003,
34 MenuStart = 0x0004,
35 MenuEnd = 0x0005,
36 PopupMenuStart = 0x0006,
37 PopupMenuEnd = 0x0007,
38 ContextHelpStart = 0x000C,
39 ContextHelpEnd = 0x000D,
40 DragDropStart = 0x000E,
41 DragDropEnd = 0x000F,
42 DialogStart = 0x0010,
43 DialogEnd = 0x0011,
44 ScrollingStart = 0x0012,
45 ScrollingEnd = 0x0013,
46
47 MenuCommand = 0x0018,
48
49 // Values from IAccessible2
50 ActionChanged = 0x0101,
51 ActiveDescendantChanged = 0x0102,
52 AttributeChanged = 0x0103,
53 DocumentContentChanged = 0x0104,
54 DocumentLoadComplete = 0x0105,
55 DocumentLoadStopped = 0x0106,
56 DocumentReload = 0x0107,
57 HyperlinkEndIndexChanged = 0x0108,
58 HyperlinkNumberOfAnchorsChanged = 0x0109,
59 HyperlinkSelectedLinkChanged = 0x010A,
60 HypertextLinkActivated = 0x010B,
61 HypertextLinkSelected = 0x010C,
62 HyperlinkStartIndexChanged = 0x010D,
63 HypertextChanged = 0x010E,
64 HypertextNLinksChanged = 0x010F,
65 ObjectAttributeChanged = 0x0110,
66 PageChanged = 0x0111,
67 SectionChanged = 0x0112,
68 TableCaptionChanged = 0x0113,
69 TableColumnDescriptionChanged = 0x0114,
70 TableColumnHeaderChanged = 0x0115,
71 TableModelChanged = 0x0116,
72 TableRowDescriptionChanged = 0x0117,
73 TableRowHeaderChanged = 0x0118,
74 TableSummaryChanged = 0x0119,
75 TextAttributeChanged = 0x011A,
76 TextCaretMoved = 0x011B,
77 // TextChanged = 0x011C, is deprecated in IA2, use TextUpdated
78 TextColumnChanged = 0x011D,
79 TextInserted = 0x011E,
80 TextRemoved = 0x011F,
81 TextUpdated = 0x0120,
82 TextSelectionChanged = 0x0121,
83 VisibleDataChanged = 0x0122,
84
85 ObjectCreated = 0x8000,
86 ObjectDestroyed = 0x8001,
87 ObjectShow = 0x8002,
88 ObjectHide = 0x8003,
89 ObjectReorder = 0x8004,
90 Focus = 0x8005,
91 Selection = 0x8006,
92 SelectionAdd = 0x8007,
93 SelectionRemove = 0x8008,
94 SelectionWithin = 0x8009,
95 StateChanged = 0x800A,
96 LocationChanged = 0x800B,
97 NameChanged = 0x800C,
98 DescriptionChanged = 0x800D,
99 ValueChanged = 0x800E,
100 ParentChanged = 0x800F,
101 HelpChanged = 0x80A0,
102 DefaultActionChanged = 0x80B0,
103 AcceleratorChanged = 0x80C0,
104
105 InvalidEvent
106 };
107 Q_ENUM(Event)
108
109 // 64 bit enums seem hard on some platforms (windows...)
110 // which makes using a bit field a sensible alternative
111 struct State {
112 // http://msdn.microsoft.com/en-us/library/ms697270.aspx
113 quint64 disabled : 1; // used to be Unavailable
114 quint64 selected : 1;
115 quint64 focusable : 1;
116 quint64 focused : 1;
117 quint64 pressed : 1;
118 quint64 checkable : 1;
119 quint64 checked : 1;
120 quint64 checkStateMixed : 1; // used to be Mixed
121 quint64 readOnly : 1;
122 quint64 hotTracked : 1;
123 quint64 defaultButton : 1;
124 quint64 expanded : 1;
125 quint64 collapsed : 1;
126 quint64 busy : 1;
127 quint64 expandable : 1;
128 quint64 marqueed : 1;
129 quint64 animated : 1;
130 quint64 invisible : 1;
131 quint64 offscreen : 1;
132 quint64 sizeable : 1;
133 quint64 movable : 1;
134 quint64 selfVoicing : 1;
135 quint64 selectable : 1;
136 quint64 linked : 1;
137 quint64 traversed : 1;
138 quint64 multiSelectable : 1;
139 quint64 extSelectable : 1;
140 quint64 passwordEdit : 1; // used to be Protected
141 quint64 hasPopup : 1;
142 quint64 modal : 1;
143
144 // IA2 - we chose to not add some IA2 states for now
145 // Below the ones that seem helpful
146 quint64 active : 1;
147 quint64 invalid : 1; // = defunct
148 quint64 editable : 1;
149 quint64 multiLine : 1;
150 quint64 selectableText : 1;
151 quint64 supportsAutoCompletion : 1;
152
153 quint64 searchEdit : 1;
154
155 // quint64 horizontal : 1;
156 // quint64 vertical : 1;
157 // quint64 invalidEntry : 1;
158 // quint64 managesDescendants : 1;
159 // quint64 singleLine : 1; // we have multi line, this is redundant.
160 // quint64 stale : 1;
161 // quint64 transient : 1;
162 // quint64 pinned : 1;
163
164 // Apple - see http://mattgemmell.com/2010/12/19/accessibility-for-iphone-and-ipad-apps/
165 // quint64 playsSound : 1;
166 // quint64 summaryElement : 1;
167 // quint64 updatesFrequently : 1;
168 // quint64 adjustable : 1;
169 // more and not included here: http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html
170
171 // MSAA
172 // quint64 alertLow : 1;
173 // quint64 alertMedium : 1;
174 // quint64 alertHigh : 1;
175
176 State() {
177 std::memset(s: this, c: 0, n: sizeof(State));
178 }
179 friend inline bool operator==(const QAccessible::State &first, const QAccessible::State &second)
180 {
181 return std::memcmp(s1: &first, s2: &second, n: sizeof(QAccessible::State)) == 0;
182 }
183 };
184
185
186
187
188
189 enum Role {
190 NoRole = 0x00000000,
191 TitleBar = 0x00000001,
192 MenuBar = 0x00000002,
193 ScrollBar = 0x00000003,
194 Grip = 0x00000004,
195 Sound = 0x00000005,
196 Cursor = 0x00000006,
197 Caret = 0x00000007,
198 AlertMessage = 0x00000008,
199 Window = 0x00000009,
200 Client = 0x0000000A,
201 PopupMenu = 0x0000000B,
202 MenuItem = 0x0000000C,
203 ToolTip = 0x0000000D,
204 Application = 0x0000000E,
205 Document = 0x0000000F,
206 Pane = 0x00000010,
207 Chart = 0x00000011,
208 Dialog = 0x00000012,
209 Border = 0x00000013,
210 Grouping = 0x00000014,
211 Separator = 0x00000015,
212 ToolBar = 0x00000016,
213 StatusBar = 0x00000017,
214 Table = 0x00000018,
215 ColumnHeader = 0x00000019,
216 RowHeader = 0x0000001A,
217 Column = 0x0000001B,
218 Row = 0x0000001C,
219 Cell = 0x0000001D,
220 Link = 0x0000001E,
221 HelpBalloon = 0x0000001F,
222 Assistant = 0x00000020,
223 List = 0x00000021,
224 ListItem = 0x00000022,
225 Tree = 0x00000023,
226 TreeItem = 0x00000024,
227 PageTab = 0x00000025,
228 PropertyPage = 0x00000026,
229 Indicator = 0x00000027,
230 Graphic = 0x00000028,
231 StaticText = 0x00000029,
232 EditableText = 0x0000002A, // Editable, selectable, etc.
233 Button = 0x0000002B,
234#ifndef Q_QDOC
235 PushButton = Button, // deprecated
236#endif
237 CheckBox = 0x0000002C,
238 RadioButton = 0x0000002D,
239 ComboBox = 0x0000002E,
240 // DropList = 0x0000002F,
241 ProgressBar = 0x00000030,
242 Dial = 0x00000031,
243 HotkeyField = 0x00000032,
244 Slider = 0x00000033,
245 SpinBox = 0x00000034,
246 Canvas = 0x00000035, // MSAA: ROLE_SYSTEM_DIAGRAM - The object represents a graphical image that is used to diagram data.
247 Animation = 0x00000036,
248 Equation = 0x00000037,
249 ButtonDropDown = 0x00000038, // The object represents a button that expands a grid.
250 ButtonMenu = 0x00000039,
251 ButtonDropGrid = 0x0000003A,
252 Whitespace = 0x0000003B, // The object represents blank space between other objects.
253 PageTabList = 0x0000003C,
254 Clock = 0x0000003D,
255 Splitter = 0x0000003E,
256 // Reserved space in case MSAA roles needs to be added
257
258 // Additional Qt roles where enum value does not map directly to MSAA:
259 LayeredPane = 0x00000080,
260 Terminal = 0x00000081,
261 Desktop = 0x00000082,
262 Paragraph = 0x00000083,
263 WebDocument = 0x00000084,
264 Section = 0x00000085,
265 Notification = 0x00000086,
266
267 // IAccessible2 roles
268 // IA2_ROLE_CANVAS = 0x401, // An object that can be drawn into and to manage events from the objects drawn into it
269 // IA2_ROLE_CAPTION = 0x402,
270 // IA2_ROLE_CHECK_MENU_ITEM = 0x403,
271 ColorChooser = 0x404,
272 // IA2_ROLE_DATE_EDITOR = 0x405,
273 // IA2_ROLE_DESKTOP_ICON = 0x406,
274 // IA2_ROLE_DESKTOP_PANE = 0x407,
275 // IA2_ROLE_DIRECTORY_PANE = 0x408,
276 // IA2_ROLE_EDITBAR = 0x409,
277 // IA2_ROLE_EMBEDDED_OBJECT = 0x40A,
278 // IA2_ROLE_ENDNOTE = 0x40B,
279 // IA2_ROLE_FILE_CHOOSER = 0x40C,
280 // IA2_ROLE_FONT_CHOOSER = 0x40D,
281 Footer = 0x40E,
282 // IA2_ROLE_FOOTNOTE = 0x40F,
283 Form = 0x410,
284 // some platforms (windows and at-spi) use Frame for regular windows
285 // because window was taken for tool/dock windows by MSAA
286 // Frame = 0x411,
287 // IA2_ROLE_GLASS_PANE = 0x412,
288 // IA2_ROLE_HEADER = 0x413,
289 Heading = 0x414,
290 // IA2_ROLE_ICON = 0x415,
291 // IA2_ROLE_IMAGE_MAP = 0x416,
292 // IA2_ROLE_INPUT_METHOD_WINDOW = 0x417,
293 // IA2_ROLE_INTERNAL_FRAME = 0x418,
294 // IA2_ROLE_LABEL = 0x419,
295 // IA2_ROLE_LAYERED_PANE = 0x41A,
296 Note = 0x41B,
297 // IA2_ROLE_OPTION_PANE = 0x41C,
298 // IA2_ROLE_PAGE = 0x41D,
299 // IA2_ROLE_PARAGRAPH = 0x42E,
300 // IA2_ROLE_RADIO_MENU_ITEM = 0x41F,
301 // IA2_ROLE_REDUNDANT_OBJECT = 0x420,
302 // IA2_ROLE_ROOT_PANE = 0x421,
303 // IA2_ROLE_RULER = 0x422,
304 // IA2_ROLE_SCROLL_PANE = 0x423,
305 // IA2_ROLE_SECTION = 0x424,
306 // IA2_ROLE_SHAPE = 0x425,
307 // IA2_ROLE_SPLIT_PANE = 0x426,
308 // IA2_ROLE_TEAR_OFF_MENU = 0x427,
309 // IA2_ROLE_TERMINAL = 0x428,
310 // IA2_ROLE_TEXT_FRAME = 0x429,
311 // IA2_ROLE_TOGGLE_BUTTON = 0x42A,
312 // IA2_ROLE_VIEW_PORT = 0x42B,
313 ComplementaryContent = 0x42C,
314
315 UserRole = 0x0000ffff
316 };
317 Q_ENUM(Role)
318
319 enum Text {
320 Name = 0,
321 Description,
322 Value,
323 Help,
324 Accelerator,
325 DebugDescription,
326 UserText = 0x0000ffff
327 };
328
329 enum RelationFlag {
330 Label = 0x00000001,
331 Labelled = 0x00000002,
332 Controller = 0x00000004,
333 Controlled = 0x00000008,
334 DescriptionFor = 0x00000010,
335 Described = 0x00000020,
336 FlowsFrom = 0x00000040,
337 FlowsTo = 0x00000080,
338 AllRelations = 0xffffffff
339 };
340 Q_DECLARE_FLAGS(Relation, RelationFlag)
341
342 enum InterfaceType
343 {
344 TextInterface,
345 EditableTextInterface,
346 ValueInterface,
347 ActionInterface,
348 ImageInterface,
349 TableInterface,
350 TableCellInterface,
351 HyperlinkInterface,
352 SelectionInterface
353 };
354
355 enum TextBoundaryType {
356 CharBoundary,
357 WordBoundary,
358 SentenceBoundary,
359 ParagraphBoundary,
360 LineBoundary,
361 NoBoundary
362 };
363
364 typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
365 typedef void(*UpdateHandler)(QAccessibleEvent *event);
366 typedef void(*RootObjectHandler)(QObject*);
367
368 typedef unsigned Id;
369
370 static void installFactory(InterfaceFactory);
371 static void removeFactory(InterfaceFactory);
372 static UpdateHandler installUpdateHandler(UpdateHandler);
373 static RootObjectHandler installRootObjectHandler(RootObjectHandler);
374
375 class Q_GUI_EXPORT ActivationObserver
376 {
377 public:
378 virtual ~ActivationObserver();
379 virtual void accessibilityActiveChanged(bool active) = 0;
380 };
381 static void installActivationObserver(ActivationObserver *);
382 static void removeActivationObserver(ActivationObserver *);
383
384 static QAccessibleInterface *queryAccessibleInterface(QObject *);
385 static Id uniqueId(QAccessibleInterface *iface);
386 static QAccessibleInterface *accessibleInterface(Id uniqueId);
387 static Id registerAccessibleInterface(QAccessibleInterface *iface);
388 static void deleteAccessibleInterface(Id uniqueId);
389
390 static void updateAccessibility(QAccessibleEvent *event);
391
392 static bool isActive();
393 static void setActive(bool active);
394 static void setRootObject(QObject *object);
395
396 static void cleanup();
397
398 static QPair< int, int > qAccessibleTextBoundaryHelper(const QTextCursor &cursor, TextBoundaryType boundaryType);
399
400private:
401 static UpdateHandler updateHandler;
402 static RootObjectHandler rootObjectHandler;
403
404 QAccessible() {}
405
406 friend class QAccessibleCache;
407};
408
409Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
410
411QT_END_NAMESPACE
412
413#endif // QT_CONFIG(accessibility)
414#endif // QACCESSIBLE_BASE_H
415

source code of qtbase/src/gui/accessible/qaccessible_base.h