1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://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 https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://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 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include <QtGui/qtguiglobal.h>
41
42#ifndef QT_NO_ACCESSIBILITY
43#ifndef QACCESSIBLE_H
44#define QACCESSIBLE_H
45
46#include <QtCore/qcoreapplication.h>
47#include <QtCore/qdebug.h>
48#include <QtCore/qglobal.h>
49#include <QtCore/qobject.h>
50#include <QtCore/qrect.h>
51#include <QtCore/qset.h>
52#include <QtCore/qvector.h>
53#include <QtCore/qvariant.h>
54#include <QtGui/qcolor.h>
55#include <QtGui/qevent.h>
56
57#include <stdlib.h>
58
59QT_BEGIN_NAMESPACE
60
61class QAccessibleInterface;
62class QAccessibleEvent;
63class QWindow;
64class QTextCursor;
65
66class Q_GUI_EXPORT QAccessible
67{
68 Q_GADGET
69public:
70
71 enum Event {
72 SoundPlayed = 0x0001,
73 Alert = 0x0002,
74 ForegroundChanged = 0x0003,
75 MenuStart = 0x0004,
76 MenuEnd = 0x0005,
77 PopupMenuStart = 0x0006,
78 PopupMenuEnd = 0x0007,
79 ContextHelpStart = 0x000C,
80 ContextHelpEnd = 0x000D,
81 DragDropStart = 0x000E,
82 DragDropEnd = 0x000F,
83 DialogStart = 0x0010,
84 DialogEnd = 0x0011,
85 ScrollingStart = 0x0012,
86 ScrollingEnd = 0x0013,
87
88 MenuCommand = 0x0018,
89
90 // Values from IAccessible2
91 ActionChanged = 0x0101,
92 ActiveDescendantChanged = 0x0102,
93 AttributeChanged = 0x0103,
94 DocumentContentChanged = 0x0104,
95 DocumentLoadComplete = 0x0105,
96 DocumentLoadStopped = 0x0106,
97 DocumentReload = 0x0107,
98 HyperlinkEndIndexChanged = 0x0108,
99 HyperlinkNumberOfAnchorsChanged = 0x0109,
100 HyperlinkSelectedLinkChanged = 0x010A,
101 HypertextLinkActivated = 0x010B,
102 HypertextLinkSelected = 0x010C,
103 HyperlinkStartIndexChanged = 0x010D,
104 HypertextChanged = 0x010E,
105 HypertextNLinksChanged = 0x010F,
106 ObjectAttributeChanged = 0x0110,
107 PageChanged = 0x0111,
108 SectionChanged = 0x0112,
109 TableCaptionChanged = 0x0113,
110 TableColumnDescriptionChanged = 0x0114,
111 TableColumnHeaderChanged = 0x0115,
112 TableModelChanged = 0x0116,
113 TableRowDescriptionChanged = 0x0117,
114 TableRowHeaderChanged = 0x0118,
115 TableSummaryChanged = 0x0119,
116 TextAttributeChanged = 0x011A,
117 TextCaretMoved = 0x011B,
118 // TextChanged = 0x011C, is deprecated in IA2, use TextUpdated
119 TextColumnChanged = 0x011D,
120 TextInserted = 0x011E,
121 TextRemoved = 0x011F,
122 TextUpdated = 0x0120,
123 TextSelectionChanged = 0x0121,
124 VisibleDataChanged = 0x0122,
125
126 ObjectCreated = 0x8000,
127 ObjectDestroyed = 0x8001,
128 ObjectShow = 0x8002,
129 ObjectHide = 0x8003,
130 ObjectReorder = 0x8004,
131 Focus = 0x8005,
132 Selection = 0x8006,
133 SelectionAdd = 0x8007,
134 SelectionRemove = 0x8008,
135 SelectionWithin = 0x8009,
136 StateChanged = 0x800A,
137 LocationChanged = 0x800B,
138 NameChanged = 0x800C,
139 DescriptionChanged = 0x800D,
140 ValueChanged = 0x800E,
141 ParentChanged = 0x800F,
142 HelpChanged = 0x80A0,
143 DefaultActionChanged = 0x80B0,
144 AcceleratorChanged = 0x80C0,
145
146 InvalidEvent
147 };
148 Q_ENUM(Event)
149
150 // 64 bit enums seem hard on some platforms (windows...)
151 // which makes using a bit field a sensible alternative
152 struct State {
153 // http://msdn.microsoft.com/en-us/library/ms697270.aspx
154 quint64 disabled : 1; // used to be Unavailable
155 quint64 selected : 1;
156 quint64 focusable : 1;
157 quint64 focused : 1;
158 quint64 pressed : 1;
159 quint64 checkable : 1;
160 quint64 checked : 1;
161 quint64 checkStateMixed : 1; // used to be Mixed
162 quint64 readOnly : 1;
163 quint64 hotTracked : 1;
164 quint64 defaultButton : 1;
165 quint64 expanded : 1;
166 quint64 collapsed : 1;
167 quint64 busy : 1;
168 quint64 expandable : 1;
169 quint64 marqueed : 1;
170 quint64 animated : 1;
171 quint64 invisible : 1;
172 quint64 offscreen : 1;
173 quint64 sizeable : 1;
174 quint64 movable : 1;
175 quint64 selfVoicing : 1;
176 quint64 selectable : 1;
177 quint64 linked : 1;
178 quint64 traversed : 1;
179 quint64 multiSelectable : 1;
180 quint64 extSelectable : 1;
181 quint64 passwordEdit : 1; // used to be Protected
182 quint64 hasPopup : 1;
183 quint64 modal : 1;
184
185 // IA2 - we chose to not add some IA2 states for now
186 // Below the ones that seem helpful
187 quint64 active : 1;
188 quint64 invalid : 1; // = defunct
189 quint64 editable : 1;
190 quint64 multiLine : 1;
191 quint64 selectableText : 1;
192 quint64 supportsAutoCompletion : 1;
193
194 quint64 searchEdit : 1;
195
196 // quint64 horizontal : 1;
197 // quint64 vertical : 1;
198 // quint64 invalidEntry : 1;
199 // quint64 managesDescendants : 1;
200 // quint64 singleLine : 1; // we have multi line, this is redundant.
201 // quint64 stale : 1;
202 // quint64 transient : 1;
203 // quint64 pinned : 1;
204
205 // Apple - see http://mattgemmell.com/2010/12/19/accessibility-for-iphone-and-ipad-apps/
206 // quint64 playsSound : 1;
207 // quint64 summaryElement : 1;
208 // quint64 updatesFrequently : 1;
209 // quint64 adjustable : 1;
210 // more and not included here: http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html
211
212 // MSAA
213 // quint64 alertLow : 1;
214 // quint64 alertMedium : 1;
215 // quint64 alertHigh : 1;
216
217 State() {
218 memset(this, 0, sizeof(State));
219 }
220 };
221
222
223
224
225
226 enum Role {
227 NoRole = 0x00000000,
228 TitleBar = 0x00000001,
229 MenuBar = 0x00000002,
230 ScrollBar = 0x00000003,
231 Grip = 0x00000004,
232 Sound = 0x00000005,
233 Cursor = 0x00000006,
234 Caret = 0x00000007,
235 AlertMessage = 0x00000008,
236 Window = 0x00000009,
237 Client = 0x0000000A,
238 PopupMenu = 0x0000000B,
239 MenuItem = 0x0000000C,
240 ToolTip = 0x0000000D,
241 Application = 0x0000000E,
242 Document = 0x0000000F,
243 Pane = 0x00000010,
244 Chart = 0x00000011,
245 Dialog = 0x00000012,
246 Border = 0x00000013,
247 Grouping = 0x00000014,
248 Separator = 0x00000015,
249 ToolBar = 0x00000016,
250 StatusBar = 0x00000017,
251 Table = 0x00000018,
252 ColumnHeader = 0x00000019,
253 RowHeader = 0x0000001A,
254 Column = 0x0000001B,
255 Row = 0x0000001C,
256 Cell = 0x0000001D,
257 Link = 0x0000001E,
258 HelpBalloon = 0x0000001F,
259 Assistant = 0x00000020,
260 List = 0x00000021,
261 ListItem = 0x00000022,
262 Tree = 0x00000023,
263 TreeItem = 0x00000024,
264 PageTab = 0x00000025,
265 PropertyPage = 0x00000026,
266 Indicator = 0x00000027,
267 Graphic = 0x00000028,
268 StaticText = 0x00000029,
269 EditableText = 0x0000002A, // Editable, selectable, etc.
270 Button = 0x0000002B,
271#ifndef Q_QDOC
272 PushButton = Button, // deprecated
273#endif
274 CheckBox = 0x0000002C,
275 RadioButton = 0x0000002D,
276 ComboBox = 0x0000002E,
277 // DropList = 0x0000002F,
278 ProgressBar = 0x00000030,
279 Dial = 0x00000031,
280 HotkeyField = 0x00000032,
281 Slider = 0x00000033,
282 SpinBox = 0x00000034,
283 Canvas = 0x00000035, // Diagram for MSAA
284 Animation = 0x00000036,
285 Equation = 0x00000037,
286 ButtonDropDown = 0x00000038, // The object represents a button that expands a grid.
287 ButtonMenu = 0x00000039,
288 ButtonDropGrid = 0x0000003A,
289 Whitespace = 0x0000003B, // The object represents blank space between other objects.
290 PageTabList = 0x0000003C,
291 Clock = 0x0000003D,
292 Splitter = 0x0000003E,
293 // Reserved space in case MSAA roles needs to be added
294
295 // Additional Qt roles where enum value does not map directly to MSAA:
296 LayeredPane = 0x00000080,
297 Terminal = 0x00000081,
298 Desktop = 0x00000082,
299 Paragraph = 0x00000083,
300 WebDocument = 0x00000084,
301 Section = 0x00000085,
302
303 // IAccessible2 roles
304 // IA2_ROLE_CANVAS = 0x401, ### Qt 6 use this one instead of Canvas above
305 // IA2_ROLE_CAPTION = 0x402,
306 // IA2_ROLE_CHECK_MENU_ITEM = 0x403,
307 ColorChooser = 0x404,
308 // IA2_ROLE_DATE_EDITOR = 0x405,
309 // IA2_ROLE_DESKTOP_ICON = 0x406,
310 // IA2_ROLE_DESKTOP_PANE = 0x407,
311 // IA2_ROLE_DIRECTORY_PANE = 0x408,
312 // IA2_ROLE_EDITBAR = 0x409,
313 // IA2_ROLE_EMBEDDED_OBJECT = 0x40A,
314 // IA2_ROLE_ENDNOTE = 0x40B,
315 // IA2_ROLE_FILE_CHOOSER = 0x40C,
316 // IA2_ROLE_FONT_CHOOSER = 0x40D,
317 Footer = 0x40E,
318 // IA2_ROLE_FOOTNOTE = 0x40F,
319 Form = 0x410,
320 // some platforms (windows and at-spi) use Frame for regular windows
321 // because window was taken for tool/dock windows by MSAA
322 // Frame = 0x411,
323 // IA2_ROLE_GLASS_PANE = 0x412,
324 // IA2_ROLE_HEADER = 0x413,
325 Heading = 0x414,
326 // IA2_ROLE_ICON = 0x415,
327 // IA2_ROLE_IMAGE_MAP = 0x416,
328 // IA2_ROLE_INPUT_METHOD_WINDOW = 0x417,
329 // IA2_ROLE_INTERNAL_FRAME = 0x418,
330 // IA2_ROLE_LABEL = 0x419,
331 // IA2_ROLE_LAYERED_PANE = 0x41A,
332 Note = 0x41B,
333 // IA2_ROLE_OPTION_PANE = 0x41C,
334 // IA2_ROLE_PAGE = 0x41D,
335 // IA2_ROLE_PARAGRAPH = 0x42E,
336 // IA2_ROLE_RADIO_MENU_ITEM = 0x41F,
337 // IA2_ROLE_REDUNDANT_OBJECT = 0x420,
338 // IA2_ROLE_ROOT_PANE = 0x421,
339 // IA2_ROLE_RULER = 0x422,
340 // IA2_ROLE_SCROLL_PANE = 0x423,
341 // IA2_ROLE_SECTION = 0x424,
342 // IA2_ROLE_SHAPE = 0x425,
343 // IA2_ROLE_SPLIT_PANE = 0x426,
344 // IA2_ROLE_TEAR_OFF_MENU = 0x427,
345 // IA2_ROLE_TERMINAL = 0x428,
346 // IA2_ROLE_TEXT_FRAME = 0x429,
347 // IA2_ROLE_TOGGLE_BUTTON = 0x42A,
348 // IA2_ROLE_VIEW_PORT = 0x42B,
349 ComplementaryContent = 0x42C,
350
351 UserRole = 0x0000ffff
352 };
353 Q_ENUM(Role)
354
355 enum Text {
356 Name = 0,
357 Description,
358 Value,
359 Help,
360 Accelerator,
361 DebugDescription,
362 UserText = 0x0000ffff
363 };
364
365 enum RelationFlag {
366 Label = 0x00000001,
367 Labelled = 0x00000002,
368 Controller = 0x00000004,
369 Controlled = 0x00000008,
370 AllRelations = 0xffffffff
371 };
372 Q_DECLARE_FLAGS(Relation, RelationFlag)
373
374 enum InterfaceType
375 {
376 TextInterface,
377 EditableTextInterface,
378 ValueInterface,
379 ActionInterface,
380 ImageInterface,
381 TableInterface,
382 TableCellInterface
383 };
384
385 enum TextBoundaryType {
386 CharBoundary,
387 WordBoundary,
388 SentenceBoundary,
389 ParagraphBoundary,
390 LineBoundary,
391 NoBoundary
392 };
393
394 typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
395 typedef void(*UpdateHandler)(QAccessibleEvent *event);
396 typedef void(*RootObjectHandler)(QObject*);
397
398 typedef unsigned Id;
399
400 static void installFactory(InterfaceFactory);
401 static void removeFactory(InterfaceFactory);
402 static UpdateHandler installUpdateHandler(UpdateHandler);
403 static RootObjectHandler installRootObjectHandler(RootObjectHandler);
404
405 class Q_GUI_EXPORT ActivationObserver
406 {
407 public:
408 virtual ~ActivationObserver();
409 virtual void accessibilityActiveChanged(bool active) = 0;
410 };
411 static void installActivationObserver(ActivationObserver *);
412 static void removeActivationObserver(ActivationObserver *);
413
414 static QAccessibleInterface *queryAccessibleInterface(QObject *);
415 static Id uniqueId(QAccessibleInterface *iface);
416 static QAccessibleInterface *accessibleInterface(Id uniqueId);
417 static Id registerAccessibleInterface(QAccessibleInterface *iface);
418 static void deleteAccessibleInterface(Id uniqueId);
419
420
421#if QT_DEPRECATED_SINCE(5, 0)
422 QT_DEPRECATED static inline void updateAccessibility(QObject *object, int child, Event reason);
423#endif
424 static void updateAccessibility(QAccessibleEvent *event);
425
426 static bool isActive();
427 static void setActive(bool active);
428 static void setRootObject(QObject *object);
429
430 static void cleanup();
431
432 static QPair< int, int > qAccessibleTextBoundaryHelper(const QTextCursor &cursor, TextBoundaryType boundaryType);
433
434private:
435 static UpdateHandler updateHandler;
436 static RootObjectHandler rootObjectHandler;
437
438 QAccessible() {}
439
440 friend class QAccessibleCache;
441};
442
443Q_GUI_EXPORT bool operator==(const QAccessible::State &first, const QAccessible::State &second);
444
445Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
446
447class QAccessible2Interface;
448class QAccessibleTextInterface;
449class QAccessibleEditableTextInterface;
450class QAccessibleValueInterface;
451class QAccessibleActionInterface;
452class QAccessibleImageInterface;
453class QAccessibleTableInterface;
454class QAccessibleTableCellInterface;
455class QAccessibleTableModelChangeEvent;
456
457class Q_GUI_EXPORT QAccessibleInterface
458{
459protected:
460 virtual ~QAccessibleInterface();
461
462public:
463 // check for valid pointers
464 virtual bool isValid() const = 0;
465 virtual QObject *object() const = 0;
466 virtual QWindow *window() const;
467
468 // relations
469 virtual QVector<QPair<QAccessibleInterface*, QAccessible::Relation> > relations(QAccessible::Relation match = QAccessible::AllRelations) const;
470 virtual QAccessibleInterface *focusChild() const;
471
472 virtual QAccessibleInterface *childAt(int x, int y) const = 0;
473
474 // navigation, hierarchy
475 virtual QAccessibleInterface *parent() const = 0;
476 virtual QAccessibleInterface *child(int index) const = 0;
477 virtual int childCount() const = 0;
478 virtual int indexOfChild(const QAccessibleInterface *) const = 0;
479
480 // properties and state
481 virtual QString text(QAccessible::Text t) const = 0;
482 virtual void setText(QAccessible::Text t, const QString &text) = 0;
483 virtual QRect rect() const = 0;
484 virtual QAccessible::Role role() const = 0;
485 virtual QAccessible::State state() const = 0;
486
487 virtual QColor foregroundColor() const;
488 virtual QColor backgroundColor() const;
489
490 inline QAccessibleTextInterface *textInterface()
491 { return reinterpret_cast<QAccessibleTextInterface *>(interface_cast(QAccessible::TextInterface)); }
492
493 inline QAccessibleEditableTextInterface *editableTextInterface()
494 { return reinterpret_cast<QAccessibleEditableTextInterface *>(interface_cast(QAccessible::EditableTextInterface)); }
495
496 inline QAccessibleValueInterface *valueInterface()
497 { return reinterpret_cast<QAccessibleValueInterface *>(interface_cast(QAccessible::ValueInterface)); }
498
499 inline QAccessibleActionInterface *actionInterface()
500 { return reinterpret_cast<QAccessibleActionInterface *>(interface_cast(QAccessible::ActionInterface)); }
501
502 inline QAccessibleImageInterface *imageInterface()
503 { return reinterpret_cast<QAccessibleImageInterface *>(interface_cast(QAccessible::ImageInterface)); }
504
505 inline QAccessibleTableInterface *tableInterface()
506 { return reinterpret_cast<QAccessibleTableInterface *>(interface_cast(QAccessible::TableInterface)); }
507
508 inline QAccessibleTableCellInterface *tableCellInterface()
509 { return reinterpret_cast<QAccessibleTableCellInterface *>(interface_cast(QAccessible::TableCellInterface)); }
510
511 virtual void virtual_hook(int id, void *data);
512
513 virtual void *interface_cast(QAccessible::InterfaceType)
514 { return nullptr; }
515
516protected:
517 friend class QAccessibleCache;
518};
519
520class Q_GUI_EXPORT QAccessibleTextInterface
521{
522public:
523 virtual ~QAccessibleTextInterface();
524 // selection
525 virtual void selection(int selectionIndex, int *startOffset, int *endOffset) const = 0;
526 virtual int selectionCount() const = 0;
527 virtual void addSelection(int startOffset, int endOffset) = 0;
528 virtual void removeSelection(int selectionIndex) = 0;
529 virtual void setSelection(int selectionIndex, int startOffset, int endOffset) = 0;
530
531 // cursor
532 virtual int cursorPosition() const = 0;
533 virtual void setCursorPosition(int position) = 0;
534
535 // text
536 virtual QString text(int startOffset, int endOffset) const = 0;
537 virtual QString textBeforeOffset(int offset, QAccessible::TextBoundaryType boundaryType,
538 int *startOffset, int *endOffset) const;
539 virtual QString textAfterOffset(int offset, QAccessible::TextBoundaryType boundaryType,
540 int *startOffset, int *endOffset) const;
541 virtual QString textAtOffset(int offset, QAccessible::TextBoundaryType boundaryType,
542 int *startOffset, int *endOffset) const;
543 virtual int characterCount() const = 0;
544
545 // character <-> geometry
546 virtual QRect characterRect(int offset) const = 0;
547 virtual int offsetAtPoint(const QPoint &point) const = 0;
548
549 virtual void scrollToSubstring(int startIndex, int endIndex) = 0;
550 virtual QString attributes(int offset, int *startOffset, int *endOffset) const = 0;
551};
552
553class Q_GUI_EXPORT QAccessibleEditableTextInterface
554{
555public:
556 virtual ~QAccessibleEditableTextInterface();
557
558 virtual void deleteText(int startOffset, int endOffset) = 0;
559 virtual void insertText(int offset, const QString &text) = 0;
560 virtual void replaceText(int startOffset, int endOffset, const QString &text) = 0;
561};
562
563class Q_GUI_EXPORT QAccessibleValueInterface
564{
565public:
566 virtual ~QAccessibleValueInterface();
567
568 virtual QVariant currentValue() const = 0;
569 virtual void setCurrentValue(const QVariant &value) = 0;
570 virtual QVariant maximumValue() const = 0;
571 virtual QVariant minimumValue() const = 0;
572 virtual QVariant minimumStepSize() const = 0;
573};
574
575class Q_GUI_EXPORT QAccessibleTableCellInterface
576{
577public:
578 virtual ~QAccessibleTableCellInterface();
579
580 virtual bool isSelected() const = 0;
581
582 virtual QList<QAccessibleInterface*> columnHeaderCells() const = 0;
583 virtual QList<QAccessibleInterface*> rowHeaderCells() const = 0;
584 virtual int columnIndex() const = 0;
585 virtual int rowIndex() const = 0;
586 virtual int columnExtent() const = 0;
587 virtual int rowExtent() const = 0;
588
589 virtual QAccessibleInterface* table() const = 0;
590};
591
592class Q_GUI_EXPORT QAccessibleTableInterface
593{
594public:
595 virtual ~QAccessibleTableInterface();
596
597 virtual QAccessibleInterface *caption() const = 0;
598 virtual QAccessibleInterface *summary() const = 0;
599
600 virtual QAccessibleInterface *cellAt (int row, int column) const = 0;
601 virtual int selectedCellCount() const = 0;
602 virtual QList<QAccessibleInterface*> selectedCells() const = 0;
603
604 virtual QString columnDescription(int column) const = 0;
605 virtual QString rowDescription(int row) const = 0;
606 virtual int selectedColumnCount() const = 0;
607 virtual int selectedRowCount() const = 0;
608 virtual int columnCount() const = 0;
609 virtual int rowCount() const = 0;
610 virtual QList<int> selectedColumns() const = 0;
611 virtual QList<int> selectedRows() const = 0;
612 virtual bool isColumnSelected(int column) const = 0;
613 virtual bool isRowSelected(int row) const = 0;
614 virtual bool selectRow(int row) = 0;
615 virtual bool selectColumn(int column) = 0;
616 virtual bool unselectRow(int row) = 0;
617 virtual bool unselectColumn(int column) = 0;
618
619 virtual void modelChange(QAccessibleTableModelChangeEvent *event) = 0;
620
621protected:
622friend class QAbstractItemView;
623friend class QAbstractItemViewPrivate;
624};
625
626class Q_GUI_EXPORT QAccessibleActionInterface
627{
628 Q_DECLARE_TR_FUNCTIONS(QAccessibleActionInterface)
629public:
630 virtual ~QAccessibleActionInterface();
631
632 virtual QStringList actionNames() const = 0;
633 virtual QString localizedActionName(const QString &name) const;
634 virtual QString localizedActionDescription(const QString &name) const;
635 virtual void doAction(const QString &actionName) = 0;
636 virtual QStringList keyBindingsForAction(const QString &actionName) const = 0;
637
638 static const QString &pressAction();
639 static const QString &increaseAction();
640 static const QString &decreaseAction();
641 static const QString &showMenuAction();
642 static const QString &setFocusAction();
643 static const QString &toggleAction();
644 static QString scrollLeftAction();
645 static QString scrollRightAction();
646 static QString scrollUpAction();
647 static QString scrollDownAction();
648 static QString nextPageAction();
649 static QString previousPageAction();
650};
651
652class Q_GUI_EXPORT QAccessibleImageInterface
653{
654public:
655 virtual ~QAccessibleImageInterface();
656
657 virtual QString imageDescription() const = 0;
658 virtual QSize imageSize() const = 0;
659 virtual QPoint imagePosition() const = 0;
660};
661
662
663class Q_GUI_EXPORT QAccessibleEvent
664{
665 Q_DISABLE_COPY(QAccessibleEvent)
666public:
667
668 inline QAccessibleEvent(QObject *obj, QAccessible::Event typ)
669 : m_type(typ), m_object(obj), m_child(-1)
670 {
671 Q_ASSERT(obj);
672 // All events below have a subclass of QAccessibleEvent.
673 // Use the subclass, since it's expected that it's possible to cast to that.
674 Q_ASSERT(m_type != QAccessible::ValueChanged);
675 Q_ASSERT(m_type != QAccessible::StateChanged);
676 Q_ASSERT(m_type != QAccessible::TextCaretMoved);
677 Q_ASSERT(m_type != QAccessible::TextSelectionChanged);
678 Q_ASSERT(m_type != QAccessible::TextInserted);
679 Q_ASSERT(m_type != QAccessible::TextRemoved);
680 Q_ASSERT(m_type != QAccessible::TextUpdated);
681 Q_ASSERT(m_type != QAccessible::TableModelChanged);
682 }
683
684 inline QAccessibleEvent(QAccessibleInterface *iface, QAccessible::Event typ)
685 : m_type(typ), m_object(nullptr)
686 {
687 Q_ASSERT(iface);
688 Q_ASSERT(m_type != QAccessible::ValueChanged);
689 Q_ASSERT(m_type != QAccessible::StateChanged);
690 Q_ASSERT(m_type != QAccessible::TextCaretMoved);
691 Q_ASSERT(m_type != QAccessible::TextSelectionChanged);
692 Q_ASSERT(m_type != QAccessible::TextInserted);
693 Q_ASSERT(m_type != QAccessible::TextRemoved);
694 Q_ASSERT(m_type != QAccessible::TextUpdated);
695 Q_ASSERT(m_type != QAccessible::TableModelChanged);
696 m_uniqueId = QAccessible::uniqueId(iface);
697 }
698
699 virtual ~QAccessibleEvent();
700
701 QAccessible::Event type() const { return m_type; }
702 QObject *object() const { return m_object; }
703 QAccessible::Id uniqueId() const;
704
705 void setChild(int chld) { m_child = chld; }
706 int child() const { return m_child; }
707
708 virtual QAccessibleInterface *accessibleInterface() const;
709
710protected:
711 QAccessible::Event m_type;
712 QObject *m_object;
713 union {
714 int m_child;
715 QAccessible::Id m_uniqueId;
716 };
717
718};
719
720class Q_GUI_EXPORT QAccessibleStateChangeEvent :public QAccessibleEvent
721{
722public:
723 inline QAccessibleStateChangeEvent(QObject *obj, QAccessible::State state)
724 : QAccessibleEvent(obj, QAccessible::InvalidEvent), m_changedStates(state)
725 {
726 m_type = QAccessible::StateChanged;
727 }
728 inline QAccessibleStateChangeEvent(QAccessibleInterface *iface, QAccessible::State state)
729 : QAccessibleEvent(iface, QAccessible::InvalidEvent), m_changedStates(state)
730 {
731 m_type = QAccessible::StateChanged;
732 }
733 ~QAccessibleStateChangeEvent();
734
735 QAccessible::State changedStates() const {
736 return m_changedStates;
737 }
738
739protected:
740 QAccessible::State m_changedStates;
741};
742
743// Update the cursor and optionally the selection.
744class Q_GUI_EXPORT QAccessibleTextCursorEvent : public QAccessibleEvent
745{
746public:
747 inline QAccessibleTextCursorEvent(QObject *obj, int cursorPos)
748 : QAccessibleEvent(obj, QAccessible::InvalidEvent)
749 , m_cursorPosition(cursorPos)
750 {
751 m_type = QAccessible::TextCaretMoved;
752 }
753 inline QAccessibleTextCursorEvent(QAccessibleInterface *iface, int cursorPos)
754 : QAccessibleEvent(iface, QAccessible::InvalidEvent)
755 , m_cursorPosition(cursorPos)
756 {
757 m_type = QAccessible::TextCaretMoved;
758 }
759
760 ~QAccessibleTextCursorEvent();
761
762 void setCursorPosition(int position) { m_cursorPosition = position; }
763 int cursorPosition() const { return m_cursorPosition; }
764
765protected:
766 int m_cursorPosition;
767};
768
769// Updates the cursor position simultaneously. By default the cursor is set to the end of the selection.
770class Q_GUI_EXPORT QAccessibleTextSelectionEvent : public QAccessibleTextCursorEvent
771{
772public:
773 inline QAccessibleTextSelectionEvent(QObject *obj, int start, int end)
774 : QAccessibleTextCursorEvent(obj, (start == -1) ? 0 : end)
775 , m_selectionStart(start), m_selectionEnd(end)
776 {
777 m_type = QAccessible::TextSelectionChanged;
778 }
779 inline QAccessibleTextSelectionEvent(QAccessibleInterface *iface, int start, int end)
780 : QAccessibleTextCursorEvent(iface, (start == -1) ? 0 : end)
781 , m_selectionStart(start), m_selectionEnd(end)
782 {
783 m_type = QAccessible::TextSelectionChanged;
784 }
785
786 ~QAccessibleTextSelectionEvent();
787
788 void setSelection(int start, int end) {
789 m_selectionStart = start;
790 m_selectionEnd = end;
791 }
792
793 int selectionStart() const { return m_selectionStart; }
794 int selectionEnd() const { return m_selectionEnd; }
795
796protected:
797 int m_selectionStart;
798 int m_selectionEnd;
799};
800
801class Q_GUI_EXPORT QAccessibleTextInsertEvent : public QAccessibleTextCursorEvent
802{
803public:
804 inline QAccessibleTextInsertEvent(QObject *obj, int position, const QString &text)
805 : QAccessibleTextCursorEvent(obj, position + text.length())
806 , m_position(position), m_text(text)
807 {
808 m_type = QAccessible::TextInserted;
809 }
810 inline QAccessibleTextInsertEvent(QAccessibleInterface *iface, int position, const QString &text)
811 : QAccessibleTextCursorEvent(iface, position + text.length())
812 , m_position(position), m_text(text)
813 {
814 m_type = QAccessible::TextInserted;
815 }
816
817 ~QAccessibleTextInsertEvent();
818
819 QString textInserted() const {
820 return m_text;
821 }
822 int changePosition() const {
823 return m_position;
824 }
825
826protected:
827 int m_position;
828 QString m_text;
829};
830
831class Q_GUI_EXPORT QAccessibleTextRemoveEvent : public QAccessibleTextCursorEvent
832{
833public:
834 inline QAccessibleTextRemoveEvent(QObject *obj, int position, const QString &text)
835 : QAccessibleTextCursorEvent(obj, position)
836 , m_position(position), m_text(text)
837 {
838 m_type = QAccessible::TextRemoved;
839 }
840 inline QAccessibleTextRemoveEvent(QAccessibleInterface *iface, int position, const QString &text)
841 : QAccessibleTextCursorEvent(iface, position)
842 , m_position(position), m_text(text)
843 {
844 m_type = QAccessible::TextRemoved;
845 }
846
847 ~QAccessibleTextRemoveEvent();
848
849 QString textRemoved() const {
850 return m_text;
851 }
852 int changePosition() const {
853 return m_position;
854 }
855
856protected:
857 int m_position;
858 QString m_text;
859};
860
861class Q_GUI_EXPORT QAccessibleTextUpdateEvent : public QAccessibleTextCursorEvent
862{
863public:
864 inline QAccessibleTextUpdateEvent(QObject *obj, int position, const QString &oldText, const QString &text)
865 : QAccessibleTextCursorEvent(obj, position + text.length())
866 , m_position(position), m_oldText(oldText), m_text(text)
867 {
868 m_type = QAccessible::TextUpdated;
869 }
870 inline QAccessibleTextUpdateEvent(QAccessibleInterface *iface, int position, const QString &oldText, const QString &text)
871 : QAccessibleTextCursorEvent(iface, position + text.length())
872 , m_position(position), m_oldText(oldText), m_text(text)
873 {
874 m_type = QAccessible::TextUpdated;
875 }
876
877 ~QAccessibleTextUpdateEvent();
878
879 QString textRemoved() const {
880 return m_oldText;
881 }
882 QString textInserted() const {
883 return m_text;
884 }
885 int changePosition() const {
886 return m_position;
887 }
888
889protected:
890 int m_position;
891 QString m_oldText;
892 QString m_text;
893};
894
895class Q_GUI_EXPORT QAccessibleValueChangeEvent : public QAccessibleEvent
896{
897public:
898 inline QAccessibleValueChangeEvent(QObject *obj, const QVariant &val)
899 : QAccessibleEvent(obj, QAccessible::InvalidEvent)
900 , m_value(val)
901 {
902 m_type = QAccessible::ValueChanged;
903 }
904 inline QAccessibleValueChangeEvent(QAccessibleInterface *iface, const QVariant &val)
905 : QAccessibleEvent(iface, QAccessible::InvalidEvent)
906 , m_value(val)
907 {
908 m_type = QAccessible::ValueChanged;
909 }
910
911 ~QAccessibleValueChangeEvent();
912
913 void setValue(const QVariant & val) { m_value= val; }
914 QVariant value() const { return m_value; }
915
916protected:
917 QVariant m_value;
918};
919
920class Q_GUI_EXPORT QAccessibleTableModelChangeEvent : public QAccessibleEvent
921{
922public:
923 enum ModelChangeType {
924 ModelReset,
925 DataChanged,
926 RowsInserted,
927 ColumnsInserted,
928 RowsRemoved,
929 ColumnsRemoved
930 };
931
932 inline QAccessibleTableModelChangeEvent(QObject *obj, ModelChangeType changeType)
933 : QAccessibleEvent(obj, QAccessible::InvalidEvent)
934 , m_modelChangeType(changeType)
935 , m_firstRow(-1), m_firstColumn(-1), m_lastRow(-1), m_lastColumn(-1)
936 {
937 m_type = QAccessible::TableModelChanged;
938 }
939 inline QAccessibleTableModelChangeEvent(QAccessibleInterface *iface, ModelChangeType changeType)
940 : QAccessibleEvent(iface, QAccessible::InvalidEvent)
941 , m_modelChangeType(changeType)
942 , m_firstRow(-1), m_firstColumn(-1), m_lastRow(-1), m_lastColumn(-1)
943 {
944 m_type = QAccessible::TableModelChanged;
945 }
946
947 ~QAccessibleTableModelChangeEvent();
948
949 void setModelChangeType(ModelChangeType changeType) { m_modelChangeType = changeType; }
950 ModelChangeType modelChangeType() const { return m_modelChangeType; }
951
952 void setFirstRow(int row) { m_firstRow = row; }
953 void setFirstColumn(int col) { m_firstColumn = col; }
954 void setLastRow(int row) { m_lastRow = row; }
955 void setLastColumn(int col) { m_lastColumn = col; }
956 int firstRow() const { return m_firstRow; }
957 int firstColumn() const { return m_firstColumn; }
958 int lastRow() const { return m_lastRow; }
959 int lastColumn() const { return m_lastColumn; }
960
961protected:
962 ModelChangeType m_modelChangeType;
963 int m_firstRow;
964 int m_firstColumn;
965 int m_lastRow;
966 int m_lastColumn;
967};
968
969#ifndef Q_CLANG_QDOC
970#define QAccessibleInterface_iid "org.qt-project.Qt.QAccessibleInterface"
971Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
972#endif
973
974Q_GUI_EXPORT const char *qAccessibleRoleString(QAccessible::Role role);
975Q_GUI_EXPORT const char *qAccessibleEventString(QAccessible::Event event);
976Q_GUI_EXPORT QString qAccessibleLocalizedActionDescription(const QString &actionName);
977
978#ifndef QT_NO_DEBUG_STREAM
979Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleInterface *iface);
980Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleEvent &ev);
981#endif
982
983#if QT_DEPRECATED_SINCE(5, 0)
984inline void QAccessible::updateAccessibility(QObject *object, int child, Event reason)
985{
986 Q_ASSERT(object);
987
988 QAccessibleEvent ev(object, reason);
989 ev.setChild(child);
990 updateAccessibility(&ev);
991}
992#endif
993
994QT_END_NAMESPACE
995
996#endif // QACCESSIBLE_H
997#endif //!QT_NO_ACCESSIBILITY
998