Qt 4.8
qaccessible.h
Go to the documentation of this file.
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 
55 
57 
58 QT_MODULE(Gui)
59 
60 #ifndef QT_NO_ACCESSIBILITY
61 
63 
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  };
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,
265  UserText = 0x0000ffff
266  };
267 
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,
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 
342 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
346 
347 namespace QAccessible2
348 {
350  {
358  };
359 }
360 
369 
371 {
372 public:
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 &params = QVariantList()) = 0;
401 
402  QVariant invokeMethod(Method method, int child = 0,
403  const QVariantList &params = QVariantList());
404 
406  { return qvariant_cast<QSet<Method> >(invokeMethod(ListSupportedMethods)); }
407 
409  { return qvariant_cast<QColor>(invokeMethod(ForegroundColor)); }
410 
413 
415  { return reinterpret_cast<QAccessibleTextInterface *>(cast_helper(QAccessible2::TextInterface)); }
416 
418  { return reinterpret_cast<QAccessibleEditableTextInterface *>(cast_helper(QAccessible2::EditableTextInterface)); }
419 
421  { return reinterpret_cast<QAccessibleValueInterface *>(cast_helper(QAccessible2::ValueInterface)); }
422 
424  { return reinterpret_cast<QAccessibleTableInterface *>(cast_helper(QAccessible2::TableInterface)); }
425 
427  { return reinterpret_cast<QAccessibleActionInterface *>(cast_helper(QAccessible2::ActionInterface)); }
428 
430  { return reinterpret_cast<QAccessibleImageInterface *>(cast_helper(QAccessible2::ImageInterface)); }
431 
433  { return reinterpret_cast<QAccessibleTable2Interface *>(cast_helper(QAccessible2::Table2Interface)); }
434 
435 private:
437 };
438 
440 {
441 public:
442  virtual QVariant invokeMethodEx(Method method, int child, const QVariantList &params) = 0;
443  virtual QVariant virtual_hook(const QVariant &data);
445  { return 0; }
446 };
447 
448 
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;
460 };
461 
462 inline QAccessibleEvent::QAccessibleEvent(Type atype, int achild)
463  : QEvent(atype), c(achild) {}
464 
465 #define QAccessibleInterface_iid "com.trolltech.Qt.QAccessibleInterface"
467 
468 #endif // QT_NO_ACCESSIBILITY
469 
471 
473 
474 #endif // QACCESSIBLE_H
The QVariant class acts like a union for the most common Qt data types.
Definition: qvariant.h:92
The QColor class provides colors based on RGB, HSV or CMYK values.
Definition: qcolor.h:67
The QAccessibleEditableTextInterface class implements support for the IAccessibleEditableText interfa...
Definition: qaccessible2.h:160
The QAccessible2 namespace defines constants relating to IAccessible2-based interfaces.
Definition: qaccessible.h:347
int type
Definition: qmetatype.cpp:239
virtual QAccessible2Interface * interface_cast(QAccessible2::InterfaceType)
Definition: qaccessible.h:444
QAccessibleValueInterface * valueInterface()
Definition: qaccessible.h:420
unsigned char c[8]
Definition: qnumeric_p.h:62
#define QT_END_NAMESPACE
This macro expands to.
Definition: qglobal.h:90
#define QT_MODULE(x)
Definition: qglobal.h:2783
static void invokeMethod(QObject *obj, const char *methodName)
Definition: qtestcase.cpp:979
#define QT_BEGIN_HEADER
Definition: qglobal.h:136
#define Q_DECLARE_FLAGS(Flags, Enum)
The Q_DECLARE_FLAGS() macro expands to.
Definition: qglobal.h:2348
#define Q_GUI_EXPORT
Definition: qglobal.h:1450
StateFlag
This enum type defines bit flags that can be combined to indicate the state of an accessible object...
Definition: qaccessible.h:143
Role
This enum defines the role of an accessible object.
Definition: qaccessible.h:188
QAccessibleEditableTextInterface * editableTextInterface()
Definition: qaccessible.h:417
The QString class provides a Unicode character string.
Definition: qstring.h:83
QAccessibleActionInterface * actionInterface()
Definition: qaccessible.h:426
The QObject class is the base class of all Qt objects.
Definition: qobject.h:111
#define Q_DECLARE_INTERFACE(IFace, IId)
Definition: qobject.h:397
#define QT_BEGIN_NAMESPACE
This macro expands to.
Definition: qglobal.h:89
#define Q_DECLARE_OPERATORS_FOR_FLAGS(Flags)
The Q_DECLARE_OPERATORS_FOR_FLAGS() macro declares global operator|() functions for Flags...
Definition: qglobal.h:2355
The QAccessibleEvent class is used to query addition accessibility information about complex widgets...
Definition: qaccessible.h:449
Event
This enum type defines accessible event types.
Definition: qaccessible.h:67
RelationFlag
This enum type defines bit flags that can be combined to indicate the relationship between two access...
Definition: qaccessible.h:268
Method
This enum describes the possible types of methods that can be invoked on an accessible object...
Definition: qaccessible.h:311
virtual ~QAccessibleInterface()
Destroys the object.
Definition: qaccessible.h:373
QColor foregroundColor()
Definition: qaccessible.h:408
static const char * data(const QByteArray &arr)
#define QAccessibleInterface_iid
Definition: qaccessible.h:465
void setValue(const QString &aText)
Set the description or help text for the given child() to text, thereby answering the request...
Definition: qaccessible.h:455
The State element defines configurations of objects and properties.
The Column item arranges its children vertically.
#define Q_DECLARE_METATYPE(TYPE)
This macro makes the type Type known to QMetaType as long as it provides a public default constructor...
Definition: qmetatype.h:265
QAccessibleImageInterface * imageInterface()
Definition: qaccessible.h:429
The QAccessibleImageInterface class implements support for the IAccessibleImage interface.
Definition: qaccessible2.h:342
Action
This enum describes the possible types of action that can occur.
Definition: qaccessible.h:294
The Row item arranges its children horizontally.
Type
This enum type defines the valid event types in Qt.
Definition: qcoreevent.h:62
QAccessibleTextInterface * textInterface()
Definition: qaccessible.h:414
The QAccessibleTextInterface class implements support for the IAccessibleText interface.
Definition: qaccessible2.h:132
State
Definition: qaudio.h:59
The QAccessibleInterface class defines an interface that exposes information about accessible objects...
Definition: qaccessible.h:370
The QAccessibleActionInterface class implements support for the IAccessibleAction interface...
Definition: qaccessible2.h:329
int key
QList< QVariant > QVariantList
Definition: qvariant.h:443
QAccessibleTable2Interface * table2Interface()
Definition: qaccessible.h:432
static void cleanup()
Definition: qpicture.cpp:1508
The QRect class defines a rectangle in the plane using integer precision.
Definition: qrect.h:58
T qvariant_cast(const QVariant &)
Definition: qvariant.h:571
QColor backgroundColor()
Definition: qaccessible.h:411
The Animation element is the base of all QML animations.
quint16 index
QAccessibleTableInterface * tableInterface()
Definition: qaccessible.h:423
The QAccessibleValueInterface class implements support for the IAccessibleValue interface.
Definition: qaccessible2.h:193
QSet< Method > supportedMethods()
Returns a QSet of QAccessible::Method that are supported by this accessible interface.
Definition: qaccessible.h:405
The QEvent class is the base class of all event classes.
Definition: qcoreevent.h:56
QAccessibleEvent(Type type, int child)
Constructs an accessibility event of the given type, which must be QEvent::AccessibilityDescription o...
Definition: qaccessible.h:462
#define QT_END_HEADER
Definition: qglobal.h:137
static UpdateHandler updateHandler
Definition: qaccessible.h:337
static RootObjectHandler rootObjectHandler
Definition: qaccessible.h:338
QString value() const
Returns the text set using setValue().
Definition: qaccessible.h:454
#define text
Definition: qobjectdefs.h:80
int child() const
Returns the (1-based) index of the child to which the request applies.
Definition: qaccessible.h:453
The QAccessible class provides enums and static functions relating to accessibility.
Definition: qaccessible.h:64
The Text item allows you to add formatted text to a scene.