1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the QtGui module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file. Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #ifndef QACCESSIBLE_H
43 #define QACCESSIBLE_H
44
45 #include <QtCore/qglobal.h>
46 #include <QtCore/qobject.h>
47 #include <QtCore/qrect.h>
48 #include <QtCore/qset.h>
49 #include <QtCore/qvector.h>
50 #include <QtCore/qvariant.h>
51 #include <QtGui/qcolor.h>
52 #include <QtGui/qevent.h>
53
54 QT_BEGIN_HEADER
55
56 QT_BEGIN_NAMESPACE
57
QT_MODULE(Gui)58 QT_MODULE(Gui)
59
60 #ifndef QT_NO_ACCESSIBILITY
61
62 class QAccessibleInterface;
63
64 class Q_GUI_EXPORT QAccessible
65 {
66 public:
67 enum Event {
68 SoundPlayed = 0x0001,
69 Alert = 0x0002,
70 ForegroundChanged = 0x0003,
71 MenuStart = 0x0004,
72 MenuEnd = 0x0005,
73 PopupMenuStart = 0x0006,
74 PopupMenuEnd = 0x0007,
75 ContextHelpStart = 0x000C,
76 ContextHelpEnd = 0x000D,
77 DragDropStart = 0x000E,
78 DragDropEnd = 0x000F,
79 DialogStart = 0x0010,
80 DialogEnd = 0x0011,
81 ScrollingStart = 0x0012,
82 ScrollingEnd = 0x0013,
83
84 MenuCommand = 0x0018,
85
86 // Values from IAccessible2
87 ActionChanged = 0x0101,
88 ActiveDescendantChanged = 0x0102,
89 AttributeChanged = 0x0103,
90 DocumentContentChanged = 0x0104,
91 DocumentLoadComplete = 0x0105,
92 DocumentLoadStopped = 0x0106,
93 DocumentReload = 0x0107,
94 HyperlinkEndIndexChanged = 0x0108,
95 HyperlinkNumberOfAnchorsChanged = 0x0109,
96 HyperlinkSelectedLinkChanged = 0x010A,
97 HypertextLinkActivated = 0x010B,
98 HypertextLinkSelected = 0x010C,
99 HyperlinkStartIndexChanged = 0x010D,
100 HypertextChanged = 0x010E,
101 HypertextNLinksChanged = 0x010F,
102 ObjectAttributeChanged = 0x0110,
103 PageChanged = 0x0111,
104 SectionChanged = 0x0112,
105 TableCaptionChanged = 0x0113,
106 TableColumnDescriptionChanged = 0x0114,
107 TableColumnHeaderChanged = 0x0115,
108 TableModelChanged = 0x0116,
109 TableRowDescriptionChanged = 0x0117,
110 TableRowHeaderChanged = 0x0118,
111 TableSummaryChanged = 0x0119,
112 TextAttributeChanged = 0x011A,
113 TextCaretMoved = 0x011B,
114 // TextChanged = 0x011C, is deprecated in IA2, use TextUpdated
115 TextColumnChanged = 0x011D,
116 TextInserted = 0x011E,
117 TextRemoved = 0x011F,
118 TextUpdated = 0x0120,
119 TextSelectionChanged = 0x0121,
120 VisibleDataChanged = 0x0122,
121
122 ObjectCreated = 0x8000,
123 ObjectDestroyed = 0x8001,
124 ObjectShow = 0x8002,
125 ObjectHide = 0x8003,
126 ObjectReorder = 0x8004,
127 Focus = 0x8005,
128 Selection = 0x8006,
129 SelectionAdd = 0x8007,
130 SelectionRemove = 0x8008,
131 SelectionWithin = 0x8009,
132 StateChanged = 0x800A,
133 LocationChanged = 0x800B,
134 NameChanged = 0x800C,
135 DescriptionChanged = 0x800D,
136 ValueChanged = 0x800E,
137 ParentChanged = 0x800F,
138 HelpChanged = 0x80A0,
139 DefaultActionChanged = 0x80B0,
140 AcceleratorChanged = 0x80C0
141 };
142
143 enum StateFlag {
144 Normal = 0x00000000,
145 Unavailable = 0x00000001,
146 Selected = 0x00000002,
147 Focused = 0x00000004,
148 Pressed = 0x00000008,
149 Checked = 0x00000010,
150 Mixed = 0x00000020,
151 ReadOnly = 0x00000040,
152 HotTracked = 0x00000080,
153 DefaultButton = 0x00000100,
154 // #### Qt5 Expandable
155 Expanded = 0x00000200,
156 Collapsed = 0x00000400,
157 Busy = 0x00000800,
158 // Floating = 0x00001000,
159 Marqueed = 0x00002000,
160 Animated = 0x00004000,
161 Invisible = 0x00008000,
162 Offscreen = 0x00010000,
163 Sizeable = 0x00020000,
164 Movable = 0x00040000,
165 #ifdef QT3_SUPPORT
166 Moveable = Movable,
167 #endif
168 SelfVoicing = 0x00080000,
169 Focusable = 0x00100000,
170 Selectable = 0x00200000,
171 Linked = 0x00400000,
172 Traversed = 0x00800000,
173 MultiSelectable = 0x01000000,
174 ExtSelectable = 0x02000000,
175 //AlertLow = 0x04000000,
176 //AlertMedium = 0x08000000,
177 //AlertHigh = 0x10000000, /* reused for HasInvokeExtension */
178 Protected = 0x20000000,
179 HasPopup = 0x40000000,
180 Modal = 0x80000000,
181
182 // #### Qt5 ManagesDescendants
183 // #### Qt5 remove HasInvokeExtension
184 HasInvokeExtension = 0x10000000 // internal
185 };
186 Q_DECLARE_FLAGS(State, StateFlag)
187
188 enum Role {
189 NoRole = 0x00000000,
190 TitleBar = 0x00000001,
191 MenuBar = 0x00000002,
192 ScrollBar = 0x00000003,
193 Grip = 0x00000004,
194 Sound = 0x00000005,
195 Cursor = 0x00000006,
196 Caret = 0x00000007,
197 AlertMessage = 0x00000008,
198 Window = 0x00000009,
199 Client = 0x0000000A,
200 PopupMenu = 0x0000000B,
201 MenuItem = 0x0000000C,
202 ToolTip = 0x0000000D,
203 Application = 0x0000000E,
204 Document = 0x0000000F,
205 Pane = 0x00000010,
206 Chart = 0x00000011,
207 Dialog = 0x00000012,
208 Border = 0x00000013,
209 Grouping = 0x00000014,
210 Separator = 0x00000015,
211 ToolBar = 0x00000016,
212 StatusBar = 0x00000017,
213 Table = 0x00000018,
214 ColumnHeader = 0x00000019,
215 RowHeader = 0x0000001A,
216 Column = 0x0000001B,
217 Row = 0x0000001C,
218 Cell = 0x0000001D,
219 Link = 0x0000001E,
220 HelpBalloon = 0x0000001F,
221 Assistant = 0x00000020,
222 List = 0x00000021,
223 ListItem = 0x00000022,
224 Tree = 0x00000023,
225 TreeItem = 0x00000024,
226 PageTab = 0x00000025,
227 PropertyPage = 0x00000026,
228 Indicator = 0x00000027,
229 Graphic = 0x00000028,
230 StaticText = 0x00000029,
231 EditableText = 0x0000002A, // Editable, selectable, etc.
232 PushButton = 0x0000002B,
233 CheckBox = 0x0000002C,
234 RadioButton = 0x0000002D,
235 ComboBox = 0x0000002E,
236 // DropList = 0x0000002F,
237 ProgressBar = 0x00000030,
238 Dial = 0x00000031,
239 HotkeyField = 0x00000032,
240 Slider = 0x00000033,
241 SpinBox = 0x00000034,
242 Canvas = 0x00000035,
243 Animation = 0x00000036,
244 Equation = 0x00000037,
245 ButtonDropDown = 0x00000038,
246 ButtonMenu = 0x00000039,
247 ButtonDropGrid = 0x0000003A,
248 Whitespace = 0x0000003B,
249 PageTabList = 0x0000003C,
250 Clock = 0x0000003D,
251 Splitter = 0x0000003E,
252 // Additional Qt roles where enum value does not map directly to MSAA:
253 LayeredPane = 0x0000003F,
254 Terminal = 0x00000040,
255 Desktop = 0x00000041,
256 UserRole = 0x0000ffff
257 };
258
259 enum Text {
260 Name = 0,
261 Description,
262 Value,
263 Help,
264 Accelerator,
265 UserText = 0x0000ffff
266 };
267
268 enum RelationFlag {
269 Unrelated = 0x00000000,
270 Self = 0x00000001,
271 Ancestor = 0x00000002,
272 Child = 0x00000004,
273 Descendent = 0x00000008,
274 Sibling = 0x00000010,
275 HierarchyMask = 0x000000ff,
276
277 Up = 0x00000100,
278 Down = 0x00000200,
279 Left = 0x00000400,
280 Right = 0x00000800,
281 Covers = 0x00001000,
282 Covered = 0x00002000,
283 GeometryMask = 0x0000ff00,
284
285 FocusChild = 0x00010000,
286 Label = 0x00020000,
287 Labelled = 0x00040000,
288 Controller = 0x00080000,
289 Controlled = 0x00100000,
290 LogicalMask = 0x00ff0000
291 };
292 Q_DECLARE_FLAGS(Relation, RelationFlag)
293
294 enum Action {
295 DefaultAction = 0,
296 Press = -1,
297 FirstStandardAction = Press,
298 SetFocus = -2,
299 Increase = -3,
300 Decrease = -4,
301 Accept = -5,
302 Cancel = -6,
303 Select = -7,
304 ClearSelection = -8,
305 RemoveSelection = -9,
306 ExtendSelection = -10,
307 AddToSelection = -11,
308 LastStandardAction = AddToSelection
309 };
310
311 enum Method {
312 ListSupportedMethods = 0,
313 SetCursorPosition = 1,
314 GetCursorPosition = 2,
315 ForegroundColor = 3,
316 BackgroundColor = 4
317 };
318
319 typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
320 typedef void(*UpdateHandler)(QObject*, int who, Event reason);
321 typedef void(*RootObjectHandler)(QObject*);
322
323 static void installFactory(InterfaceFactory);
324 static void removeFactory(InterfaceFactory);
325 static UpdateHandler installUpdateHandler(UpdateHandler);
326 static RootObjectHandler installRootObjectHandler(RootObjectHandler);
327
328 static QAccessibleInterface *queryAccessibleInterface(QObject *);
329 static void updateAccessibility(QObject *, int who, Event reason);
330 static bool isActive();
331 static void setRootObject(QObject*);
332
333 static void initialize();
334 static void cleanup();
335
336 private:
337 static UpdateHandler updateHandler;
338 static RootObjectHandler rootObjectHandler;
339 };
340
341 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::State)
Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)342 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
343 QT_END_NAMESPACE
344 Q_DECLARE_METATYPE(QSet<QAccessible::Method>)
345 QT_BEGIN_NAMESPACE
346
347 namespace QAccessible2
348 {
349 enum InterfaceType
350 {
351 TextInterface,
352 EditableTextInterface,
353 ValueInterface,
354 TableInterface,
355 ActionInterface,
356 ImageInterface,
357 Table2Interface
358 };
359 }
360
361 class QAccessible2Interface;
362 class QAccessibleTextInterface;
363 class QAccessibleEditableTextInterface;
364 class QAccessibleValueInterface;
365 class QAccessibleTableInterface;
366 class QAccessibleActionInterface;
367 class QAccessibleImageInterface;
368 class QAccessibleTable2Interface;
369
370 class Q_GUI_EXPORT QAccessibleInterface : public QAccessible
371 {
372 public:
~QAccessibleInterface()373 virtual ~QAccessibleInterface() {}
374 // check for valid pointers
375 virtual bool isValid() const = 0;
376 virtual QObject *object() const = 0;
377
378 // hierarchy
379 virtual int childCount() const = 0;
380 virtual int indexOfChild(const QAccessibleInterface *) const = 0;
381
382 // relations
383 virtual Relation relationTo(int child, const QAccessibleInterface *other,
384 int otherChild) const = 0;
385 virtual int childAt(int x, int y) const = 0;
386
387 // navigation
388 virtual int navigate(RelationFlag relation, int index, QAccessibleInterface **iface) const = 0;
389
390 // properties and state
391 virtual QString text(Text t, int child) const = 0;
392 virtual void setText(Text t, int child, const QString &text) = 0;
393 virtual QRect rect(int child) const = 0;
394 virtual Role role(int child) const = 0;
395 virtual State state(int child) const = 0;
396
397 // action
398 virtual int userActionCount(int child) const = 0;
399 virtual QString actionText(int action, Text t, int child) const = 0;
400 virtual bool doAction(int action, int child, const QVariantList ¶ms = QVariantList()) = 0;
401
402 QVariant invokeMethod(Method method, int child = 0,
403 const QVariantList ¶ms = QVariantList());
404
supportedMethods()405 inline QSet<Method> supportedMethods()
406 { return qvariant_cast<QSet<Method> >(invokeMethod(ListSupportedMethods)); }
407
foregroundColor()408 inline QColor foregroundColor()
409 { return qvariant_cast<QColor>(invokeMethod(ForegroundColor)); }
410
backgroundColor()411 inline QColor backgroundColor()
412 { return qvariant_cast<QColor>(invokeMethod(BackgroundColor)); }
413
textInterface()414 inline QAccessibleTextInterface *textInterface()
415 { return reinterpret_cast<QAccessibleTextInterface *>(cast_helper(QAccessible2::TextInterface)); }
416
editableTextInterface()417 inline QAccessibleEditableTextInterface *editableTextInterface()
418 { return reinterpret_cast<QAccessibleEditableTextInterface *>(cast_helper(QAccessible2::EditableTextInterface)); }
419
valueInterface()420 inline QAccessibleValueInterface *valueInterface()
421 { return reinterpret_cast<QAccessibleValueInterface *>(cast_helper(QAccessible2::ValueInterface)); }
422
tableInterface()423 inline QAccessibleTableInterface *tableInterface()
424 { return reinterpret_cast<QAccessibleTableInterface *>(cast_helper(QAccessible2::TableInterface)); }
425
actionInterface()426 inline QAccessibleActionInterface *actionInterface()
427 { return reinterpret_cast<QAccessibleActionInterface *>(cast_helper(QAccessible2::ActionInterface)); }
428
imageInterface()429 inline QAccessibleImageInterface *imageInterface()
430 { return reinterpret_cast<QAccessibleImageInterface *>(cast_helper(QAccessible2::ImageInterface)); }
431
table2Interface()432 inline QAccessibleTable2Interface *table2Interface()
433 { return reinterpret_cast<QAccessibleTable2Interface *>(cast_helper(QAccessible2::Table2Interface)); }
434
435 private:
436 QAccessible2Interface *cast_helper(QAccessible2::InterfaceType);
437 };
438
439 class Q_GUI_EXPORT QAccessibleInterfaceEx: public QAccessibleInterface
440 {
441 public:
442 virtual QVariant invokeMethodEx(Method method, int child, const QVariantList ¶ms) = 0;
443 virtual QVariant virtual_hook(const QVariant &data);
interface_cast(QAccessible2::InterfaceType)444 virtual QAccessible2Interface *interface_cast(QAccessible2::InterfaceType)
445 { return 0; }
446 };
447
448
449 class Q_GUI_EXPORT QAccessibleEvent : public QEvent
450 {
451 public:
452 inline QAccessibleEvent(Type type, int child);
child()453 inline int child() const { return c; }
value()454 inline QString value() const { return val; }
setValue(const QString & aText)455 inline void setValue(const QString &aText) { val = aText; }
456
457 private:
458 int c;
459 QString val;
460 };
461
QAccessibleEvent(Type atype,int achild)462 inline QAccessibleEvent::QAccessibleEvent(Type atype, int achild)
463 : QEvent(atype), c(achild) {}
464
465 #define QAccessibleInterface_iid "com.trolltech.Qt.QAccessibleInterface"
466 Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
467
468 #endif // QT_NO_ACCESSIBILITY
469
470 QT_END_NAMESPACE
471
472 QT_END_HEADER
473
474 #endif // QACCESSIBLE_H
475