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         Announcement         = 0x80D0,
0105         IdentifierChanged    = 0x80E0,
0106         RoleChanged          = 0x80E1,
0107
0108         // was declared after AcceleratorChanged, without explicit value
0109         InvalidEvent                    = AcceleratorChanged + 1,
0110     };
0111     Q_ENUM(Event)
0112
0113     // 64 bit enums seem hard on some platforms (windows...)
0114     // which makes using a bit field a sensible alternative
0115     struct State {
0116         // http://msdn.microsoft.com/en-us/library/ms697270.aspx
0117         quint64 disabled : 1; // used to be Unavailable
0118         quint64 selected : 1;
0119         quint64 focusable : 1;
0120         quint64 focused : 1;
0121         quint64 pressed : 1;
0122         quint64 checkable : 1;
0123         quint64 checked : 1;
0124         quint64 checkStateMixed : 1; // used to be Mixed
0125         quint64 readOnly : 1;
0126         quint64 hotTracked : 1;
0127         quint64 defaultButton : 1;
0128         quint64 expanded : 1;
0129         quint64 collapsed : 1;
0130         quint64 busy : 1;
0131         quint64 expandable : 1;
0132         quint64 marqueed : 1;
0133         quint64 animated : 1;
0134         quint64 invisible : 1;
0135         quint64 offscreen : 1;
0136         quint64 sizeable : 1;
0137         quint64 movable : 1;
0138         quint64 selfVoicing : 1;
0139         quint64 selectable : 1;
0140         quint64 linked : 1;
0141         quint64 traversed : 1;
0142         quint64 multiSelectable : 1;
0143         quint64 extSelectable : 1;
0144         quint64 passwordEdit : 1; // used to be Protected
0145         quint64 hasPopup : 1;
0146         quint64 modal : 1;
0147
0148         // IA2 - we chose to not add some IA2 states for now
0149         // Below the ones that seem helpful
0150         quint64 active : 1;
0151         quint64 invalid : 1; // = defunct
0152         quint64 editable : 1;
0153         quint64 multiLine : 1;
0154         quint64 selectableText : 1;
0155         quint64 supportsAutoCompletion : 1;
0156
0157         quint64 searchEdit : 1;
0158
0159         // quint64 invalidEntry : 1;
0160         // quint64 managesDescendants : 1;
0161         // quint64 singleLine : 1; // we have multi line, this is redundant.
0162         // quint64 stale : 1;
0163         // quint64 transient : 1;
0164         // quint64 pinned : 1;
0165
0166         // Apple - see http://mattgemmell.com/2010/12/19/accessibility-for-iphone-and-ipad-apps/
0167         // quint64 playsSound : 1;
0168         // quint64 summaryElement : 1;
0169         // quint64 updatesFrequently : 1;
0170         // quint64 adjustable : 1;
0171         // more and not included here: http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html
0172
0173         // MSAA
0174         // quint64 alertLow : 1;
0175         // quint64 alertMedium : 1;
0176         // quint64 alertHigh : 1;
0177
0178         Q_DECL_UNUSED_MEMBER quint64 qt_reserved : 27;
0179
0180         State() {
0181             std::memset(this, 0, sizeof(State));
0182         }
0183         friend inline bool operator==(const QAccessible::State &first, const QAccessible::State &second)
0184         {
0185             static_assert(std::has_unique_object_representations_v<State>,
0186                           "memcmp() cannot be used on types with padding");
0187             return std::memcmp(&first, &second, sizeof(QAccessible::State)) == 0;
0188         }
0189     };
0190
0191
0192
0193
0194
0195     enum Role {
0196         NoRole         = 0x00000000,
0197         TitleBar       = 0x00000001,
0198         MenuBar        = 0x00000002,
0199         ScrollBar      = 0x00000003,
0200         Grip           = 0x00000004,
0201         Sound          = 0x00000005,
0202         Cursor         = 0x00000006,
0203         Caret          = 0x00000007,
0204         AlertMessage   = 0x00000008,
0205         Window         = 0x00000009,
0206         Client         = 0x0000000A,
0207         PopupMenu      = 0x0000000B,
0208         MenuItem       = 0x0000000C,
0209         ToolTip        = 0x0000000D,
0210         Application    = 0x0000000E,
0211         Document       = 0x0000000F,
0212         Pane           = 0x00000010,
0213         Chart          = 0x00000011,
0214         Dialog         = 0x00000012,
0215         Border         = 0x00000013,
0216         Grouping       = 0x00000014,
0217         Separator      = 0x00000015,
0218         ToolBar        = 0x00000016,
0219         StatusBar      = 0x00000017,
0220         Table          = 0x00000018,
0221         ColumnHeader   = 0x00000019,
0222         RowHeader      = 0x0000001A,
0223         Column         = 0x0000001B,
0224         Row            = 0x0000001C,
0225         Cell           = 0x0000001D,
0226         Link           = 0x0000001E,
0227         HelpBalloon    = 0x0000001F,
0228         Assistant      = 0x00000020,
0229         List           = 0x00000021,
0230         ListItem       = 0x00000022,
0231         Tree           = 0x00000023,
0232         TreeItem       = 0x00000024,
0233         PageTab        = 0x00000025,
0234         PropertyPage   = 0x00000026,
0235         Indicator      = 0x00000027,
0236         Graphic        = 0x00000028,
0237         StaticText     = 0x00000029,
0238         EditableText   = 0x0000002A,  // Editable, selectable, etc.
0239         Button         = 0x0000002B,
0240 #ifndef Q_QDOC
0241         PushButton     = Button, // deprecated
0242 #endif
0243         CheckBox       = 0x0000002C,
0244         RadioButton    = 0x0000002D,
0245         ComboBox       = 0x0000002E,
0246         // DropList       = 0x0000002F,
0247         ProgressBar    = 0x00000030,
0248         Dial           = 0x00000031,
0249         HotkeyField    = 0x00000032,
0250         Slider         = 0x00000033,
0251         SpinBox        = 0x00000034,
0252         Canvas         = 0x00000035, // MSAA: ROLE_SYSTEM_DIAGRAM - The object represents a graphical image that is used to diagram data.
0253         Animation      = 0x00000036,
0254         Equation       = 0x00000037,
0255         ButtonDropDown = 0x00000038, // The object represents a button that expands a grid.
0256         ButtonMenu     = 0x00000039,
0257         ButtonDropGrid = 0x0000003A,
0258         Whitespace     = 0x0000003B, // The object represents blank space between other objects.
0259         PageTabList    = 0x0000003C,
0260         Clock          = 0x0000003D,
0261         Splitter       = 0x0000003E,
0262         // Reserved space in case MSAA roles needs to be added
0263
0264         // Additional Qt roles where enum value does not map directly to MSAA:
0265         LayeredPane    = 0x00000080,
0266         Terminal       = 0x00000081,
0267         Desktop        = 0x00000082,
0268         Paragraph      = 0x00000083,
0269         WebDocument    = 0x00000084,
0270         Section        = 0x00000085,
0271         Notification   = 0x00000086,
0272         Switch         = 0x00000087,
0273
0274         // IAccessible2 roles
0275         // IA2_ROLE_CANVAS = 0x401, // An object that can be drawn into and to manage events from the objects drawn into it
0276         // IA2_ROLE_CAPTION = 0x402,
0277         // IA2_ROLE_CHECK_MENU_ITEM = 0x403,
0278         ColorChooser = 0x404,
0279         // IA2_ROLE_DATE_EDITOR = 0x405,
0280         // IA2_ROLE_DESKTOP_ICON = 0x406,
0281         // IA2_ROLE_DESKTOP_PANE = 0x407,
0282         // IA2_ROLE_DIRECTORY_PANE = 0x408,
0283         // IA2_ROLE_EDITBAR = 0x409,
0284         // IA2_ROLE_EMBEDDED_OBJECT = 0x40A,
0285         // IA2_ROLE_ENDNOTE = 0x40B,
0286         // IA2_ROLE_FILE_CHOOSER = 0x40C,
0287         // IA2_ROLE_FONT_CHOOSER = 0x40D,
0288         Footer      = 0x40E,
0289         // IA2_ROLE_FOOTNOTE = 0x40F,
0290         Form        = 0x410,
0291         // some platforms (windows and at-spi) use Frame for regular windows
0292         // because window was taken for tool/dock windows by MSAA
0293         // Frame = 0x411,
0294         // IA2_ROLE_GLASS_PANE = 0x412,
0295         // IA2_ROLE_HEADER = 0x413,
0296         Heading  = 0x414,
0297         // IA2_ROLE_ICON = 0x415,
0298         // IA2_ROLE_IMAGE_MAP = 0x416,
0299         // IA2_ROLE_INPUT_METHOD_WINDOW = 0x417,
0300         // IA2_ROLE_INTERNAL_FRAME = 0x418,
0301         // IA2_ROLE_LABEL = 0x419,
0302         // IA2_ROLE_LAYERED_PANE = 0x41A,
0303         Note = 0x41B,
0304         // IA2_ROLE_OPTION_PANE = 0x41C,
0305         // IA2_ROLE_PAGE = 0x41D,
0306         // IA2_ROLE_PARAGRAPH = 0x42E,
0307         // IA2_ROLE_RADIO_MENU_ITEM = 0x41F,
0308         // IA2_ROLE_REDUNDANT_OBJECT = 0x420,
0309         // IA2_ROLE_ROOT_PANE = 0x421,
0310         // IA2_ROLE_RULER = 0x422,
0311         // IA2_ROLE_SCROLL_PANE = 0x423,
0312         // IA2_ROLE_SECTION = 0x424,
0313         // IA2_ROLE_SHAPE = 0x425,
0314         // IA2_ROLE_SPLIT_PANE = 0x426,
0315         // IA2_ROLE_TEAR_OFF_MENU = 0x427,
0316         // IA2_ROLE_TERMINAL = 0x428,
0317         // IA2_ROLE_TEXT_FRAME = 0x429,
0318         // IA2_ROLE_TOGGLE_BUTTON = 0x42A,
0319         // IA2_ROLE_VIEW_PORT = 0x42B,
0320         ComplementaryContent = 0x42C,
0321         // IA2_ROLE_LANDMARK = 0x42D,
0322         // IA2_ROLE_LEVEL_BAR = 0x42E,
0323         // IA2_ROLE_CONTENT_DELETION = 0x42F,
0324         // IA2_ROLE_CONTENT_INSERTION = 0x430,
0325         BlockQuote = 0x431,
0326         // IA2_ROLE_MARK = 0x432,
0327         // IA2_ROLE_SUGGESTION = 0x433,
0328         // IA2_ROLE_COMMENT = = 0x434,
0329
0330         UserRole       = 0x0000ffff
0331     };
0332     Q_ENUM(Role)
0333
0334     enum Text {
0335         Name         = 0,
0336         Description,
0337         Value,
0338         Help,
0339         Accelerator,
0340         DebugDescription,
0341         Identifier,
0342         UserText     = 0x0000ffff
0343     };
0344
0345     enum RelationFlag {
0346         Label         = 0x00000001,
0347         Labelled      = 0x00000002,
0348         Controller    = 0x00000004,
0349         Controlled    = 0x00000008,
0350         DescriptionFor = 0x00000010,
0351         Described     = 0x00000020,
0352         FlowsFrom     = 0x00000040,
0353         FlowsTo       = 0x00000080,
0354         AllRelations  = 0xffffffff
0355     };
0356     Q_DECLARE_FLAGS(Relation, RelationFlag)
0357
0358     enum InterfaceType
0359     {
0360         TextInterface,
0361         EditableTextInterface,
0362         ValueInterface,
0363         ActionInterface,
0364         ImageInterface,
0365         TableInterface,
0366         TableCellInterface,
0367         HyperlinkInterface,
0368         SelectionInterface,
0369         AttributesInterface,
0370     };
0371
0372     enum TextBoundaryType {
0373         CharBoundary,
0374         WordBoundary,
0375         SentenceBoundary,
0376         ParagraphBoundary,
0377         LineBoundary,
0378         NoBoundary
0379     };
0380
0381     enum class Attribute {
0382         Custom,
0383         Level,
0384         Locale,
0385         Orientation,
0386     };
0387     Q_ENUM(Attribute)
0388
0389     enum class AnnouncementPoliteness {
0390         Polite,
0391         Assertive,
0392     };
0393     Q_ENUM(AnnouncementPoliteness)
0394
0395     typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
0396     typedef void(*UpdateHandler)(QAccessibleEvent *event);
0397     typedef void(*RootObjectHandler)(QObject*);
0398
0399     typedef unsigned Id;
0400
0401     static void installFactory(InterfaceFactory);
0402     static void removeFactory(InterfaceFactory);
0403     static UpdateHandler installUpdateHandler(UpdateHandler);
0404     static RootObjectHandler installRootObjectHandler(RootObjectHandler);
0405
0406     class Q_GUI_EXPORT ActivationObserver
0407     {
0408     public:
0409         virtual ~ActivationObserver();
0410         virtual void accessibilityActiveChanged(bool active) = 0;
0411     };
0412     static void installActivationObserver(ActivationObserver *);
0413     static void removeActivationObserver(ActivationObserver *);
0414
0415     static QAccessibleInterface *queryAccessibleInterface(QObject *);
0416     static Id uniqueId(QAccessibleInterface *iface);
0417     static QAccessibleInterface *accessibleInterface(Id uniqueId);
0418     static Id registerAccessibleInterface(QAccessibleInterface *iface);
0419     static void deleteAccessibleInterface(Id uniqueId);
0420
0421     static void updateAccessibility(QAccessibleEvent *event);
0422
0423     static bool isActive();
0424     static void setActive(bool active);
0425     static void setRootObject(QObject *object);
0426
0427     static void cleanup();
0428
0429     static std::pair< int, int > qAccessibleTextBoundaryHelper(const QTextCursor &cursor, TextBoundaryType boundaryType);
0430
0431 private:
0432     static UpdateHandler updateHandler;
0433     static RootObjectHandler rootObjectHandler;
0434
0435     QAccessible() {}
0436
0437     friend class QAccessibleCache;
0438 };
0439
0440 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
0441
0442 QT_END_NAMESPACE
0443
0444 #endif // QT_CONFIG(accessibility)
0445 #endif // QACCESSIBLE_BASE_H