1// Copyright (C) 2020 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
5#if 0
6// keep existing syncqt header working after the move of the class
7// into qaccessible_base
8#pragma qt_class(QAccessible)
9#endif
10
11#ifndef QACCESSIBLE_H
12#define QACCESSIBLE_H
13#include <QtGui/qtguiglobal.h>
14
15#if QT_CONFIG(accessibility)
16
17#include <QtCore/qcoreapplication.h>
18#include <QtCore/qdebug.h>
19#include <QtCore/qglobal.h>
20#include <QtCore/qlist.h>
21#include <QtCore/qobject.h>
22#include <QtCore/qrect.h>
23#include <QtCore/qset.h>
24#include <QtCore/qvariant.h>
25#include <QtGui/qcolor.h>
26#include <QtGui/qevent.h>
27#include <QtGui/qaccessible_base.h>
28
29QT_BEGIN_NAMESPACE
30
31class QAccessibleInterface;
32class QAccessibleEvent;
33class QWindow;
34class QTextCursor;
35
36class QAccessible2Interface;
37class QAccessibleTextInterface;
38class QAccessibleEditableTextInterface;
39class QAccessibleValueInterface;
40class QAccessibleActionInterface;
41class QAccessibleImageInterface;
42class QAccessibleTableInterface;
43class QAccessibleTableCellInterface;
44class QAccessibleHyperlinkInterface;
45class QAccessibleSelectionInterface;
46class QAccessibleTableModelChangeEvent;
47
48class Q_GUI_EXPORT QAccessibleInterface
49{
50protected:
51 virtual ~QAccessibleInterface();
52
53public:
54 // check for valid pointers
55 virtual bool isValid() const = 0;
56 virtual QObject *object() const = 0;
57 virtual QWindow *window() const;
58
59 // relations
60 virtual QList<QPair<QAccessibleInterface *, QAccessible::Relation>>
61 relations(QAccessible::Relation match = QAccessible::AllRelations) const;
62 virtual QAccessibleInterface *focusChild() const;
63
64 virtual QAccessibleInterface *childAt(int x, int y) const = 0;
65
66 // navigation, hierarchy
67 virtual QAccessibleInterface *parent() const = 0;
68 virtual QAccessibleInterface *child(int index) const = 0;
69 virtual int childCount() const = 0;
70 virtual int indexOfChild(const QAccessibleInterface *) const = 0;
71
72 // properties and state
73 virtual QString text(QAccessible::Text t) const = 0;
74 virtual void setText(QAccessible::Text t, const QString &text) = 0;
75 virtual QRect rect() const = 0;
76 virtual QAccessible::Role role() const = 0;
77 virtual QAccessible::State state() const = 0;
78
79 virtual QColor foregroundColor() const;
80 virtual QColor backgroundColor() const;
81
82 inline QAccessibleTextInterface *textInterface()
83 { return reinterpret_cast<QAccessibleTextInterface *>(interface_cast(QAccessible::TextInterface)); }
84
85 inline QAccessibleEditableTextInterface *editableTextInterface()
86 { return reinterpret_cast<QAccessibleEditableTextInterface *>(interface_cast(QAccessible::EditableTextInterface)); }
87
88 inline QAccessibleValueInterface *valueInterface()
89 { return reinterpret_cast<QAccessibleValueInterface *>(interface_cast(QAccessible::ValueInterface)); }
90
91 inline QAccessibleActionInterface *actionInterface()
92 { return reinterpret_cast<QAccessibleActionInterface *>(interface_cast(QAccessible::ActionInterface)); }
93
94 inline QAccessibleImageInterface *imageInterface()
95 { return reinterpret_cast<QAccessibleImageInterface *>(interface_cast(QAccessible::ImageInterface)); }
96
97 inline QAccessibleTableInterface *tableInterface()
98 { return reinterpret_cast<QAccessibleTableInterface *>(interface_cast(QAccessible::TableInterface)); }
99
100 inline QAccessibleTableCellInterface *tableCellInterface()
101 { return reinterpret_cast<QAccessibleTableCellInterface *>(interface_cast(QAccessible::TableCellInterface)); }
102
103 inline QAccessibleHyperlinkInterface *hyperlinkInterface()
104 { return reinterpret_cast<QAccessibleHyperlinkInterface *>(interface_cast(QAccessible::HyperlinkInterface)); }
105
106 inline QAccessibleSelectionInterface *selectionInterface()
107 { return reinterpret_cast<QAccessibleSelectionInterface *>(interface_cast(QAccessible::SelectionInterface)); }
108
109 virtual void virtual_hook(int id, void *data);
110
111 virtual void *interface_cast(QAccessible::InterfaceType)
112 { return nullptr; }
113
114protected:
115 friend class QAccessibleCache;
116};
117
118class Q_GUI_EXPORT QAccessibleTextInterface
119{
120public:
121 virtual ~QAccessibleTextInterface();
122 // selection
123 virtual void selection(int selectionIndex, int *startOffset, int *endOffset) const = 0;
124 virtual int selectionCount() const = 0;
125 virtual void addSelection(int startOffset, int endOffset) = 0;
126 virtual void removeSelection(int selectionIndex) = 0;
127 virtual void setSelection(int selectionIndex, int startOffset, int endOffset) = 0;
128
129 // cursor
130 virtual int cursorPosition() const = 0;
131 virtual void setCursorPosition(int position) = 0;
132
133 // text
134 virtual QString text(int startOffset, int endOffset) const = 0;
135 virtual QString textBeforeOffset(int offset, QAccessible::TextBoundaryType boundaryType,
136 int *startOffset, int *endOffset) const;
137 virtual QString textAfterOffset(int offset, QAccessible::TextBoundaryType boundaryType,
138 int *startOffset, int *endOffset) const;
139 virtual QString textAtOffset(int offset, QAccessible::TextBoundaryType boundaryType,
140 int *startOffset, int *endOffset) const;
141 virtual int characterCount() const = 0;
142
143 // character <-> geometry
144 virtual QRect characterRect(int offset) const = 0;
145 virtual int offsetAtPoint(const QPoint &point) const = 0;
146
147 virtual void scrollToSubstring(int startIndex, int endIndex) = 0;
148 virtual QString attributes(int offset, int *startOffset, int *endOffset) const = 0;
149};
150
151class Q_GUI_EXPORT QAccessibleEditableTextInterface
152{
153public:
154 virtual ~QAccessibleEditableTextInterface();
155
156 virtual void deleteText(int startOffset, int endOffset) = 0;
157 virtual void insertText(int offset, const QString &text) = 0;
158 virtual void replaceText(int startOffset, int endOffset, const QString &text) = 0;
159};
160
161class Q_GUI_EXPORT QAccessibleValueInterface
162{
163public:
164 virtual ~QAccessibleValueInterface();
165
166 virtual QVariant currentValue() const = 0;
167 virtual void setCurrentValue(const QVariant &value) = 0;
168 virtual QVariant maximumValue() const = 0;
169 virtual QVariant minimumValue() const = 0;
170 virtual QVariant minimumStepSize() const = 0;
171};
172
173class Q_GUI_EXPORT QAccessibleTableCellInterface
174{
175public:
176 virtual ~QAccessibleTableCellInterface();
177
178 virtual bool isSelected() const = 0;
179
180 virtual QList<QAccessibleInterface*> columnHeaderCells() const = 0;
181 virtual QList<QAccessibleInterface*> rowHeaderCells() const = 0;
182 virtual int columnIndex() const = 0;
183 virtual int rowIndex() const = 0;
184 virtual int columnExtent() const = 0;
185 virtual int rowExtent() const = 0;
186
187 virtual QAccessibleInterface* table() const = 0;
188};
189
190class Q_GUI_EXPORT QAccessibleTableInterface
191{
192public:
193 virtual ~QAccessibleTableInterface();
194
195 virtual QAccessibleInterface *caption() const = 0;
196 virtual QAccessibleInterface *summary() const = 0;
197
198 virtual QAccessibleInterface *cellAt (int row, int column) const = 0;
199 virtual int selectedCellCount() const = 0;
200 virtual QList<QAccessibleInterface*> selectedCells() const = 0;
201
202 virtual QString columnDescription(int column) const = 0;
203 virtual QString rowDescription(int row) const = 0;
204 virtual int selectedColumnCount() const = 0;
205 virtual int selectedRowCount() const = 0;
206 virtual int columnCount() const = 0;
207 virtual int rowCount() const = 0;
208 virtual QList<int> selectedColumns() const = 0;
209 virtual QList<int> selectedRows() const = 0;
210 virtual bool isColumnSelected(int column) const = 0;
211 virtual bool isRowSelected(int row) const = 0;
212 virtual bool selectRow(int row) = 0;
213 virtual bool selectColumn(int column) = 0;
214 virtual bool unselectRow(int row) = 0;
215 virtual bool unselectColumn(int column) = 0;
216
217 virtual void modelChange(QAccessibleTableModelChangeEvent *event) = 0;
218
219protected:
220friend class QAbstractItemView;
221friend class QAbstractItemViewPrivate;
222};
223
224class Q_GUI_EXPORT QAccessibleActionInterface
225{
226 Q_DECLARE_TR_FUNCTIONS(QAccessibleActionInterface)
227public:
228 virtual ~QAccessibleActionInterface();
229
230 virtual QStringList actionNames() const = 0;
231 virtual QString localizedActionName(const QString &name) const;
232 virtual QString localizedActionDescription(const QString &name) const;
233 virtual void doAction(const QString &actionName) = 0;
234 virtual QStringList keyBindingsForAction(const QString &actionName) const = 0;
235
236 static const QString &pressAction();
237 static const QString &increaseAction();
238 static const QString &decreaseAction();
239 static const QString &showMenuAction();
240 static const QString &setFocusAction();
241 static const QString &toggleAction();
242 static QString scrollLeftAction();
243 static QString scrollRightAction();
244 static QString scrollUpAction();
245 static QString scrollDownAction();
246 static QString nextPageAction();
247 static QString previousPageAction();
248};
249
250class Q_GUI_EXPORT QAccessibleImageInterface
251{
252public:
253 virtual ~QAccessibleImageInterface();
254
255 virtual QString imageDescription() const = 0;
256 virtual QSize imageSize() const = 0;
257 virtual QPoint imagePosition() const = 0;
258};
259
260class Q_GUI_EXPORT QAccessibleHyperlinkInterface
261{
262public:
263 virtual ~QAccessibleHyperlinkInterface();
264
265 virtual QString anchor() const = 0;
266 virtual QString anchorTarget() const = 0;
267 virtual int startIndex() const = 0;
268 virtual int endIndex() const = 0;
269 virtual bool isValid() const = 0;
270};
271
272class Q_GUI_EXPORT QAccessibleSelectionInterface
273{
274public:
275 virtual ~QAccessibleSelectionInterface();
276
277 virtual int selectedItemCount() const = 0;
278 virtual QList<QAccessibleInterface*> selectedItems() const = 0;
279 virtual QAccessibleInterface* selectedItem(int selectionIndex) const;
280 virtual bool isSelected(QAccessibleInterface *childItem) const;
281 virtual bool select(QAccessibleInterface *childItem) = 0;
282 virtual bool unselect(QAccessibleInterface *childItem) = 0;
283 virtual bool selectAll() = 0;
284 virtual bool clear() = 0;
285};
286
287class Q_GUI_EXPORT QAccessibleEvent
288{
289 Q_DISABLE_COPY(QAccessibleEvent)
290public:
291
292 inline QAccessibleEvent(QObject *obj, QAccessible::Event typ)
293 : m_type(typ), m_object(obj), m_child(-1)
294 {
295 Q_ASSERT(obj);
296 // All events below have a subclass of QAccessibleEvent.
297 // Use the subclass, since it's expected that it's possible to cast to that.
298 Q_ASSERT(m_type != QAccessible::ValueChanged);
299 Q_ASSERT(m_type != QAccessible::StateChanged);
300 Q_ASSERT(m_type != QAccessible::TextCaretMoved);
301 Q_ASSERT(m_type != QAccessible::TextSelectionChanged);
302 Q_ASSERT(m_type != QAccessible::TextInserted);
303 Q_ASSERT(m_type != QAccessible::TextRemoved);
304 Q_ASSERT(m_type != QAccessible::TextUpdated);
305 Q_ASSERT(m_type != QAccessible::TableModelChanged);
306 }
307
308 inline QAccessibleEvent(QAccessibleInterface *iface, QAccessible::Event typ)
309 : m_type(typ)
310 {
311 Q_ASSERT(iface);
312 Q_ASSERT(m_type != QAccessible::ValueChanged);
313 Q_ASSERT(m_type != QAccessible::StateChanged);
314 Q_ASSERT(m_type != QAccessible::TextCaretMoved);
315 Q_ASSERT(m_type != QAccessible::TextSelectionChanged);
316 Q_ASSERT(m_type != QAccessible::TextInserted);
317 Q_ASSERT(m_type != QAccessible::TextRemoved);
318 Q_ASSERT(m_type != QAccessible::TextUpdated);
319 Q_ASSERT(m_type != QAccessible::TableModelChanged);
320 m_uniqueId = QAccessible::uniqueId(iface);
321 m_object = iface->object();
322 }
323
324 virtual ~QAccessibleEvent();
325
326 QAccessible::Event type() const { return m_type; }
327 QObject *object() const { return m_object; }
328 QAccessible::Id uniqueId() const;
329
330 void setChild(int chld) { m_child = chld; }
331 int child() const { return m_child; }
332
333 virtual QAccessibleInterface *accessibleInterface() const;
334
335protected:
336 QAccessible::Event m_type;
337 QObject *m_object;
338 union {
339 int m_child;
340 QAccessible::Id m_uniqueId;
341 };
342
343 friend class QTestAccessibility;
344};
345
346class Q_GUI_EXPORT QAccessibleStateChangeEvent :public QAccessibleEvent
347{
348public:
349 inline QAccessibleStateChangeEvent(QObject *obj, QAccessible::State state)
350 : QAccessibleEvent(obj, QAccessible::InvalidEvent), m_changedStates(state)
351 {
352 m_type = QAccessible::StateChanged;
353 }
354 inline QAccessibleStateChangeEvent(QAccessibleInterface *iface, QAccessible::State state)
355 : QAccessibleEvent(iface, QAccessible::InvalidEvent), m_changedStates(state)
356 {
357 m_type = QAccessible::StateChanged;
358 }
359 ~QAccessibleStateChangeEvent();
360
361 QAccessible::State changedStates() const {
362 return m_changedStates;
363 }
364
365protected:
366 QAccessible::State m_changedStates;
367};
368
369// Update the cursor and optionally the selection.
370class Q_GUI_EXPORT QAccessibleTextCursorEvent : public QAccessibleEvent
371{
372public:
373 inline QAccessibleTextCursorEvent(QObject *obj, int cursorPos)
374 : QAccessibleEvent(obj, QAccessible::InvalidEvent)
375 , m_cursorPosition(cursorPos)
376 {
377 m_type = QAccessible::TextCaretMoved;
378 }
379 inline QAccessibleTextCursorEvent(QAccessibleInterface *iface, int cursorPos)
380 : QAccessibleEvent(iface, QAccessible::InvalidEvent)
381 , m_cursorPosition(cursorPos)
382 {
383 m_type = QAccessible::TextCaretMoved;
384 }
385
386 ~QAccessibleTextCursorEvent();
387
388 void setCursorPosition(int position) { m_cursorPosition = position; }
389 int cursorPosition() const { return m_cursorPosition; }
390
391protected:
392 int m_cursorPosition;
393};
394
395// Updates the cursor position simultaneously. By default the cursor is set to the end of the selection.
396class Q_GUI_EXPORT QAccessibleTextSelectionEvent : public QAccessibleTextCursorEvent
397{
398public:
399 inline QAccessibleTextSelectionEvent(QObject *obj, int start, int end)
400 : QAccessibleTextCursorEvent(obj, (start == -1) ? 0 : end)
401 , m_selectionStart(start), m_selectionEnd(end)
402 {
403 m_type = QAccessible::TextSelectionChanged;
404 }
405 inline QAccessibleTextSelectionEvent(QAccessibleInterface *iface, int start, int end)
406 : QAccessibleTextCursorEvent(iface, (start == -1) ? 0 : end)
407 , m_selectionStart(start), m_selectionEnd(end)
408 {
409 m_type = QAccessible::TextSelectionChanged;
410 }
411
412 ~QAccessibleTextSelectionEvent();
413
414 void setSelection(int start, int end) {
415 m_selectionStart = start;
416 m_selectionEnd = end;
417 }
418
419 int selectionStart() const { return m_selectionStart; }
420 int selectionEnd() const { return m_selectionEnd; }
421
422protected:
423 int m_selectionStart;
424 int m_selectionEnd;
425};
426
427class Q_GUI_EXPORT QAccessibleTextInsertEvent : public QAccessibleTextCursorEvent
428{
429public:
430 inline QAccessibleTextInsertEvent(QObject *obj, int position, const QString &text)
431 : QAccessibleTextCursorEvent(obj, position + int(text.size()))
432 , m_position(position), m_text(text)
433 {
434 m_type = QAccessible::TextInserted;
435 }
436 inline QAccessibleTextInsertEvent(QAccessibleInterface *iface, int position, const QString &text)
437 : QAccessibleTextCursorEvent(iface, position + int(text.size()))
438 , m_position(position), m_text(text)
439 {
440 m_type = QAccessible::TextInserted;
441 }
442
443 ~QAccessibleTextInsertEvent();
444
445 QString textInserted() const {
446 return m_text;
447 }
448 int changePosition() const {
449 return m_position;
450 }
451
452protected:
453 int m_position;
454 QString m_text;
455};
456
457class Q_GUI_EXPORT QAccessibleTextRemoveEvent : public QAccessibleTextCursorEvent
458{
459public:
460 inline QAccessibleTextRemoveEvent(QObject *obj, int position, const QString &text)
461 : QAccessibleTextCursorEvent(obj, position)
462 , m_position(position), m_text(text)
463 {
464 m_type = QAccessible::TextRemoved;
465 }
466 inline QAccessibleTextRemoveEvent(QAccessibleInterface *iface, int position, const QString &text)
467 : QAccessibleTextCursorEvent(iface, position)
468 , m_position(position), m_text(text)
469 {
470 m_type = QAccessible::TextRemoved;
471 }
472
473 ~QAccessibleTextRemoveEvent();
474
475 QString textRemoved() const {
476 return m_text;
477 }
478 int changePosition() const {
479 return m_position;
480 }
481
482protected:
483 int m_position;
484 QString m_text;
485};
486
487class Q_GUI_EXPORT QAccessibleTextUpdateEvent : public QAccessibleTextCursorEvent
488{
489public:
490 inline QAccessibleTextUpdateEvent(QObject *obj, int position, const QString &oldText, const QString &text)
491 : QAccessibleTextCursorEvent(obj, position + int(text.size()))
492 , m_position(position), m_oldText(oldText), m_text(text)
493 {
494 m_type = QAccessible::TextUpdated;
495 }
496 inline QAccessibleTextUpdateEvent(QAccessibleInterface *iface, int position, const QString &oldText, const QString &text)
497 : QAccessibleTextCursorEvent(iface, position + int(text.size()))
498 , m_position(position), m_oldText(oldText), m_text(text)
499 {
500 m_type = QAccessible::TextUpdated;
501 }
502
503 ~QAccessibleTextUpdateEvent();
504
505 QString textRemoved() const {
506 return m_oldText;
507 }
508 QString textInserted() const {
509 return m_text;
510 }
511 int changePosition() const {
512 return m_position;
513 }
514
515protected:
516 int m_position;
517 QString m_oldText;
518 QString m_text;
519};
520
521class Q_GUI_EXPORT QAccessibleValueChangeEvent : public QAccessibleEvent
522{
523public:
524 inline QAccessibleValueChangeEvent(QObject *obj, const QVariant &val)
525 : QAccessibleEvent(obj, QAccessible::InvalidEvent)
526 , m_value(val)
527 {
528 m_type = QAccessible::ValueChanged;
529 }
530 inline QAccessibleValueChangeEvent(QAccessibleInterface *iface, const QVariant &val)
531 : QAccessibleEvent(iface, QAccessible::InvalidEvent)
532 , m_value(val)
533 {
534 m_type = QAccessible::ValueChanged;
535 }
536
537 ~QAccessibleValueChangeEvent();
538
539 void setValue(const QVariant & val) { m_value= val; }
540 QVariant value() const { return m_value; }
541
542protected:
543 QVariant m_value;
544};
545
546class Q_GUI_EXPORT QAccessibleTableModelChangeEvent : public QAccessibleEvent
547{
548public:
549 enum ModelChangeType {
550 ModelReset,
551 DataChanged,
552 RowsInserted,
553 ColumnsInserted,
554 RowsRemoved,
555 ColumnsRemoved
556 };
557
558 inline QAccessibleTableModelChangeEvent(QObject *obj, ModelChangeType changeType)
559 : QAccessibleEvent(obj, QAccessible::InvalidEvent)
560 , m_modelChangeType(changeType)
561 , m_firstRow(-1), m_firstColumn(-1), m_lastRow(-1), m_lastColumn(-1)
562 {
563 m_type = QAccessible::TableModelChanged;
564 }
565 inline QAccessibleTableModelChangeEvent(QAccessibleInterface *iface, ModelChangeType changeType)
566 : QAccessibleEvent(iface, QAccessible::InvalidEvent)
567 , m_modelChangeType(changeType)
568 , m_firstRow(-1), m_firstColumn(-1), m_lastRow(-1), m_lastColumn(-1)
569 {
570 m_type = QAccessible::TableModelChanged;
571 }
572
573 ~QAccessibleTableModelChangeEvent();
574
575 void setModelChangeType(ModelChangeType changeType) { m_modelChangeType = changeType; }
576 ModelChangeType modelChangeType() const { return m_modelChangeType; }
577
578 void setFirstRow(int row) { m_firstRow = row; }
579 void setFirstColumn(int col) { m_firstColumn = col; }
580 void setLastRow(int row) { m_lastRow = row; }
581 void setLastColumn(int col) { m_lastColumn = col; }
582 int firstRow() const { return m_firstRow; }
583 int firstColumn() const { return m_firstColumn; }
584 int lastRow() const { return m_lastRow; }
585 int lastColumn() const { return m_lastColumn; }
586
587protected:
588 ModelChangeType m_modelChangeType;
589 int m_firstRow;
590 int m_firstColumn;
591 int m_lastRow;
592 int m_lastColumn;
593};
594
595#ifndef Q_QDOC
596#define QAccessibleInterface_iid "org.qt-project.Qt.QAccessibleInterface"
597Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
598#endif
599
600Q_GUI_EXPORT const char *qAccessibleRoleString(QAccessible::Role role);
601Q_GUI_EXPORT const char *qAccessibleEventString(QAccessible::Event event);
602Q_GUI_EXPORT QString qAccessibleLocalizedActionDescription(const QString &actionName);
603
604#ifndef QT_NO_DEBUG_STREAM
605Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleInterface *iface);
606Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleEvent &ev);
607#endif
608
609QT_END_NAMESPACE
610
611#endif // QT_CONFIG(accessibility)
612#endif // QACCESSIBLE_H
613

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