1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). |
4 | ** Contact: http://www.qt-project.org/legal |
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 Digia. For licensing terms and |
14 | ** conditions see http://qt.digia.com/licensing. For further information |
15 | ** use the contact form at http://qt.digia.com/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 as published by the Free Software |
20 | ** Foundation and appearing in the file LICENSE.LGPL included in the |
21 | ** packaging of this file. Please review the following information to |
22 | ** ensure the GNU Lesser General Public License version 2.1 requirements |
23 | ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
24 | ** |
25 | ** In addition, as a special exception, Digia gives you certain additional |
26 | ** rights. These rights are described in the Digia Qt LGPL Exception |
27 | ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
28 | ** |
29 | ** GNU General Public License Usage |
30 | ** Alternatively, this file may be used under the terms of the GNU |
31 | ** General Public License version 3.0 as published by the Free Software |
32 | ** Foundation and appearing in the file LICENSE.GPL included in the |
33 | ** packaging of this file. Please review the following information to |
34 | ** ensure the GNU General Public License version 3.0 requirements will be |
35 | ** met: http://www.gnu.org/copyleft/gpl.html. |
36 | ** |
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 | |
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 | = 0x0004, |
72 | = 0x0005, |
73 | = 0x0006, |
74 | = 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 | = 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 | = 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 | = 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 | = 0x0000000B, |
201 | = 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 | = 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 | = 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) |
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: |
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 | |
405 | inline QSet<Method> supportedMethods() |
406 | { return qvariant_cast<QSet<Method> >(invokeMethod(ListSupportedMethods)); } |
407 | |
408 | inline QColor foregroundColor() |
409 | { return qvariant_cast<QColor>(invokeMethod(ForegroundColor)); } |
410 | |
411 | inline QColor backgroundColor() |
412 | { return qvariant_cast<QColor>(invokeMethod(BackgroundColor)); } |
413 | |
414 | inline QAccessibleTextInterface *textInterface() |
415 | { return reinterpret_cast<QAccessibleTextInterface *>(cast_helper(QAccessible2::TextInterface)); } |
416 | |
417 | inline QAccessibleEditableTextInterface *editableTextInterface() |
418 | { return reinterpret_cast<QAccessibleEditableTextInterface *>(cast_helper(QAccessible2::EditableTextInterface)); } |
419 | |
420 | inline QAccessibleValueInterface *valueInterface() |
421 | { return reinterpret_cast<QAccessibleValueInterface *>(cast_helper(QAccessible2::ValueInterface)); } |
422 | |
423 | inline QAccessibleTableInterface *tableInterface() |
424 | { return reinterpret_cast<QAccessibleTableInterface *>(cast_helper(QAccessible2::TableInterface)); } |
425 | |
426 | inline QAccessibleActionInterface *actionInterface() |
427 | { return reinterpret_cast<QAccessibleActionInterface *>(cast_helper(QAccessible2::ActionInterface)); } |
428 | |
429 | inline QAccessibleImageInterface *imageInterface() |
430 | { return reinterpret_cast<QAccessibleImageInterface *>(cast_helper(QAccessible2::ImageInterface)); } |
431 | |
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); |
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); |
453 | inline int child() const { return c; } |
454 | inline QString value() const { return val; } |
455 | inline void setValue(const QString &aText) { val = aText; } |
456 | |
457 | private: |
458 | int c; |
459 | QString val; |
460 | }; |
461 | |
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 | |