include/QtGui/qaccessible_base.h

0001 // Copyright (C) 2022 The Qt Company Ltd.
0002 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0003
0004 #ifndef QACCESSIBLE_BASE_H
0005 #define QACCESSIBLE_BASE_H
0006
0007 #include <QtGui/qtguiglobal.h>
0008 #if QT_CONFIG(accessibility)
0009
0010 #if 0
0011 // QAccessible class is handled in qaccessible.h
0012 #pragma qt_sync_stop_processing
0013 #endif
0014
0015 #include <QtCore/qobjectdefs.h>
0016
0017 #include <cstring> // memset, memcmp
0018
0019 QT_BEGIN_NAMESPACE
0020
0021 class QAccessibleInterface;
0022 class QAccessibleEvent;
0023 class QTextCursor;
0024
0025 class Q_GUI_EXPORT QAccessible
0026 {
0027     Q_GADGET
0028 public:
0029
0030     enum Event {
0031         SoundPlayed          = 0x0001,
0032         Alert                = 0x0002,
0033         ForegroundChanged    = 0x0003,
0034         MenuStart            = 0x0004,
0035         MenuEnd              = 0x0005,
0036         PopupMenuStart       = 0x0006,
0037         PopupMenuEnd         = 0x0007,
0038         ContextHelpStart     = 0x000C,
0039         ContextHelpEnd       = 0x000D,
0040         DragDropStart        = 0x000E,
0041         DragDropEnd          = 0x000F,
0042         DialogStart          = 0x0010,
0043         DialogEnd            = 0x0011,
0044         ScrollingStart       = 0x0012,
0045         ScrollingEnd         = 0x0013,
0046
0047         MenuCommand          = 0x0018,
0048
0049         // Values from IAccessible2
0050         ActionChanged                    = 0x0101,
0051         ActiveDescendantChanged          = 0x0102,
0052         AttributeChanged                 = 0x0103,
0053         DocumentContentChanged           = 0x0104,
0054         DocumentLoadComplete             = 0x0105,
0055         DocumentLoadStopped              = 0x0106,
0056         DocumentReload                   = 0x0107,
0057         HyperlinkEndIndexChanged         = 0x0108,
0058         HyperlinkNumberOfAnchorsChanged  = 0x0109,
0059         HyperlinkSelectedLinkChanged     = 0x010A,
0060         HypertextLinkActivated           = 0x010B,
0061         HypertextLinkSelected            = 0x010C,
0062         HyperlinkStartIndexChanged       = 0x010D,
0063         HypertextChanged                 = 0x010E,
0064         HypertextNLinksChanged           = 0x010F,
0065         ObjectAttributeChanged           = 0x0110,
0066         PageChanged                      = 0x0111,
0067         SectionChanged                   = 0x0112,
0068         TableCaptionChanged              = 0x0113,
0069         TableColumnDescriptionChanged    = 0x0114,
0070         TableColumnHeaderChanged         = 0x0115,
0071         TableModelChanged                = 0x0116,
0072         TableRowDescriptionChanged       = 0x0117,
0073         TableRowHeaderChanged            = 0x0118,
0074         TableSummaryChanged              = 0x0119,
0075         TextAttributeChanged             = 0x011A,
0076         TextCaretMoved                   = 0x011B,
0077         // TextChanged = 0x011C, is deprecated in IA2, use TextUpdated
0078         TextColumnChanged                = 0x011D,
0079         TextInserted                     = 0x011E,
0080         TextRemoved                      = 0x011F,
0081         TextUpdated                      = 0x0120,
0082         TextSelectionChanged             = 0x0121,
0083         VisibleDataChanged               = 0x0122,
0084
0085         ObjectCreated        = 0x8000,
0086         ObjectDestroyed      = 0x8001,
0087         ObjectShow           = 0x8002,
0088         ObjectHide           = 0x8003,
0089         ObjectReorder        = 0x8004,
0090         Focus                = 0x8005,
0091         Selection            = 0x8006,
0092         SelectionAdd         = 0x8007,
0093         SelectionRemove      = 0x8008,
0094         SelectionWithin      = 0x8009,
0095         StateChanged         = 0x800A,
0096         LocationChanged      = 0x800B,
0097         NameChanged          = 0x800C,
0098         DescriptionChanged   = 0x800D,
0099         ValueChanged         = 0x800E,
0100         ParentChanged        = 0x800F,
0101         HelpChanged          = 0x80A0,
0102         DefaultActionChanged = 0x80B0,
0103         AcceleratorChanged   = 0x80C0,
0104
0105         InvalidEvent
0106     };
0107     Q_ENUM(Event)
0108
0109     // 64 bit enums seem hard on some platforms (windows...)
0110     // which makes using a bit field a sensible alternative
0111     struct State {
0112         // http://msdn.microsoft.com/en-us/library/ms697270.aspx
0113         quint64 disabled : 1; // used to be Unavailable
0114         quint64 selected : 1;
0115         quint64 focusable : 1;
0116         quint64 focused : 1;
0117         quint64 pressed : 1;
0118         quint64 checkable : 1;
0119         quint64 checked : 1;
0120         quint64 checkStateMixed : 1; // used to be Mixed
0121         quint64 readOnly : 1;
0122         quint64 hotTracked : 1;
0123         quint64 defaultButton : 1;
0124         quint64 expanded : 1;
0125         quint64 collapsed : 1;
0126         quint64 busy : 1;
0127         quint64 expandable : 1;
0128         quint64 marqueed : 1;
0129         quint64 animated : 1;
0130         quint64 invisible : 1;
0131         quint64 offscreen : 1;
0132         quint64 sizeable : 1;
0133         quint64 movable : 1;
0134         quint64 selfVoicing : 1;
0135         quint64 selectable : 1;
0136         quint64 linked : 1;
0137         quint64 traversed : 1;
0138         quint64 multiSelectable : 1;
0139         quint64 extSelectable : 1;
0140         quint64 passwordEdit : 1; // used to be Protected
0141         quint64 hasPopup : 1;
0142         quint64 modal : 1;
0143
0144         // IA2 - we chose to not add some IA2 states for now
0145         // Below the ones that seem helpful
0146         quint64 active : 1;
0147         quint64 invalid : 1; // = defunct
0148         quint64 editable : 1;
0149         quint64 multiLine : 1;
0150         quint64 selectableText : 1;
0151         quint64 supportsAutoCompletion : 1;
0152
0153         quint64 searchEdit : 1;
0154
0155         // quint64 horizontal : 1;
0156         // quint64 vertical : 1;
0157         // quint64 invalidEntry : 1;
0158         // quint64 managesDescendants : 1;
0159         // quint64 singleLine : 1; // we have multi line, this is redundant.
0160         // quint64 stale : 1;
0161         // quint64 transient : 1;
0162         // quint64 pinned : 1;
0163
0164         // Apple - see http://mattgemmell.com/2010/12/19/accessibility-for-iphone-and-ipad-apps/
0165         // quint64 playsSound : 1;
0166         // quint64 summaryElement : 1;
0167         // quint64 updatesFrequently : 1;
0168         // quint64 adjustable : 1;
0169         // more and not included here: http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html
0170
0171         // MSAA
0172         // quint64 alertLow : 1;
0173         // quint64 alertMedium : 1;
0174         // quint64 alertHigh : 1;
0175
0176         State() {
0177             std::memset(this, 0, sizeof(State));
0178         }
0179         friend inline bool operator==(const QAccessible::State &first, const QAccessible::State &second)
0180         {
0181             return std::memcmp(&first, &second, sizeof(QAccessible::State)) == 0;
0182         }
0183     };
0184
0185
0186
0187
0188
0189     enum Role {
0190         NoRole         = 0x00000000,
0191         TitleBar       = 0x00000001,
0192         MenuBar        = 0x00000002,
0193         ScrollBar      = 0x00000003,
0194         Grip           = 0x00000004,
0195         Sound          = 0x00000005,
0196         Cursor         = 0x00000006,
0197         Caret          = 0x00000007,
0198         AlertMessage   = 0x00000008,
0199         Window         = 0x00000009,
0200         Client         = 0x0000000A,
0201         PopupMenu      = 0x0000000B,
0202         MenuItem       = 0x0000000C,
0203         ToolTip        = 0x0000000D,
0204         Application    = 0x0000000E,
0205         Document       = 0x0000000F,
0206         Pane           = 0x00000010,
0207         Chart          = 0x00000011,
0208         Dialog         = 0x00000012,
0209         Border         = 0x00000013,
0210         Grouping       = 0x00000014,
0211         Separator      = 0x00000015,
0212         ToolBar        = 0x00000016,
0213         StatusBar      = 0x00000017,
0214         Table          = 0x00000018,
0215         ColumnHeader   = 0x00000019,
0216         RowHeader      = 0x0000001A,
0217         Column         = 0x0000001B,
0218         Row            = 0x0000001C,
0219         Cell           = 0x0000001D,
0220         Link           = 0x0000001E,
0221         HelpBalloon    = 0x0000001F,
0222         Assistant      = 0x00000020,
0223         List           = 0x00000021,
0224         ListItem       = 0x00000022,
0225         Tree           = 0x00000023,
0226         TreeItem       = 0x00000024,
0227         PageTab        = 0x00000025,
0228         PropertyPage   = 0x00000026,
0229         Indicator      = 0x00000027,
0230         Graphic        = 0x00000028,
0231         StaticText     = 0x00000029,
0232         EditableText   = 0x0000002A,  // Editable, selectable, etc.
0233         Button         = 0x0000002B,
0234 #ifndef Q_QDOC
0235         PushButton     = Button, // deprecated
0236 #endif
0237         CheckBox       = 0x0000002C,
0238         RadioButton    = 0x0000002D,
0239         ComboBox       = 0x0000002E,
0240         // DropList       = 0x0000002F,
0241         ProgressBar    = 0x00000030,
0242         Dial           = 0x00000031,
0243         HotkeyField    = 0x00000032,
0244         Slider         = 0x00000033,
0245         SpinBox        = 0x00000034,
0246         Canvas         = 0x00000035, // MSAA: ROLE_SYSTEM_DIAGRAM - The object represents a graphical image that is used to diagram data.
0247         Animation      = 0x00000036,
0248         Equation       = 0x00000037,
0249         ButtonDropDown = 0x00000038, // The object represents a button that expands a grid.
0250         ButtonMenu     = 0x00000039,
0251         ButtonDropGrid = 0x0000003A,
0252         Whitespace     = 0x0000003B, // The object represents blank space between other objects.
0253         PageTabList    = 0x0000003C,
0254         Clock          = 0x0000003D,
0255         Splitter       = 0x0000003E,
0256         // Reserved space in case MSAA roles needs to be added
0257
0258         // Additional Qt roles where enum value does not map directly to MSAA:
0259         LayeredPane    = 0x00000080,
0260         Terminal       = 0x00000081,
0261         Desktop        = 0x00000082,
0262         Paragraph      = 0x00000083,
0263         WebDocument    = 0x00000084,
0264         Section        = 0x00000085,
0265         Notification   = 0x00000086,
0266
0267         // IAccessible2 roles
0268         // IA2_ROLE_CANVAS = 0x401, // An object that can be drawn into and to manage events from the objects drawn into it
0269         // IA2_ROLE_CAPTION = 0x402,
0270         // IA2_ROLE_CHECK_MENU_ITEM = 0x403,
0271         ColorChooser = 0x404,
0272         // IA2_ROLE_DATE_EDITOR = 0x405,
0273         // IA2_ROLE_DESKTOP_ICON = 0x406,
0274         // IA2_ROLE_DESKTOP_PANE = 0x407,
0275         // IA2_ROLE_DIRECTORY_PANE = 0x408,
0276         // IA2_ROLE_EDITBAR = 0x409,
0277         // IA2_ROLE_EMBEDDED_OBJECT = 0x40A,
0278         // IA2_ROLE_ENDNOTE = 0x40B,
0279         // IA2_ROLE_FILE_CHOOSER = 0x40C,
0280         // IA2_ROLE_FONT_CHOOSER = 0x40D,
0281         Footer      = 0x40E,
0282         // IA2_ROLE_FOOTNOTE = 0x40F,
0283         Form        = 0x410,
0284         // some platforms (windows and at-spi) use Frame for regular windows
0285         // because window was taken for tool/dock windows by MSAA
0286         // Frame = 0x411,
0287         // IA2_ROLE_GLASS_PANE = 0x412,
0288         // IA2_ROLE_HEADER = 0x413,
0289         Heading  = 0x414,
0290         // IA2_ROLE_ICON = 0x415,
0291         // IA2_ROLE_IMAGE_MAP = 0x416,
0292         // IA2_ROLE_INPUT_METHOD_WINDOW = 0x417,
0293         // IA2_ROLE_INTERNAL_FRAME = 0x418,
0294         // IA2_ROLE_LABEL = 0x419,
0295         // IA2_ROLE_LAYERED_PANE = 0x41A,
0296         Note = 0x41B,
0297         // IA2_ROLE_OPTION_PANE = 0x41C,
0298         // IA2_ROLE_PAGE = 0x41D,
0299         // IA2_ROLE_PARAGRAPH = 0x42E,
0300         // IA2_ROLE_RADIO_MENU_ITEM = 0x41F,
0301         // IA2_ROLE_REDUNDANT_OBJECT = 0x420,
0302         // IA2_ROLE_ROOT_PANE = 0x421,
0303         // IA2_ROLE_RULER = 0x422,
0304         // IA2_ROLE_SCROLL_PANE = 0x423,
0305         // IA2_ROLE_SECTION = 0x424,
0306         // IA2_ROLE_SHAPE = 0x425,
0307         // IA2_ROLE_SPLIT_PANE = 0x426,
0308         // IA2_ROLE_TEAR_OFF_MENU = 0x427,
0309         // IA2_ROLE_TERMINAL = 0x428,
0310         // IA2_ROLE_TEXT_FRAME = 0x429,
0311         // IA2_ROLE_TOGGLE_BUTTON = 0x42A,
0312         // IA2_ROLE_VIEW_PORT = 0x42B,
0313         ComplementaryContent = 0x42C,
0314
0315         UserRole       = 0x0000ffff
0316     };
0317     Q_ENUM(Role)
0318
0319     enum Text {
0320         Name         = 0,
0321         Description,
0322         Value,
0323         Help,
0324         Accelerator,
0325         DebugDescription,
0326         UserText     = 0x0000ffff
0327     };
0328
0329     enum RelationFlag {
0330         Label         = 0x00000001,
0331         Labelled      = 0x00000002,
0332         Controller    = 0x00000004,
0333         Controlled    = 0x00000008,
0334         DescriptionFor = 0x00000010,
0335         Described     = 0x00000020,
0336         FlowsFrom     = 0x00000040,
0337         FlowsTo       = 0x00000080,
0338         AllRelations  = 0xffffffff
0339     };
0340     Q_DECLARE_FLAGS(Relation, RelationFlag)
0341
0342     enum InterfaceType
0343     {
0344         TextInterface,
0345         EditableTextInterface,
0346         ValueInterface,
0347         ActionInterface,
0348         ImageInterface,
0349         TableInterface,
0350         TableCellInterface,
0351         HyperlinkInterface,
0352         SelectionInterface
0353     };
0354
0355     enum TextBoundaryType {
0356         CharBoundary,
0357         WordBoundary,
0358         SentenceBoundary,
0359         ParagraphBoundary,
0360         LineBoundary,
0361         NoBoundary
0362     };
0363
0364     typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
0365     typedef void(*UpdateHandler)(QAccessibleEvent *event);
0366     typedef void(*RootObjectHandler)(QObject*);
0367
0368     typedef unsigned Id;
0369
0370     static void installFactory(InterfaceFactory);
0371     static void removeFactory(InterfaceFactory);
0372     static UpdateHandler installUpdateHandler(UpdateHandler);
0373     static RootObjectHandler installRootObjectHandler(RootObjectHandler);
0374
0375     class Q_GUI_EXPORT ActivationObserver
0376     {
0377     public:
0378         virtual ~ActivationObserver();
0379         virtual void accessibilityActiveChanged(bool active) = 0;
0380     };
0381     static void installActivationObserver(ActivationObserver *);
0382     static void removeActivationObserver(ActivationObserver *);
0383
0384     static QAccessibleInterface *queryAccessibleInterface(QObject *);
0385     static Id uniqueId(QAccessibleInterface *iface);
0386     static QAccessibleInterface *accessibleInterface(Id uniqueId);
0387     static Id registerAccessibleInterface(QAccessibleInterface *iface);
0388     static void deleteAccessibleInterface(Id uniqueId);
0389
0390     static void updateAccessibility(QAccessibleEvent *event);
0391
0392     static bool isActive();
0393     static void setActive(bool active);
0394     static void setRootObject(QObject *object);
0395
0396     static void cleanup();
0397
0398     static QPair< int, int > qAccessibleTextBoundaryHelper(const QTextCursor &cursor, TextBoundaryType boundaryType);
0399
0400 private:
0401     static UpdateHandler updateHandler;
0402     static RootObjectHandler rootObjectHandler;
0403
0404     QAccessible() {}
0405
0406     friend class QAccessibleCache;
0407 };
0408
0409 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
0410
0411 QT_END_NAMESPACE
0412
0413 #endif // QT_CONFIG(accessibility)
0414 #endif // QACCESSIBLE_BASE_H