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 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  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 QT_MODULE(Gui)
  59
  60 #ifndef QT_NO_ACCESSIBILITY
  61
  62 class QAccessibleInterface;
  63
  64 class Q_GUI_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,
  89         AttributeChanged,
  90         DocumentContentChanged,
  91         DocumentLoadComplete,
  92         DocumentLoadStopped,
  93         DocumentReload,
  94         HyperlinkEndIndexChanged,
  95         HyperlinkNumberOfAnchorsChanged,
  96         HyperlinkSelectedLinkChanged,
  97         HypertextLinkActivated,
  98         HypertextLinkSelected,
  99         HyperlinkStartIndexChanged,
 100         HypertextChanged,
 101         HypertextNLinksChanged,
 102         ObjectAttributeChanged,
 103         PageChanged,
 104         SectionChanged,
 105         TableCaptionChanged,
 106         TableColumnDescriptionChanged,
 107         TableColumnHeaderChanged,
 108         TableModelChanged,
 109         TableRowDescriptionChanged,
 110         TableRowHeaderChanged,
 111         TableSummaryChanged,
 112         TextAttributeChanged,
 113         TextCaretMoved,
 114         // TextChanged, deprecated, use TextUpdated
 115         TextColumnChanged = TextCaretMoved + 2,
 116         TextInserted,
 117         TextRemoved,
 118         TextUpdated,
 119         TextSelectionChanged,
 120         VisibleDataChanged,
 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         Expanded        = 0x00000200,
 155         Collapsed       = 0x00000400,
 156         Busy            = 0x00000800,
 157         // Floating        = 0x00001000,
 158         Marqueed        = 0x00002000,
 159         Animated        = 0x00004000,
 160         Invisible       = 0x00008000,
 161         Offscreen       = 0x00010000,
 162         Sizeable        = 0x00020000,
 163         Movable         = 0x00040000,
 164 #ifdef QT3_SUPPORT
 165         Moveable        = Movable,
 166 #endif
 167         SelfVoicing     = 0x00080000,
 168         Focusable       = 0x00100000,
 169         Selectable      = 0x00200000,
 170         Linked          = 0x00400000,
 171         Traversed       = 0x00800000,
 172         MultiSelectable = 0x01000000,
 173         ExtSelectable   = 0x02000000,
 174         //AlertLow        = 0x04000000,
 175         //AlertMedium     = 0x08000000,
 176         //AlertHigh       = 0x10000000, /* reused for HasInvokeExtension */
 177         Protected       = 0x20000000,
 178         HasPopup        = 0x40000000,
 179         Modal           = 0x80000000,
 180
 181         HasInvokeExtension = 0x10000000 // internal
 182     };
 183     Q_DECLARE_FLAGS(State, StateFlag)
 184
 185     enum Role {
 186         NoRole         = 0x00000000,
 187         TitleBar       = 0x00000001,
 188         MenuBar        = 0x00000002,
 189         ScrollBar      = 0x00000003,
 190         Grip           = 0x00000004,
 191         Sound          = 0x00000005,
 192         Cursor         = 0x00000006,
 193         Caret          = 0x00000007,
 194         AlertMessage   = 0x00000008,
 195         Window         = 0x00000009,
 196         Client         = 0x0000000A,
 197         PopupMenu      = 0x0000000B,
 198         MenuItem       = 0x0000000C,
 199         ToolTip        = 0x0000000D,
 200         Application    = 0x0000000E,
 201         Document       = 0x0000000F,
 202         Pane           = 0x00000010,
 203         Chart          = 0x00000011,
 204         Dialog         = 0x00000012,
 205         Border         = 0x00000013,
 206         Grouping       = 0x00000014,
 207         Separator      = 0x00000015,
 208         ToolBar        = 0x00000016,
 209         StatusBar      = 0x00000017,
 210         Table          = 0x00000018,
 211         ColumnHeader   = 0x00000019,
 212         RowHeader      = 0x0000001A,
 213         Column         = 0x0000001B,
 214         Row            = 0x0000001C,
 215         Cell           = 0x0000001D,
 216         Link           = 0x0000001E,
 217         HelpBalloon    = 0x0000001F,
 218         Assistant      = 0x00000020,
 219         List           = 0x00000021,
 220         ListItem       = 0x00000022,
 221         Tree           = 0x00000023,
 222         TreeItem       = 0x00000024,
 223         PageTab        = 0x00000025,
 224         PropertyPage   = 0x00000026,
 225         Indicator      = 0x00000027,
 226         Graphic        = 0x00000028,
 227         StaticText     = 0x00000029,
 228         EditableText   = 0x0000002A,  // Editable, selectable, etc.
 229         PushButton     = 0x0000002B,
 230         CheckBox       = 0x0000002C,
 231         RadioButton    = 0x0000002D,
 232         ComboBox       = 0x0000002E,
 233         // DropList       = 0x0000002F,
 234         ProgressBar    = 0x00000030,
 235         Dial           = 0x00000031,
 236         HotkeyField    = 0x00000032,
 237         Slider         = 0x00000033,
 238         SpinBox        = 0x00000034,
 239         Canvas         = 0x00000035,
 240         Animation      = 0x00000036,
 241         Equation       = 0x00000037,
 242         ButtonDropDown = 0x00000038,
 243         ButtonMenu     = 0x00000039,
 244         ButtonDropGrid = 0x0000003A,
 245         Whitespace     = 0x0000003B,
 246         PageTabList    = 0x0000003C,
 247         Clock          = 0x0000003D,
 248         Splitter       = 0x0000003E,
 249         // Additional Qt roles where enum value does not map directly to MSAA:
 250         LayeredPane    = 0x0000003F,
 251         UserRole       = 0x0000ffff
 252     };
 253
 254     enum Text {
 255         Name         = 0,
 256         Description,
 257         Value,
 258         Help,
 259         Accelerator,
 260         UserText     = 0x0000ffff
 261     };
 262
 263     enum RelationFlag {
 264         Unrelated     = 0x00000000,
 265         Self          = 0x00000001,
 266         Ancestor      = 0x00000002,
 267         Child         = 0x00000004,
 268         Descendent    = 0x00000008,
 269         Sibling       = 0x00000010,
 270         HierarchyMask = 0x000000ff,
 271
 272         Up            = 0x00000100,
 273         Down          = 0x00000200,
 274         Left          = 0x00000400,
 275         Right         = 0x00000800,
 276         Covers        = 0x00001000,
 277         Covered       = 0x00002000,
 278         GeometryMask  = 0x0000ff00,
 279
 280         FocusChild    = 0x00010000,
 281         Label         = 0x00020000,
 282         Labelled      = 0x00040000,
 283         Controller    = 0x00080000,
 284         Controlled    = 0x00100000,
 285         LogicalMask   = 0x00ff0000
 286     };
 287     Q_DECLARE_FLAGS(Relation, RelationFlag)
 288
 289     enum Action {
 290         DefaultAction       = 0,
 291         Press               = -1,
 292         FirstStandardAction = Press,
 293         SetFocus            = -2,
 294         Increase            = -3,
 295         Decrease            = -4,
 296         Accept              = -5,
 297         Cancel              = -6,
 298         Select              = -7,
 299         ClearSelection      = -8,
 300         RemoveSelection     = -9,
 301         ExtendSelection     = -10,
 302         AddToSelection      = -11,
 303         LastStandardAction  = AddToSelection
 304     };
 305
 306     enum Method {
 307         ListSupportedMethods      = 0,
 308         SetCursorPosition         = 1,
 309         GetCursorPosition         = 2,
 310         ForegroundColor           = 3,
 311         BackgroundColor           = 4
 312     };
 313
 314     typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
 315     typedef void(*UpdateHandler)(QObject*, int who, Event reason);
 316     typedef void(*RootObjectHandler)(QObject*);
 317
 318     static void installFactory(InterfaceFactory);
 319     static void removeFactory(InterfaceFactory);
 320     static UpdateHandler installUpdateHandler(UpdateHandler);
 321     static RootObjectHandler installRootObjectHandler(RootObjectHandler);
 322
 323     static QAccessibleInterface *queryAccessibleInterface(QObject *);
 324     static void updateAccessibility(QObject *, int who, Event reason);
 325     static bool isActive();
 326     static void setRootObject(QObject*);
 327
 328     static void initialize();
 329     static void cleanup();
 330
 331 private:
 332     static UpdateHandler updateHandler;
 333     static RootObjectHandler rootObjectHandler;
 334 };
 335
 336 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::State)
 337 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
 338 QT_END_NAMESPACE
 339 Q_DECLARE_METATYPE(QSet<QAccessible::Method>)
 340 QT_BEGIN_NAMESPACE
 341
 342 namespace QAccessible2
 343 {
 344     enum InterfaceType
 345     {
 346         TextInterface,
 347         EditableTextInterface,
 348         ValueInterface,
 349         TableInterface,
 350         ActionInterface,
 351         ImageInterface
 352     };
 353 }
 354
 355 class QAccessible2Interface;
 356 class QAccessibleTextInterface;
 357 class QAccessibleEditableTextInterface;
 358 class QAccessibleValueInterface;
 359 class QAccessibleTableInterface;
 360 class QAccessibleActionInterface;
 361 class QAccessibleImageInterface;
 362
 363 class Q_GUI_EXPORT QAccessibleInterface : public QAccessible
 364 {
 365 public:
 366     virtual ~QAccessibleInterface() {}
 367     // check for valid pointers
 368     virtual bool isValid() const = 0;
 369     virtual QObject *object() const = 0;
 370
 371     // hierarchy
 372     virtual int childCount() const = 0;
 373     virtual int indexOfChild(const QAccessibleInterface *) const = 0;
 374
 375     // relations
 376     virtual Relation relationTo(int child, const QAccessibleInterface *other,
 377                                 int otherChild) const = 0;
 378     virtual int childAt(int x, int y) const = 0;
 379
 380     // navigation
 381     virtual int navigate(RelationFlag relation, int index, QAccessibleInterface **iface) const = 0;
 382
 383     // properties and state
 384     virtual QString text(Text t, int child) const = 0;
 385     virtual void setText(Text t, int child, const QString &text) = 0;
 386     virtual QRect rect(int child) const = 0;
 387     virtual Role role(int child) const = 0;
 388     virtual State state(int child) const = 0;
 389
 390     // action
 391     virtual int userActionCount(int child) const = 0;
 392     virtual QString actionText(int action, Text t, int child) const = 0;
 393     virtual bool doAction(int action, int child, const QVariantList &params = QVariantList()) = 0;
 394
 395     QVariant invokeMethod(Method method, int child = 0,
 396                           const QVariantList &params = QVariantList());
 397
 398     inline QSet<Method> supportedMethods()
 399     { return qvariant_cast<QSet<Method> >(invokeMethod(ListSupportedMethods)); }
 400
 401     inline QColor foregroundColor()
 402     { return qvariant_cast<QColor>(invokeMethod(ForegroundColor)); }
 403
 404     inline QColor backgroundColor()
 405     { return qvariant_cast<QColor>(invokeMethod(BackgroundColor)); }
 406
 407     inline QAccessibleTextInterface *textInterface()
 408     { return reinterpret_cast<QAccessibleTextInterface *>(cast_helper(QAccessible2::TextInterface)); }
 409
 410     inline QAccessibleEditableTextInterface *editableTextInterface()
 411     { return reinterpret_cast<QAccessibleEditableTextInterface *>(cast_helper(QAccessible2::EditableTextInterface)); }
 412
 413     inline QAccessibleValueInterface *valueInterface()
 414     { return reinterpret_cast<QAccessibleValueInterface *>(cast_helper(QAccessible2::ValueInterface)); }
 415
 416     inline QAccessibleTableInterface *tableInterface()
 417     { return reinterpret_cast<QAccessibleTableInterface *>(cast_helper(QAccessible2::TableInterface)); }
 418
 419     inline QAccessibleActionInterface *actionInterface()
 420     { return reinterpret_cast<QAccessibleActionInterface *>(cast_helper(QAccessible2::ActionInterface)); }
 421
 422     inline QAccessibleImageInterface *imageInterface()
 423     { return reinterpret_cast<QAccessibleImageInterface *>(cast_helper(QAccessible2::ImageInterface)); }
 424
 425 private:
 426     QAccessible2Interface *cast_helper(QAccessible2::InterfaceType);
 427 };
 428
 429 class Q_GUI_EXPORT QAccessibleInterfaceEx: public QAccessibleInterface
 430 {
 431 public:
 432     virtual QVariant invokeMethodEx(Method method, int child, const QVariantList &params) = 0;
 433     virtual QVariant virtual_hook(const QVariant &data);
 434     virtual QAccessible2Interface *interface_cast(QAccessible2::InterfaceType)
 435     { return 0; }
 436 };
 437
 438
 439 class Q_GUI_EXPORT QAccessibleEvent : public QEvent
 440 {
 441 public:
 442     inline QAccessibleEvent(Type type, int child);
 443     inline int child() const { return c; }
 444     inline QString value() const { return val; }
 445     inline void setValue(const QString &aText) { val = aText; }
 446
 447 private:
 448     int c;
 449     QString val;
 450 };
 451
 452 inline QAccessibleEvent::QAccessibleEvent(Type atype, int achild)
 453     : QEvent(atype), c(achild) {}
 454
 455 #define QAccessibleInterface_iid "com.trolltech.Qt.QAccessibleInterface"
 456 Q_DECLARE_INTERFACE(QAccessibleInterface, QAccessibleInterface_iid)
 457
 458 #endif // QT_NO_ACCESSIBILITY
 459
 460 QT_END_NAMESPACE
 461
 462 QT_END_HEADER
 463
 464 #endif // QACCESSIBLE_H