src/gui/accessible/qaccessible.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtGui module of the Qt Toolkit.
   8 **
   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.
  17 **
  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.
  21 **
  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.
  29 **
  30 ** Other Usage
  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.
  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 QT_MODULE(Gui)
  59
  60 #ifndef QT_NO_ACCESSIBILITY
  61
  62 class QAccessibleInterface;
  63 class QWindow;
  64
  65 class Q_GUI_EXPORT QAccessible
  66 {
  67 public:
  68     enum Event {
  69         SoundPlayed          = 0x0001,
  70         Alert                = 0x0002,
  71         ForegroundChanged    = 0x0003,
  72         MenuStart            = 0x0004,
  73         MenuEnd              = 0x0005,
  74         PopupMenuStart       = 0x0006,
  75         PopupMenuEnd         = 0x0007,
  76         ContextHelpStart     = 0x000C,
  77         ContextHelpEnd       = 0x000D,
  78         DragDropStart        = 0x000E,
  79         DragDropEnd          = 0x000F,
  80         DialogStart          = 0x0010,
  81         DialogEnd            = 0x0011,
  82         ScrollingStart       = 0x0012,
  83         ScrollingEnd         = 0x0013,
  84
  85         MenuCommand          = 0x0018,
  86
  87         // Values from IAccessible2
  88         ActionChanged                    = 0x0101,
  89         ActiveDescendantChanged          = 0x0102,
  90         AttributeChanged                 = 0x0103,
  91         DocumentContentChanged           = 0x0104,
  92         DocumentLoadComplete             = 0x0105,
  93         DocumentLoadStopped              = 0x0106,
  94         DocumentReload                   = 0x0107,
  95         HyperlinkEndIndexChanged         = 0x0108,
  96         HyperlinkNumberOfAnchorsChanged  = 0x0109,
  97         HyperlinkSelectedLinkChanged     = 0x010A,
  98         HypertextLinkActivated           = 0x010B,
  99         HypertextLinkSelected            = 0x010C,
 100         HyperlinkStartIndexChanged       = 0x010D,
 101         HypertextChanged                 = 0x010E,
 102         HypertextNLinksChanged           = 0x010F,
 103         ObjectAttributeChanged           = 0x0110,
 104         PageChanged                      = 0x0111,
 105         SectionChanged                   = 0x0112,
 106         TableCaptionChanged              = 0x0113,
 107         TableColumnDescriptionChanged    = 0x0114,
 108         TableColumnHeaderChanged         = 0x0115,
 109         TableModelChanged                = 0x0116,
 110         TableRowDescriptionChanged       = 0x0117,
 111         TableRowHeaderChanged            = 0x0118,
 112         TableSummaryChanged              = 0x0119,
 113         TextAttributeChanged             = 0x011A,
 114         TextCaretMoved                   = 0x011B,
 115         // TextChanged = 0x011C, is deprecated in IA2, use TextUpdated
 116         TextColumnChanged                = 0x011D,
 117         TextInserted                     = 0x011E,
 118         TextRemoved                      = 0x011F,
 119         TextUpdated                      = 0x0120,
 120         TextSelectionChanged             = 0x0121,
 121         VisibleDataChanged               = 0x0122,
 122
 123         ObjectCreated        = 0x8000,
 124         ObjectDestroyed      = 0x8001,
 125         ObjectShow           = 0x8002,
 126         ObjectHide           = 0x8003,
 127         ObjectReorder        = 0x8004,
 128         Focus                = 0x8005,
 129         Selection            = 0x8006,
 130         SelectionAdd         = 0x8007,
 131         SelectionRemove      = 0x8008,
 132         SelectionWithin      = 0x8009,
 133         StateChanged         = 0x800A,
 134         LocationChanged      = 0x800B,
 135         NameChanged          = 0x800C,
 136         DescriptionChanged   = 0x800D,
 137         ValueChanged         = 0x800E,
 138         ParentChanged        = 0x800F,
 139         HelpChanged          = 0x80A0,
 140         DefaultActionChanged = 0x80B0,
 141         AcceleratorChanged   = 0x80C0
 142     };
 143
 144     enum StateFlag {
 145         Normal          = 0x00000000,
 146         Unavailable     = 0x00000001,
 147         Selected        = 0x00000002,
 148         Focused         = 0x00000004,
 149         Pressed         = 0x00000008,
 150         Checked         = 0x00000010,
 151         Mixed           = 0x00000020,
 152         ReadOnly        = 0x00000040,
 153         HotTracked      = 0x00000080,
 154         DefaultButton   = 0x00000100,
 155         // #### Qt5 Expandable
 156         Expanded        = 0x00000200,
 157         Collapsed       = 0x00000400,
 158         Busy            = 0x00000800,
 159         // Floating        = 0x00001000,
 160         Marqueed        = 0x00002000,
 161         Animated        = 0x00004000,
 162         Invisible       = 0x00008000,
 163         Offscreen       = 0x00010000,
 164         Sizeable        = 0x00020000,
 165         Movable         = 0x00040000,
 166         SelfVoicing     = 0x00080000,
 167         Focusable       = 0x00100000,
 168         Selectable      = 0x00200000,
 169         Linked          = 0x00400000,
 170         Traversed       = 0x00800000,
 171         MultiSelectable = 0x01000000,
 172         ExtSelectable   = 0x02000000,
 173         //AlertLow        = 0x04000000,
 174         //AlertMedium     = 0x08000000,
 175         //AlertHigh       = 0x10000000, /* reused for HasInvokeExtension */
 176         Protected       = 0x20000000,
 177         HasPopup        = 0x40000000,
 178         Modal           = 0x80000000
 179
 180     };
 181     Q_DECLARE_FLAGS(State, StateFlag)
 182
 183     enum Role {
 184         NoRole         = 0x00000000,
 185         TitleBar       = 0x00000001,
 186         MenuBar        = 0x00000002,
 187         ScrollBar      = 0x00000003,
 188         Grip           = 0x00000004,
 189         Sound          = 0x00000005,
 190         Cursor         = 0x00000006,
 191         Caret          = 0x00000007,
 192         AlertMessage   = 0x00000008,
 193         Window         = 0x00000009,
 194         Client         = 0x0000000A,
 195         PopupMenu      = 0x0000000B,
 196         MenuItem       = 0x0000000C,
 197         ToolTip        = 0x0000000D,
 198         Application    = 0x0000000E,
 199         Document       = 0x0000000F,
 200         Pane           = 0x00000010,
 201         Chart          = 0x00000011,
 202         Dialog         = 0x00000012,
 203         Border         = 0x00000013,
 204         Grouping       = 0x00000014,
 205         Separator      = 0x00000015,
 206         ToolBar        = 0x00000016,
 207         StatusBar      = 0x00000017,
 208         Table          = 0x00000018,
 209         ColumnHeader   = 0x00000019,
 210         RowHeader      = 0x0000001A,
 211         Column         = 0x0000001B,
 212         Row            = 0x0000001C,
 213         Cell           = 0x0000001D,
 214         Link           = 0x0000001E,
 215         HelpBalloon    = 0x0000001F,
 216         Assistant      = 0x00000020,
 217         List           = 0x00000021,
 218         ListItem       = 0x00000022,
 219         Tree           = 0x00000023,
 220         TreeItem       = 0x00000024,
 221         PageTab        = 0x00000025,
 222         PropertyPage   = 0x00000026,
 223         Indicator      = 0x00000027,
 224         Graphic        = 0x00000028,
 225         StaticText     = 0x00000029,
 226         EditableText   = 0x0000002A,  // Editable, selectable, etc.
 227         PushButton     = 0x0000002B,
 228         CheckBox       = 0x0000002C,
 229         RadioButton    = 0x0000002D,
 230         ComboBox       = 0x0000002E,
 231         // DropList       = 0x0000002F,
 232         ProgressBar    = 0x00000030,
 233         Dial           = 0x00000031,
 234         HotkeyField    = 0x00000032,
 235         Slider         = 0x00000033,
 236         SpinBox        = 0x00000034,
 237         Canvas         = 0x00000035,
 238         Animation      = 0x00000036,
 239         Equation       = 0x00000037,
 240         ButtonDropDown = 0x00000038,
 241         ButtonMenu     = 0x00000039,
 242         ButtonDropGrid = 0x0000003A,
 243         Whitespace     = 0x0000003B,
 244         PageTabList    = 0x0000003C,
 245         Clock          = 0x0000003D,
 246         Splitter       = 0x0000003E,
 247         // Additional Qt roles where enum value does not map directly to MSAA:
 248         LayeredPane    = 0x0000003F,
 249         UserRole       = 0x0000ffff
 250     };
 251
 252     enum Text {
 253         Name         = 0,
 254         Description,
 255         Value,
 256         Help,
 257         Accelerator,
 258         UserText     = 0x0000ffff
 259     };
 260
 261     enum RelationFlag {
 262         Unrelated     = 0x00000000,
 263         Self          = 0x00000001,
 264         Ancestor      = 0x00000002,
 265         Child         = 0x00000004,
 266         Descendent    = 0x00000008,
 267         Sibling       = 0x00000010,
 268         HierarchyMask = 0x000000ff,
 269
 270         Up            = 0x00000100,
 271         Down          = 0x00000200,
 272         Left          = 0x00000400,
 273         Right         = 0x00000800,
 274         Covers        = 0x00001000,
 275         Covered       = 0x00002000,
 276         GeometryMask  = 0x0000ff00,
 277
 278         FocusChild    = 0x00010000,
 279         Label         = 0x00020000,
 280         Labelled      = 0x00040000,
 281         Controller    = 0x00080000,
 282         Controlled    = 0x00100000,
 283         LogicalMask   = 0x00ff0000
 284     };
 285     Q_DECLARE_FLAGS(Relation, RelationFlag)
 286
 287     enum Action {
 288         DefaultAction       = 0,
 289         Press               = -1,
 290         FirstStandardAction = Press,
 291         SetFocus            = -2,
 292         Increase            = -3,
 293         Decrease            = -4,
 294         Accept              = -5,
 295         Cancel              = -6,
 296         Select              = -7,
 297         ClearSelection      = -8,
 298         RemoveSelection     = -9,
 299         ExtendSelection     = -10,
 300         AddToSelection      = -11,
 301         LastStandardAction  = AddToSelection
 302     };
 303
 304     enum Method {
 305         ListSupportedMethods      = 0,
 306         SetCursorPosition         = 1,
 307         GetCursorPosition         = 2,
 308         ForegroundColor           = 3,
 309         BackgroundColor           = 4
 310     };
 311
 312     typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
 313     typedef void(*UpdateHandler)(QObject*, int who, Event reason);
 314     typedef void(*RootObjectHandler)(QObject*);
 315
 316     static void installFactory(InterfaceFactory);
 317     static void removeFactory(InterfaceFactory);
 318     static UpdateHandler installUpdateHandler(UpdateHandler);
 319     static RootObjectHandler installRootObjectHandler(RootObjectHandler);
 320
 321     static QAccessibleInterface *queryAccessibleInterface(QObject *);
 322     static void updateAccessibility(QObject *, int who, Event reason);
 323     static bool isActive();
 324     static void setRootObject(QObject*);
 325
 326     static void cleanup();
 327
 328 private:
 329     static UpdateHandler updateHandler;
 330     static RootObjectHandler rootObjectHandler;
 331 };
 332
 333 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::State)
 334 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
 335 QT_END_NAMESPACE
 336 Q_DECLARE_METATYPE(QSet<QAccessible::Method>)
 337 QT_BEGIN_NAMESPACE
 338
 339 namespace QAccessible2
 340 {
 341     enum InterfaceType
 342     {
 343         TextInterface,
 344         EditableTextInterface,
 345         ValueInterface,
 346         TableInterface,
 347         ActionInterface,
 348         ImageInterface,
 349         Table2Interface
 350     };
 351 }
 352
 353 class QAccessible2Interface;
 354 class QAccessibleTextInterface;
 355 class QAccessibleEditableTextInterface;
 356 class QAccessibleValueInterface;
 357 class QAccessibleTableInterface;
 358 class QAccessibleActionInterface;
 359 class QAccessibleImageInterface;
 360 class QAccessibleTable2Interface;
 361
 362 class Q_GUI_EXPORT QAccessibleInterface : public QAccessible
 363 {
 364 public:
 365     virtual ~QAccessibleInterface() {}
 366     // check for valid pointers
 367     virtual bool isValid() const = 0;
 368     virtual QObject *object() const = 0;
 369     virtual QWindow *window() const;
 370
 371     // relations
 372     virtual Relation relationTo(const QAccessibleInterface *other) const;
 373     virtual QVector<QPair<QAccessibleInterface*, Relation> > relations() const;
 374
 375     virtual int childAt(int x, int y) const = 0;
 376
 377     // navigation, hierarchy
 378     virtual QAccessibleInterface *parent() const = 0;
 379     virtual QAccessibleInterface *child(int index) const = 0;
 380     virtual int childCount() const = 0;
 381     virtual int indexOfChild(const QAccessibleInterface *) const = 0;
 382     virtual int navigate(RelationFlag relation, int index, QAccessibleInterface **iface) const = 0;
 383
 384     // properties and state
 385     virtual QString text(Text t) const = 0;
 386     virtual void setText(Text t, const QString &text) = 0;
 387     virtual QRect rect() const = 0;
 388     virtual Role role() const = 0;
 389     virtual State state() const = 0;
 390
 391     virtual QColor foregroundColor() const;
 392     virtual QColor backgroundColor() const;
 393
 394     virtual QVariant invokeMethod(Method method, const QVariantList &params = QVariantList());
 395
 396     inline QSet<Method> supportedMethods()
 397     { return qvariant_cast<QSet<Method> >(invokeMethod(ListSupportedMethods)); }
 398
 399     inline QAccessibleTextInterface *textInterface()
 400     { return reinterpret_cast<QAccessibleTextInterface *>(cast_helper(QAccessible2::TextInterface)); }
 401
 402     inline QAccessibleEditableTextInterface *editableTextInterface()
 403     { return reinterpret_cast<QAccessibleEditableTextInterface *>(cast_helper(QAccessible2::EditableTextInterface)); }
 404
 405     inline QAccessibleValueInterface *valueInterface()
 406     { return reinterpret_cast<QAccessibleValueInterface *>(cast_helper(QAccessible2::ValueInterface)); }
 407
 408     inline QAccessibleTableInterface *tableInterface()
 409     { return reinterpret_cast<QAccessibleTableInterface *>(cast_helper(QAccessible2::TableInterface)); }
 410
 411     inline QAccessibleActionInterface *actionInterface()
 412     { return reinterpret_cast<QAccessibleActionInterface *>(cast_helper(QAccessible2::ActionInterface)); }
 413
 414     inline QAccessibleImageInterface *imageInterface()
 415     { return reinterpret_cast<QAccessibleImageInterface *>(cast_helper(QAccessible2::ImageInterface)); }
 416
 417     inline QAccessibleTable2Interface *table2Interface()
 418     { return reinterpret_cast<QAccessibleTable2Interface *>(cast_helper(QAccessible2::Table2Interface)); }
 419
 420     // FIXME
 421     virtual QVariant virtual_hook(const QVariant &data);
 422     virtual QAccessible2Interface *interface_cast(QAccessible2::InterfaceType)
 423     { return 0; }
 424
 425 private:
 426     QAccessible2Interface *cast_helper(QAccessible2::InterfaceType);
 427 };
 428
 429 class QAccessibleEvent : public QEvent
 430 {
 431 public:
 432     inline QAccessibleEvent(Type type);
 433     inline QString value() const { return val; }
 434     inline void setValue(const QString &aText) { val = aText; }
 435
 436 private:
 437     QString val;
 438 };
 439
 440 inline QAccessibleEvent::QAccessibleEvent(Type atype)
 441     : QEvent(atype) {}
 442
 443 #define QAccessibleInterface_iid "com.trolltech.Qt.QAccessibleInterface"
 444 Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
 445
 446 #ifndef QT_NO_DEBUG_STREAM
 447 Q_GUI_EXPORT QDebug operator<<(QDebug d, const QAccessibleInterface *iface);
 448 #endif
 449
 450 #endif // QT_NO_ACCESSIBILITY
 451
 452 QT_END_NAMESPACE
 453
 454 QT_END_HEADER
 455
 456 #endif // QACCESSIBLE_H