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 QAccessibleEvent;
  63 class QWindow;
  64
  65 // We need to inherit QObject to expose the enums to QML.
  66 class Q_GUI_EXPORT QAccessible
  67 #ifndef qdoc
  68         :public QObject
  69 #endif
  70 {
  71     Q_OBJECT
  72     Q_ENUMS(Role Event State)
  73 public:
  74
  75     enum Event {
  76         SoundPlayed          = 0x0001,
  77         Alert                = 0x0002,
  78         ForegroundChanged    = 0x0003,
  79         MenuStart            = 0x0004,
  80         MenuEnd              = 0x0005,
  81         PopupMenuStart       = 0x0006,
  82         PopupMenuEnd         = 0x0007,
  83         ContextHelpStart     = 0x000C,
  84         ContextHelpEnd       = 0x000D,
  85         DragDropStart        = 0x000E,
  86         DragDropEnd          = 0x000F,
  87         DialogStart          = 0x0010,
  88         DialogEnd            = 0x0011,
  89         ScrollingStart       = 0x0012,
  90         ScrollingEnd         = 0x0013,
  91
  92         MenuCommand          = 0x0018,
  93
  94         // Values from IAccessible2
  95         ActionChanged                    = 0x0101,
  96         ActiveDescendantChanged          = 0x0102,
  97         AttributeChanged                 = 0x0103,
  98         DocumentContentChanged           = 0x0104,
  99         DocumentLoadComplete             = 0x0105,
 100         DocumentLoadStopped              = 0x0106,
 101         DocumentReload                   = 0x0107,
 102         HyperlinkEndIndexChanged         = 0x0108,
 103         HyperlinkNumberOfAnchorsChanged  = 0x0109,
 104         HyperlinkSelectedLinkChanged     = 0x010A,
 105         HypertextLinkActivated           = 0x010B,
 106         HypertextLinkSelected            = 0x010C,
 107         HyperlinkStartIndexChanged       = 0x010D,
 108         HypertextChanged                 = 0x010E,
 109         HypertextNLinksChanged           = 0x010F,
 110         ObjectAttributeChanged           = 0x0110,
 111         PageChanged                      = 0x0111,
 112         SectionChanged                   = 0x0112,
 113         TableCaptionChanged              = 0x0113,
 114         TableColumnDescriptionChanged    = 0x0114,
 115         TableColumnHeaderChanged         = 0x0115,
 116         TableModelChanged                = 0x0116,
 117         TableRowDescriptionChanged       = 0x0117,
 118         TableRowHeaderChanged            = 0x0118,
 119         TableSummaryChanged              = 0x0119,
 120         TextAttributeChanged             = 0x011A,
 121         TextCaretMoved                   = 0x011B,
 122         // TextChanged = 0x011C, is deprecated in IA2, use TextUpdated
 123         TextColumnChanged                = 0x011D,
 124         TextInserted                     = 0x011E,
 125         TextRemoved                      = 0x011F,
 126         TextUpdated                      = 0x0120,
 127         TextSelectionChanged             = 0x0121,
 128         VisibleDataChanged               = 0x0122,
 129
 130         ObjectCreated        = 0x8000,
 131         ObjectDestroyed      = 0x8001,
 132         ObjectShow           = 0x8002,
 133         ObjectHide           = 0x8003,
 134         ObjectReorder        = 0x8004,
 135         Focus                = 0x8005,
 136         Selection            = 0x8006,
 137         SelectionAdd         = 0x8007,
 138         SelectionRemove      = 0x8008,
 139         SelectionWithin      = 0x8009,
 140         StateChanged         = 0x800A,
 141         LocationChanged      = 0x800B,
 142         NameChanged          = 0x800C,
 143         DescriptionChanged   = 0x800D,
 144         ValueChanged         = 0x800E,
 145         ParentChanged        = 0x800F,
 146         HelpChanged          = 0x80A0,
 147         DefaultActionChanged = 0x80B0,
 148         AcceleratorChanged   = 0x80C0
 149     };
 150
 151     // 64 bit enums seem hard on some platforms (windows...)
 152     // which makes using a bit field a sensible alternative
 153     struct State {
 154         // http://msdn.microsoft.com/en-us/library/ms697270.aspx
 155         quint64 disabled : 1; // used to be Unavailable
 156         quint64 selected : 1;
 157         quint64 focusable : 1;
 158         quint64 focused : 1;
 159         quint64 pressed : 1;
 160         quint64 checkable : 1;
 161         quint64 checked : 1;
 162         quint64 checkStateMixed : 1; // used to be Mixed
 163         quint64 readOnly : 1;
 164         quint64 hotTracked : 1;
 165         quint64 defaultButton : 1;
 166         quint64 expanded : 1;
 167         quint64 collapsed : 1;
 168         quint64 busy : 1;
 169         quint64 expandable : 1;
 170         quint64 marqueed : 1;
 171         quint64 animated : 1;
 172         quint64 invisible : 1;
 173         quint64 offscreen : 1;
 174         quint64 sizeable : 1;
 175         quint64 movable : 1;
 176         quint64 selfVoicing : 1;
 177         quint64 selectable : 1;
 178         quint64 linked : 1;
 179         quint64 traversed : 1;
 180         quint64 multiSelectable : 1;
 181         quint64 extSelectable : 1;
 182         quint64 passwordEdit : 1; // used to be Protected
 183         quint64 hasPopup : 1;
 184         quint64 modal : 1;
 185
 186         // IA2 - we chose to not add some IA2 states for now
 187         // Below the ones that seem helpful
 188         quint64 active : 1;
 189         quint64 invalid : 1; // = defunct
 190         quint64 editable : 1;
 191         quint64 multiLine : 1;
 192         quint64 selectableText : 1;
 193         quint64 supportsAutoCompletion : 1;
 194
 195         // quint64 horizontal : 1;
 196         // quint64 vertical : 1;
 197         // quint64 invalidEntry : 1;
 198         // quint64 managesDescendants : 1;
 199         // quint64 singleLine : 1; // we have multi line, this is redundant.
 200         // quint64 stale : 1;
 201         // quint64 transient : 1;
 202         // quint64 pinned : 1;
 203
 204         // Apple - see http://mattgemmell.com/2010/12/19/accessibility-for-iphone-and-ipad-apps/
 205         // quint64 playsSound : 1;
 206         // quint64 summaryElement : 1;
 207         // quint64 updatesFrequently : 1;
 208         // quint64 adjustable : 1;
 209         // more and not included here: http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html
 210
 211         // MSAA
 212         // quint64 alertLow : 1;
 213         // quint64 alertMedium : 1;
 214         // quint64 alertHigh : 1;
 215
 216         State() {
 217             qMemSet(this, 0, sizeof(State));
 218         }
 219     };
 220
 221
 222
 223
 224
 225     enum Role {
 226         NoRole         = 0x00000000,
 227         TitleBar       = 0x00000001,
 228         MenuBar        = 0x00000002,
 229         ScrollBar      = 0x00000003,
 230         Grip           = 0x00000004,
 231         Sound          = 0x00000005,
 232         Cursor         = 0x00000006,
 233         Caret          = 0x00000007,
 234         AlertMessage   = 0x00000008,
 235         Window         = 0x00000009,
 236         Client         = 0x0000000A,
 237         PopupMenu      = 0x0000000B,
 238         MenuItem       = 0x0000000C,
 239         ToolTip        = 0x0000000D,
 240         Application    = 0x0000000E,
 241         Document       = 0x0000000F,
 242         Pane           = 0x00000010,
 243         Chart          = 0x00000011,
 244         Dialog         = 0x00000012,
 245         Border         = 0x00000013,
 246         Grouping       = 0x00000014,
 247         Separator      = 0x00000015,
 248         ToolBar        = 0x00000016,
 249         StatusBar      = 0x00000017,
 250         Table          = 0x00000018,
 251         ColumnHeader   = 0x00000019,
 252         RowHeader      = 0x0000001A,
 253         Column         = 0x0000001B,
 254         Row            = 0x0000001C,
 255         Cell           = 0x0000001D,
 256         Link           = 0x0000001E,
 257         HelpBalloon    = 0x0000001F,
 258         Assistant      = 0x00000020,
 259         List           = 0x00000021,
 260         ListItem       = 0x00000022,
 261         Tree           = 0x00000023,
 262         TreeItem       = 0x00000024,
 263         PageTab        = 0x00000025,
 264         PropertyPage   = 0x00000026,
 265         Indicator      = 0x00000027,
 266         Graphic        = 0x00000028,
 267         StaticText     = 0x00000029,
 268         EditableText   = 0x0000002A,  // Editable, selectable, etc.
 269         Button         = 0x0000002B,
 270 #ifndef qdoc
 271         PushButton     = Button, // deprecated
 272 #endif
 273         CheckBox       = 0x0000002C,
 274         RadioButton    = 0x0000002D,
 275         ComboBox       = 0x0000002E,
 276         // DropList       = 0x0000002F,
 277         ProgressBar    = 0x00000030,
 278         Dial           = 0x00000031,
 279         HotkeyField    = 0x00000032,
 280         Slider         = 0x00000033,
 281         SpinBox        = 0x00000034,
 282         Canvas         = 0x00000035,
 283         Animation      = 0x00000036,
 284         Equation       = 0x00000037,
 285         ButtonDropDown = 0x00000038,
 286         ButtonMenu     = 0x00000039,
 287         ButtonDropGrid = 0x0000003A,
 288         Whitespace     = 0x0000003B,
 289         PageTabList    = 0x0000003C,
 290         Clock          = 0x0000003D,
 291         Splitter       = 0x0000003E,
 292         // Additional Qt roles where enum value does not map directly to MSAA:
 293         LayeredPane    = 0x0000003F,
 294         Terminal       = 0x00000040,
 295         UserRole       = 0x0000ffff
 296     };
 297
 298     enum Text {
 299         Name         = 0,
 300         Description,
 301         Value,
 302         Help,
 303         Accelerator,
 304         DebugDescription,
 305         UserText     = 0x0000ffff
 306     };
 307
 308     enum RelationFlag {
 309         Label         = 0x00000001,
 310         Labelled      = 0x00000002,
 311         Controller    = 0x00000004,
 312         Controlled    = 0x00000008,
 313         AllRelations  = 0xffffffff
 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)(const QAccessibleEvent &event);
 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
 339     QT_DEPRECATED static void updateAccessibility(QObject *object, int child, Event reason);
 340     static void updateAccessibility(const QAccessibleEvent &event);
 341
 342     static bool isActive();
 343     static void setRootObject(QObject *object);
 344
 345     static void cleanup();
 346
 347 private:
 348     static UpdateHandler updateHandler;
 349     static RootObjectHandler rootObjectHandler;
 350
 351     /*! @internal
 352       This class is purely a collection of enums and static functions,
 353       it is not supposed to be instantiated.
 354     */
 355     QAccessible() {}
 356 };
 357
 358 Q_GUI_EXPORT bool operator==(const QAccessible::State &first, const QAccessible::State &second);
 359
 360 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
 361
 362 class QAccessible2Interface;
 363 class QAccessibleTextInterface;
 364 class QAccessibleEditableTextInterface;
 365 class QAccessibleValueInterface;
 366 class QAccessibleActionInterface;
 367 class QAccessibleImageInterface;
 368 class QAccessibleTableInterface;
 369 class QAccessibleTableCellInterface;
 370
 371 class Q_GUI_EXPORT QAccessibleInterface
 372 {
 373 public:
 374     virtual ~QAccessibleInterface() {}
 375     // check for valid pointers
 376     virtual bool isValid() const = 0;
 377     virtual QObject *object() const = 0;
 378     virtual QWindow *window() const;
 379
 380     // relations
 381     virtual QVector<QPair<QAccessibleInterface*, QAccessible::Relation> > relations(QAccessible::Relation match = QAccessible::AllRelations) const;
 382     virtual QAccessibleInterface *focusChild() const;
 383
 384     virtual QAccessibleInterface *childAt(int x, int y) const = 0;
 385
 386     // navigation, hierarchy
 387     virtual QAccessibleInterface *parent() const = 0;
 388     virtual QAccessibleInterface *child(int index) const = 0;
 389     virtual int childCount() const = 0;
 390     virtual int indexOfChild(const QAccessibleInterface *) const = 0;
 391
 392     // properties and state
 393     virtual QString text(QAccessible::Text t) const = 0;
 394     virtual void setText(QAccessible::Text t, const QString &text) = 0;
 395     virtual QRect rect() const = 0;
 396     virtual QAccessible::Role role() const = 0;
 397     virtual QAccessible::State state() const = 0;
 398
 399     virtual QColor foregroundColor() const;
 400     virtual QColor backgroundColor() const;
 401
 402     inline QAccessibleTextInterface *textInterface()
 403     { return reinterpret_cast<QAccessibleTextInterface *>(interface_cast(QAccessible::TextInterface)); }
 404
 405     inline QAccessibleEditableTextInterface *editableTextInterface()
 406     { return reinterpret_cast<QAccessibleEditableTextInterface *>(interface_cast(QAccessible::EditableTextInterface)); }
 407
 408     inline QAccessibleValueInterface *valueInterface()
 409     { return reinterpret_cast<QAccessibleValueInterface *>(interface_cast(QAccessible::ValueInterface)); }
 410
 411     inline QAccessibleActionInterface *actionInterface()
 412     { return reinterpret_cast<QAccessibleActionInterface *>(interface_cast(QAccessible::ActionInterface)); }
 413
 414     inline QAccessibleImageInterface *imageInterface()
 415     { return reinterpret_cast<QAccessibleImageInterface *>(interface_cast(QAccessible::ImageInterface)); }
 416
 417     inline QAccessibleTableInterface *tableInterface()
 418     { return reinterpret_cast<QAccessibleTableInterface *>(interface_cast(QAccessible::TableInterface)); }
 419
 420     inline QAccessibleTableCellInterface *tableCellInterface()
 421     { return reinterpret_cast<QAccessibleTableCellInterface *>(interface_cast(QAccessible::TableCellInterface)); }
 422
 423     virtual void virtual_hook(int id, void *data);
 424
 425     virtual void *interface_cast(QAccessible::InterfaceType)
 426     { return 0; }
 427 private:
 428 };
 429
 430 class Q_GUI_EXPORT QAccessibleEvent
 431 {
 432 public:
 433     inline QAccessibleEvent(QAccessible::Event typ, QObject *obj, int chld = -1)
 434         : m_type(typ), m_object(obj), m_child(chld)
 435     {
 436         Q_ASSERT(obj);
 437     }
 438
 439     QAccessible::Event type() const { return m_type; }
 440     QObject *object() const { return m_object; }
 441     int child() const { return m_child; }
 442
 443     QAccessibleInterface *accessibleInterface() const;
 444
 445 private:
 446     QAccessible::Event m_type;
 447     QObject *m_object;
 448     int m_child;
 449 };
 450
 451
 452 #define QAccessibleInterface_iid "org.qt-project.Qt.QAccessibleInterface"
 453 Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
 454
 455 Q_GUI_EXPORT const char *qAccessibleRoleString(QAccessible::Role role);
 456 Q_GUI_EXPORT const char *qAccessibleEventString(QAccessible::Event event);
 457
 458 #ifndef QT_NO_DEBUG_STREAM
 459 Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleInterface *iface);
 460 #endif
 461
 462 #endif // QT_NO_ACCESSIBILITY
 463
 464 QT_END_NAMESPACE
 465
 466 QT_END_HEADER
 467
 468 #endif // QACCESSIBLE_H