1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
7 ** This file is part of the QtGui module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
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>
59 #ifndef QT_NO_ACCESSIBILITY
61 class QAccessibleInterface;
64 // We need to inherit QObject to expose the enums to QML.
65 class Q_GUI_EXPORT QAccessible
71 Q_ENUMS(Role Event State)
77 ForegroundChanged = 0x0003,
80 PopupMenuStart = 0x0006,
81 PopupMenuEnd = 0x0007,
82 ContextHelpStart = 0x000C,
83 ContextHelpEnd = 0x000D,
84 DragDropStart = 0x000E,
88 ScrollingStart = 0x0012,
89 ScrollingEnd = 0x0013,
93 // Values from IAccessible2
94 ActionChanged = 0x0101,
95 ActiveDescendantChanged = 0x0102,
96 AttributeChanged = 0x0103,
97 DocumentContentChanged = 0x0104,
98 DocumentLoadComplete = 0x0105,
99 DocumentLoadStopped = 0x0106,
100 DocumentReload = 0x0107,
101 HyperlinkEndIndexChanged = 0x0108,
102 HyperlinkNumberOfAnchorsChanged = 0x0109,
103 HyperlinkSelectedLinkChanged = 0x010A,
104 HypertextLinkActivated = 0x010B,
105 HypertextLinkSelected = 0x010C,
106 HyperlinkStartIndexChanged = 0x010D,
107 HypertextChanged = 0x010E,
108 HypertextNLinksChanged = 0x010F,
109 ObjectAttributeChanged = 0x0110,
110 PageChanged = 0x0111,
111 SectionChanged = 0x0112,
112 TableCaptionChanged = 0x0113,
113 TableColumnDescriptionChanged = 0x0114,
114 TableColumnHeaderChanged = 0x0115,
115 TableModelChanged = 0x0116,
116 TableRowDescriptionChanged = 0x0117,
117 TableRowHeaderChanged = 0x0118,
118 TableSummaryChanged = 0x0119,
119 TextAttributeChanged = 0x011A,
120 TextCaretMoved = 0x011B,
121 // TextChanged = 0x011C, is deprecated in IA2, use TextUpdated
122 TextColumnChanged = 0x011D,
123 TextInserted = 0x011E,
124 TextRemoved = 0x011F,
125 TextUpdated = 0x0120,
126 TextSelectionChanged = 0x0121,
127 VisibleDataChanged = 0x0122,
129 ObjectCreated = 0x8000,
130 ObjectDestroyed = 0x8001,
133 ObjectReorder = 0x8004,
136 SelectionAdd = 0x8007,
137 SelectionRemove = 0x8008,
138 SelectionWithin = 0x8009,
139 StateChanged = 0x800A,
140 LocationChanged = 0x800B,
141 NameChanged = 0x800C,
142 DescriptionChanged = 0x800D,
143 ValueChanged = 0x800E,
144 ParentChanged = 0x800F,
145 HelpChanged = 0x80A0,
146 DefaultActionChanged = 0x80B0,
147 AcceleratorChanged = 0x80C0
150 // 64 bit enums seem hard on some platforms (windows...)
151 // which makes using a bit field a sensible alternative
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;
159 quint64 checkable : 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;
168 quint64 expandable : 1;
169 quint64 marqueed : 1;
170 quint64 animated : 1;
171 quint64 invisible : 1;
172 quint64 offscreen : 1;
173 quint64 sizeable : 1;
175 quint64 selfVoicing : 1;
176 quint64 selectable : 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;
185 // IA2 - we chose to not add some IA2 states for now
186 // Below the ones that seem helpful
188 quint64 invalid : 1; // = defunct
189 quint64 editable : 1;
190 quint64 multiLine : 1;
191 quint64 selectableText : 1;
192 quint64 supportsAutoCompletion : 1;
194 // quint64 horizontal : 1;
195 // quint64 vertical : 1;
196 // quint64 invalidEntry : 1;
197 // quint64 managesDescendants : 1;
198 // quint64 singleLine : 1; // we have multi line, this is redundant.
199 // quint64 stale : 1;
200 // quint64 transient : 1;
201 // quint64 pinned : 1;
203 // Apple - see http://mattgemmell.com/2010/12/19/accessibility-for-iphone-and-ipad-apps/
204 // quint64 playsSound : 1;
205 // quint64 summaryElement : 1;
206 // quint64 updatesFrequently : 1;
207 // quint64 adjustable : 1;
208 // more and not included here: http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html
211 // quint64 alertLow : 1;
212 // quint64 alertMedium : 1;
213 // quint64 alertHigh : 1;
216 qMemSet(this, 0, sizeof(State));
226 TitleBar = 0x00000001,
227 MenuBar = 0x00000002,
228 ScrollBar = 0x00000003,
233 AlertMessage = 0x00000008,
236 PopupMenu = 0x0000000B,
237 MenuItem = 0x0000000C,
238 ToolTip = 0x0000000D,
239 Application = 0x0000000E,
240 Document = 0x0000000F,
245 Grouping = 0x00000014,
246 Separator = 0x00000015,
247 ToolBar = 0x00000016,
248 StatusBar = 0x00000017,
250 ColumnHeader = 0x00000019,
251 RowHeader = 0x0000001A,
256 HelpBalloon = 0x0000001F,
257 Assistant = 0x00000020,
259 ListItem = 0x00000022,
261 TreeItem = 0x00000024,
262 PageTab = 0x00000025,
263 PropertyPage = 0x00000026,
264 Indicator = 0x00000027,
265 Graphic = 0x00000028,
266 StaticText = 0x00000029,
267 EditableText = 0x0000002A, // Editable, selectable, etc.
270 PushButton = Button, // deprecated
272 CheckBox = 0x0000002C,
273 RadioButton = 0x0000002D,
274 ComboBox = 0x0000002E,
275 // DropList = 0x0000002F,
276 ProgressBar = 0x00000030,
278 HotkeyField = 0x00000032,
280 SpinBox = 0x00000034,
282 Animation = 0x00000036,
283 Equation = 0x00000037,
284 ButtonDropDown = 0x00000038,
285 ButtonMenu = 0x00000039,
286 ButtonDropGrid = 0x0000003A,
287 Whitespace = 0x0000003B,
288 PageTabList = 0x0000003C,
290 Splitter = 0x0000003E,
291 // Additional Qt roles where enum value does not map directly to MSAA:
292 LayeredPane = 0x0000003F,
293 UserRole = 0x0000ffff
303 UserText = 0x0000ffff
307 Unrelated = 0x00000000,
308 FocusChild = 0x00010000,
310 Labelled = 0x00040000,
311 Controller = 0x00080000,
312 Controlled = 0x00100000,
313 LogicalMask = 0x00ff0000
315 Q_DECLARE_FLAGS(Relation, RelationFlag)
320 EditableTextInterface,
328 typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
329 typedef void(*UpdateHandler)(QObject*, int who, Event reason);
330 typedef void(*RootObjectHandler)(QObject*);
332 static void installFactory(InterfaceFactory);
333 static void removeFactory(InterfaceFactory);
334 static UpdateHandler installUpdateHandler(UpdateHandler);
335 static RootObjectHandler installRootObjectHandler(RootObjectHandler);
337 static QAccessibleInterface *queryAccessibleInterface(QObject *);
338 static void updateAccessibility(QObject *object, int child, Event reason);
339 static bool isActive();
340 static void setRootObject(QObject *object);
342 static void cleanup();
345 static UpdateHandler updateHandler;
346 static RootObjectHandler rootObjectHandler;
349 This class is purely a collection of enums and static functions,
350 it is not supposed to be instantiated.
355 Q_GUI_EXPORT bool operator==(const QAccessible::State &first, const QAccessible::State &second);
357 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
359 class QAccessible2Interface;
360 class QAccessibleTextInterface;
361 class QAccessibleEditableTextInterface;
362 class QAccessibleValueInterface;
363 class QAccessibleActionInterface;
364 class QAccessibleImageInterface;
365 class QAccessibleTableInterface;
366 class QAccessibleTableCellInterface;
368 class Q_GUI_EXPORT QAccessibleInterface
371 virtual ~QAccessibleInterface() {}
372 // check for valid pointers
373 virtual bool isValid() const = 0;
374 virtual QObject *object() const = 0;
375 virtual QWindow *window() const;
378 virtual QAccessible::Relation relationTo(const QAccessibleInterface *other) const;
379 virtual QVector<QPair<QAccessibleInterface*, QAccessible::Relation> > relations() const;
381 virtual QAccessibleInterface *childAt(int x, int y) const = 0;
383 // navigation, hierarchy
384 virtual QAccessibleInterface *parent() const = 0;
385 virtual QAccessibleInterface *child(int index) const = 0;
386 virtual int childCount() const = 0;
387 virtual int indexOfChild(const QAccessibleInterface *) const = 0;
388 virtual int navigate(QAccessible::RelationFlag relation, int index, QAccessibleInterface **iface) const = 0;
390 // properties and state
391 virtual QString text(QAccessible::Text t) const = 0;
392 virtual void setText(QAccessible::Text t, const QString &text) = 0;
393 virtual QRect rect() const = 0;
394 virtual QAccessible::Role role() const = 0;
395 virtual QAccessible::State state() const = 0;
397 virtual QColor foregroundColor() const;
398 virtual QColor backgroundColor() const;
400 inline QAccessibleTextInterface *textInterface()
401 { return reinterpret_cast<QAccessibleTextInterface *>(interface_cast(QAccessible::TextInterface)); }
403 inline QAccessibleEditableTextInterface *editableTextInterface()
404 { return reinterpret_cast<QAccessibleEditableTextInterface *>(interface_cast(QAccessible::EditableTextInterface)); }
406 inline QAccessibleValueInterface *valueInterface()
407 { return reinterpret_cast<QAccessibleValueInterface *>(interface_cast(QAccessible::ValueInterface)); }
409 inline QAccessibleActionInterface *actionInterface()
410 { return reinterpret_cast<QAccessibleActionInterface *>(interface_cast(QAccessible::ActionInterface)); }
412 inline QAccessibleImageInterface *imageInterface()
413 { return reinterpret_cast<QAccessibleImageInterface *>(interface_cast(QAccessible::ImageInterface)); }
415 inline QAccessibleTableInterface *tableInterface()
416 { return reinterpret_cast<QAccessibleTableInterface *>(interface_cast(QAccessible::TableInterface)); }
418 inline QAccessibleTableCellInterface *tableCellInterface()
419 { return reinterpret_cast<QAccessibleTableCellInterface *>(interface_cast(QAccessible::TableCellInterface)); }
421 virtual void virtual_hook(int id, void *data);
423 virtual void *interface_cast(QAccessible::InterfaceType)
428 #define QAccessibleInterface_iid "org.qt-project.Qt.QAccessibleInterface"
429 Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
431 Q_GUI_EXPORT const char *qAccessibleRoleString(QAccessible::Role role);
432 Q_GUI_EXPORT const char *qAccessibleEventString(QAccessible::Event event);
434 #ifndef QT_NO_DEBUG_STREAM
435 Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleInterface *iface);
438 #endif // QT_NO_ACCESSIBILITY
444 #endif // QACCESSIBLE_H