src/widgets/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
  64 class Q_WIDGETS_EXPORT QAccessible
  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     };
 186     Q_DECLARE_FLAGS(State, StateFlag)
 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         UserRole       = 0x0000ffff
 255     };
 256
 257     enum Text {
 258         Name         = 0,
 259         Description,
 260         Value,
 261         Help,
 262         Accelerator,
 263         UserText     = 0x0000ffff
 264     };
 265
 266     enum RelationFlag {
 267         Unrelated     = 0x00000000,
 268         Self          = 0x00000001,
 269         Ancestor      = 0x00000002,
 270         Child         = 0x00000004,
 271         Descendent    = 0x00000008,
 272         Sibling       = 0x00000010,
 273         HierarchyMask = 0x000000ff,
 274
 275         Up            = 0x00000100,
 276         Down          = 0x00000200,
 277         Left          = 0x00000400,
 278         Right         = 0x00000800,
 279         Covers        = 0x00001000,
 280         Covered       = 0x00002000,
 281         GeometryMask  = 0x0000ff00,
 282
 283         FocusChild    = 0x00010000,
 284         Label         = 0x00020000,
 285         Labelled      = 0x00040000,
 286         Controller    = 0x00080000,
 287         Controlled    = 0x00100000,
 288         LogicalMask   = 0x00ff0000
 289     };
 290     Q_DECLARE_FLAGS(Relation, RelationFlag)
 291
 292     enum Action {
 293         DefaultAction       = 0,
 294         Press               = -1,
 295         FirstStandardAction = Press,
 296         SetFocus            = -2,
 297         Increase            = -3,
 298         Decrease            = -4,
 299         Accept              = -5,
 300         Cancel              = -6,
 301         Select              = -7,
 302         ClearSelection      = -8,
 303         RemoveSelection     = -9,
 304         ExtendSelection     = -10,
 305         AddToSelection      = -11,
 306         LastStandardAction  = AddToSelection
 307     };
 308
 309     enum Method {
 310         ListSupportedMethods      = 0,
 311         SetCursorPosition         = 1,
 312         GetCursorPosition         = 2,
 313         ForegroundColor           = 3,
 314         BackgroundColor           = 4
 315     };
 316
 317     typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
 318     typedef void(*UpdateHandler)(QObject*, int who, Event reason);
 319     typedef void(*RootObjectHandler)(QObject*);
 320
 321     static void installFactory(InterfaceFactory);
 322     static void removeFactory(InterfaceFactory);
 323     static UpdateHandler installUpdateHandler(UpdateHandler);
 324     static RootObjectHandler installRootObjectHandler(RootObjectHandler);
 325
 326     static QAccessibleInterface *queryAccessibleInterface(QObject *);
 327     static void updateAccessibility(QObject *, int who, Event reason);
 328     static bool isActive();
 329     static void setRootObject(QObject*);
 330
 331     static void initialize();
 332     static void cleanup();
 333
 334 private:
 335     static UpdateHandler updateHandler;
 336     static RootObjectHandler rootObjectHandler;
 337 };
 338
 339 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::State)
 340 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
 341 QT_END_NAMESPACE
 342 Q_DECLARE_METATYPE(QSet<QAccessible::Method>)
 343 QT_BEGIN_NAMESPACE
 344
 345 namespace QAccessible2
 346 {
 347     enum InterfaceType
 348     {
 349         TextInterface,
 350         EditableTextInterface,
 351         ValueInterface,
 352         TableInterface,
 353         ActionInterface,
 354         ImageInterface,
 355         Table2Interface
 356     };
 357 }
 358
 359 class QAccessible2Interface;
 360 class QAccessibleTextInterface;
 361 class QAccessibleEditableTextInterface;
 362 class QAccessibleValueInterface;
 363 class QAccessibleTableInterface;
 364 class QAccessibleActionInterface;
 365 class QAccessibleImageInterface;
 366 class QAccessibleTable2Interface;
 367
 368 class Q_WIDGETS_EXPORT QAccessibleInterface : public QAccessible
 369 {
 370 public:
 371     virtual ~QAccessibleInterface() {}
 372     // check for valid pointers
 373     virtual bool isValid() const = 0;
 374     virtual QObject *object() const = 0;
 375
 376     // hierarchy
 377     virtual int childCount() const = 0;
 378     virtual int indexOfChild(const QAccessibleInterface *) const = 0;
 379
 380     // relations
 381     virtual Relation relationTo(int child, const QAccessibleInterface *other,
 382                                 int otherChild) const = 0;
 383     virtual int childAt(int x, int y) const = 0;
 384
 385     // navigation
 386     virtual int navigate(RelationFlag relation, int index, QAccessibleInterface **iface) const = 0;
 387
 388     // properties and state
 389     virtual QString text(Text t, int child) const = 0;
 390     virtual void setText(Text t, int child, const QString &text) = 0;
 391     virtual QRect rect(int child) const = 0;
 392     virtual Role role(int child) const = 0;
 393     virtual State state(int child) const = 0;
 394
 395     // action
 396     virtual int userActionCount(int child) const = 0;
 397     virtual QString actionText(int action, Text t, int child) const = 0;
 398     virtual bool doAction(int action, int child, const QVariantList &params = QVariantList()) = 0;
 399
 400     QVariant invokeMethod(Method method, int child = 0,
 401                           const QVariantList &params = QVariantList());
 402
 403     inline QSet<Method> supportedMethods()
 404     { return qvariant_cast<QSet<Method> >(invokeMethod(ListSupportedMethods)); }
 405
 406     inline QColor foregroundColor()
 407     { return qvariant_cast<QColor>(invokeMethod(ForegroundColor)); }
 408
 409     inline QColor backgroundColor()
 410     { return qvariant_cast<QColor>(invokeMethod(BackgroundColor)); }
 411
 412     inline QAccessibleTextInterface *textInterface()
 413     { return reinterpret_cast<QAccessibleTextInterface *>(cast_helper(QAccessible2::TextInterface)); }
 414
 415     inline QAccessibleEditableTextInterface *editableTextInterface()
 416     { return reinterpret_cast<QAccessibleEditableTextInterface *>(cast_helper(QAccessible2::EditableTextInterface)); }
 417
 418     inline QAccessibleValueInterface *valueInterface()
 419     { return reinterpret_cast<QAccessibleValueInterface *>(cast_helper(QAccessible2::ValueInterface)); }
 420
 421     inline QAccessibleTableInterface *tableInterface()
 422     { return reinterpret_cast<QAccessibleTableInterface *>(cast_helper(QAccessible2::TableInterface)); }
 423
 424     inline QAccessibleActionInterface *actionInterface()
 425     { return reinterpret_cast<QAccessibleActionInterface *>(cast_helper(QAccessible2::ActionInterface)); }
 426
 427     inline QAccessibleImageInterface *imageInterface()
 428     { return reinterpret_cast<QAccessibleImageInterface *>(cast_helper(QAccessible2::ImageInterface)); }
 429
 430     inline QAccessibleTable2Interface *table2Interface()
 431     { return reinterpret_cast<QAccessibleTable2Interface *>(cast_helper(QAccessible2::Table2Interface)); }
 432
 433 private:
 434     QAccessible2Interface *cast_helper(QAccessible2::InterfaceType);
 435 };
 436
 437 class Q_WIDGETS_EXPORT QAccessibleInterfaceEx: public QAccessibleInterface
 438 {
 439 public:
 440     virtual QVariant invokeMethodEx(Method method, int child, const QVariantList &params) = 0;
 441     virtual QVariant virtual_hook(const QVariant &data);
 442     virtual QAccessible2Interface *interface_cast(QAccessible2::InterfaceType)
 443     { return 0; }
 444 };
 445
 446
 447 class Q_WIDGETS_EXPORT QAccessibleEvent : public QEvent
 448 {
 449 public:
 450     inline QAccessibleEvent(Type type, int child);
 451     inline int child() const { return c; }
 452     inline QString value() const { return val; }
 453     inline void setValue(const QString &aText) { val = aText; }
 454
 455 private:
 456     int c;
 457     QString val;
 458 };
 459
 460 inline QAccessibleEvent::QAccessibleEvent(Type atype, int achild)
 461     : QEvent(atype), c(achild) {}
 462
 463 #define QAccessibleInterface_iid "com.trolltech.Qt.QAccessibleInterface"
 464 Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
 465
 466 #endif // QT_NO_ACCESSIBILITY
 467
 468 QT_END_NAMESPACE
 469
 470 QT_END_HEADER
 471
 472 #endif // QACCESSIBLE_H