src/gui/accessible/qaccessible.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  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
  59 #ifndef QT_NO_ACCESSIBILITY
  60
  61 class QAccessibleInterface;
  62 class QWindow;
  63
  64 // We need to inherit QObject to expose the enums to QML.
  65 class Q_GUI_EXPORT QAccessible
  66 #ifndef qdoc
  67         :public QObject
  68 #endif
  69 {
  70     Q_OBJECT
  71     Q_ENUMS(Role Event State)
  72 public:
  73
  74     enum Event {
  75         SoundPlayed          = 0x0001,
  76         Alert                = 0x0002,
  77         ForegroundChanged    = 0x0003,
  78         MenuStart            = 0x0004,
  79         MenuEnd              = 0x0005,
  80         PopupMenuStart       = 0x0006,
  81         PopupMenuEnd         = 0x0007,
  82         ContextHelpStart     = 0x000C,
  83         ContextHelpEnd       = 0x000D,
  84         DragDropStart        = 0x000E,
  85         DragDropEnd          = 0x000F,
  86         DialogStart          = 0x0010,
  87         DialogEnd            = 0x0011,
  88         ScrollingStart       = 0x0012,
  89         ScrollingEnd         = 0x0013,
  90
  91         MenuCommand          = 0x0018,
  92
  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,
 128
 129         ObjectCreated        = 0x8000,
 130         ObjectDestroyed      = 0x8001,
 131         ObjectShow           = 0x8002,
 132         ObjectHide           = 0x8003,
 133         ObjectReorder        = 0x8004,
 134         Focus                = 0x8005,
 135         Selection            = 0x8006,
 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
 148     };
 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 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;
 202
 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
 209
 210         // MSAA
 211         // quint64 alertLow : 1;
 212         // quint64 alertMedium : 1;
 213         // quint64 alertHigh : 1;
 214
 215         State() {
 216             qMemSet(this, 0, sizeof(State));
 217         }
 218     };
 219
 220
 221
 222
 223
 224     enum Role {
 225         NoRole         = 0x00000000,
 226         TitleBar       = 0x00000001,
 227         MenuBar        = 0x00000002,
 228         ScrollBar      = 0x00000003,
 229         Grip           = 0x00000004,
 230         Sound          = 0x00000005,
 231         Cursor         = 0x00000006,
 232         Caret          = 0x00000007,
 233         AlertMessage   = 0x00000008,
 234         Window         = 0x00000009,
 235         Client         = 0x0000000A,
 236         PopupMenu      = 0x0000000B,
 237         MenuItem       = 0x0000000C,
 238         ToolTip        = 0x0000000D,
 239         Application    = 0x0000000E,
 240         Document       = 0x0000000F,
 241         Pane           = 0x00000010,
 242         Chart          = 0x00000011,
 243         Dialog         = 0x00000012,
 244         Border         = 0x00000013,
 245         Grouping       = 0x00000014,
 246         Separator      = 0x00000015,
 247         ToolBar        = 0x00000016,
 248         StatusBar      = 0x00000017,
 249         Table          = 0x00000018,
 250         ColumnHeader   = 0x00000019,
 251         RowHeader      = 0x0000001A,
 252         Column         = 0x0000001B,
 253         Row            = 0x0000001C,
 254         Cell           = 0x0000001D,
 255         Link           = 0x0000001E,
 256         HelpBalloon    = 0x0000001F,
 257         Assistant      = 0x00000020,
 258         List           = 0x00000021,
 259         ListItem       = 0x00000022,
 260         Tree           = 0x00000023,
 261         TreeItem       = 0x00000024,
 262         PageTab        = 0x00000025,
 263         PropertyPage   = 0x00000026,
 264         Indicator      = 0x00000027,
 265         Graphic        = 0x00000028,
 266         StaticText     = 0x00000029,
 267         EditableText   = 0x0000002A,  // Editable, selectable, etc.
 268         Button         = 0x0000002B,
 269 #ifndef qdoc
 270         PushButton     = Button, // deprecated
 271 #endif
 272         CheckBox       = 0x0000002C,
 273         RadioButton    = 0x0000002D,
 274         ComboBox       = 0x0000002E,
 275         // DropList       = 0x0000002F,
 276         ProgressBar    = 0x00000030,
 277         Dial           = 0x00000031,
 278         HotkeyField    = 0x00000032,
 279         Slider         = 0x00000033,
 280         SpinBox        = 0x00000034,
 281         Canvas         = 0x00000035,
 282         Animation      = 0x00000036,
 283         Equation       = 0x00000037,
 284         ButtonDropDown = 0x00000038,
 285         ButtonMenu     = 0x00000039,
 286         ButtonDropGrid = 0x0000003A,
 287         Whitespace     = 0x0000003B,
 288         PageTabList    = 0x0000003C,
 289         Clock          = 0x0000003D,
 290         Splitter       = 0x0000003E,
 291         // Additional Qt roles where enum value does not map directly to MSAA:
 292         LayeredPane    = 0x0000003F,
 293         UserRole       = 0x0000ffff
 294     };
 295
 296     enum Text {
 297         Name         = 0,
 298         Description,
 299         Value,
 300         Help,
 301         Accelerator,
 302         DebugDescription,
 303         UserText     = 0x0000ffff
 304     };
 305
 306     enum RelationFlag {
 307         Unrelated     = 0x00000000,
 308         FocusChild    = 0x00010000,
 309         Label         = 0x00020000,
 310         Labelled      = 0x00040000,
 311         Controller    = 0x00080000,
 312         Controlled    = 0x00100000,
 313         LogicalMask   = 0x00ff0000
 314     };
 315     Q_DECLARE_FLAGS(Relation, RelationFlag)
 316
 317     enum InterfaceType
 318     {
 319         TextInterface,
 320         EditableTextInterface,
 321         ValueInterface,
 322         ActionInterface,
 323         ImageInterface,
 324         TableInterface,
 325         TableCellInterface
 326     };
 327
 328     typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
 329     typedef void(*UpdateHandler)(QObject*, int who, Event reason);
 330     typedef void(*RootObjectHandler)(QObject*);
 331
 332     static void installFactory(InterfaceFactory);
 333     static void removeFactory(InterfaceFactory);
 334     static UpdateHandler installUpdateHandler(UpdateHandler);
 335     static RootObjectHandler installRootObjectHandler(RootObjectHandler);
 336
 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);
 341
 342     static void cleanup();
 343
 344 private:
 345     static UpdateHandler updateHandler;
 346     static RootObjectHandler rootObjectHandler;
 347
 348     /*! @internal
 349       This class is purely a collection of enums and static functions,
 350       it is not supposed to be instantiated.
 351     */
 352     QAccessible() {}
 353 };
 354
 355 Q_GUI_EXPORT bool operator==(const QAccessible::State &first, const QAccessible::State &second);
 356
 357 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
 358
 359 class QAccessible2Interface;
 360 class QAccessibleTextInterface;
 361 class QAccessibleEditableTextInterface;
 362 class QAccessibleValueInterface;
 363 class QAccessibleActionInterface;
 364 class QAccessibleImageInterface;
 365 class QAccessibleTableInterface;
 366 class QAccessibleTableCellInterface;
 367
 368 class Q_GUI_EXPORT QAccessibleInterface
 369 {
 370 public:
 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;
 376
 377     // relations
 378     virtual QAccessible::Relation relationTo(const QAccessibleInterface *other) const;
 379     virtual QVector<QPair<QAccessibleInterface*, QAccessible::Relation> > relations() const;
 380
 381     virtual QAccessibleInterface *childAt(int x, int y) const = 0;
 382
 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;
 389
 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;
 396
 397     virtual QColor foregroundColor() const;
 398     virtual QColor backgroundColor() const;
 399
 400     inline QAccessibleTextInterface *textInterface()
 401     { return reinterpret_cast<QAccessibleTextInterface *>(interface_cast(QAccessible::TextInterface)); }
 402
 403     inline QAccessibleEditableTextInterface *editableTextInterface()
 404     { return reinterpret_cast<QAccessibleEditableTextInterface *>(interface_cast(QAccessible::EditableTextInterface)); }
 405
 406     inline QAccessibleValueInterface *valueInterface()
 407     { return reinterpret_cast<QAccessibleValueInterface *>(interface_cast(QAccessible::ValueInterface)); }
 408
 409     inline QAccessibleActionInterface *actionInterface()
 410     { return reinterpret_cast<QAccessibleActionInterface *>(interface_cast(QAccessible::ActionInterface)); }
 411
 412     inline QAccessibleImageInterface *imageInterface()
 413     { return reinterpret_cast<QAccessibleImageInterface *>(interface_cast(QAccessible::ImageInterface)); }
 414
 415     inline QAccessibleTableInterface *tableInterface()
 416     { return reinterpret_cast<QAccessibleTableInterface *>(interface_cast(QAccessible::TableInterface)); }
 417
 418     inline QAccessibleTableCellInterface *tableCellInterface()
 419     { return reinterpret_cast<QAccessibleTableCellInterface *>(interface_cast(QAccessible::TableCellInterface)); }
 420
 421     virtual void virtual_hook(int id, void *data);
 422
 423     virtual void *interface_cast(QAccessible::InterfaceType)
 424     { return 0; }
 425 private:
 426 };
 427
 428 #define QAccessibleInterface_iid "org.qt-project.Qt.QAccessibleInterface"
 429 Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
 430
 431 Q_GUI_EXPORT const char *qAccessibleRoleString(QAccessible::Role role);
 432 Q_GUI_EXPORT const char *qAccessibleEventString(QAccessible::Event event);
 433
 434 #ifndef QT_NO_DEBUG_STREAM
 435 Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleInterface *iface);
 436 #endif
 437
 438 #endif // QT_NO_ACCESSIBILITY
 439
 440 QT_END_NAMESPACE
 441
 442 QT_END_HEADER
 443
 444 #endif // QACCESSIBLE_H