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
0107         // was declared after AcceleratorChanged, without explicit value
0108         InvalidEvent                    = AcceleratorChanged + 1,
0109     };
0110     Q_ENUM(Event)
0111
0112     // 64 bit enums seem hard on some platforms (windows...)
0113     // which makes using a bit field a sensible alternative
0114     struct State {
0115         // http://msdn.microsoft.com/en-us/library/ms697270.aspx
0116         quint64 disabled : 1; // used to be Unavailable
0117         quint64 selected : 1;
0118         quint64 focusable : 1;
0119         quint64 focused : 1;
0120         quint64 pressed : 1;
0121         quint64 checkable : 1;
0122         quint64 checked : 1;
0123         quint64 checkStateMixed : 1; // used to be Mixed
0124         quint64 readOnly : 1;
0125         quint64 hotTracked : 1;
0126         quint64 defaultButton : 1;
0127         quint64 expanded : 1;
0128         quint64 collapsed : 1;
0129         quint64 busy : 1;
0130         quint64 expandable : 1;
0131         quint64 marqueed : 1;
0132         quint64 animated : 1;
0133         quint64 invisible : 1;
0134         quint64 offscreen : 1;
0135         quint64 sizeable : 1;
0136         quint64 movable : 1;
0137         quint64 selfVoicing : 1;
0138         quint64 selectable : 1;
0139         quint64 linked : 1;
0140         quint64 traversed : 1;
0141         quint64 multiSelectable : 1;
0142         quint64 extSelectable : 1;
0143         quint64 passwordEdit : 1; // used to be Protected
0144         quint64 hasPopup : 1;
0145         quint64 modal : 1;
0146
0147         // IA2 - we chose to not add some IA2 states for now
0148         // Below the ones that seem helpful
0149         quint64 active : 1;
0150         quint64 invalid : 1; // = defunct
0151         quint64 editable : 1;
0152         quint64 multiLine : 1;
0153         quint64 selectableText : 1;
0154         quint64 supportsAutoCompletion : 1;
0155
0156         quint64 searchEdit : 1;
0157
0158         // quint64 horizontal : 1;
0159         // quint64 vertical : 1;
0160         // quint64 invalidEntry : 1;
0161         // quint64 managesDescendants : 1;
0162         // quint64 singleLine : 1; // we have multi line, this is redundant.
0163         // quint64 stale : 1;
0164         // quint64 transient : 1;
0165         // quint64 pinned : 1;
0166
0167         // Apple - see http://mattgemmell.com/2010/12/19/accessibility-for-iphone-and-ipad-apps/
0168         // quint64 playsSound : 1;
0169         // quint64 summaryElement : 1;
0170         // quint64 updatesFrequently : 1;
0171         // quint64 adjustable : 1;
0172         // more and not included here: http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Attributes.html
0173
0174         // MSAA
0175         // quint64 alertLow : 1;
0176         // quint64 alertMedium : 1;
0177         // quint64 alertHigh : 1;
0178
0179         Q_DECL_UNUSED_MEMBER quint64 qt_reserved : 27;
0180
0181         State() {
0182             std::memset(this, 0, sizeof(State));
0183         }
0184         friend inline bool operator==(const QAccessible::State &first, const QAccessible::State &second)
0185         {
0186             static_assert(std::has_unique_object_representations_v<State>,
0187                           "memcmp() cannot be used on types with padding");
0188             return std::memcmp(&first, &second, sizeof(QAccessible::State)) == 0;
0189         }
0190     };
0191
0192
0193
0194
0195
0196     enum Role {
0197         NoRole         = 0x00000000,
0198         TitleBar       = 0x00000001,
0199         MenuBar        = 0x00000002,
0200         ScrollBar      = 0x00000003,
0201         Grip           = 0x00000004,
0202         Sound          = 0x00000005,
0203         Cursor         = 0x00000006,
0204         Caret          = 0x00000007,
0205         AlertMessage   = 0x00000008,
0206         Window         = 0x00000009,
0207         Client         = 0x0000000A,
0208         PopupMenu      = 0x0000000B,
0209         MenuItem       = 0x0000000C,
0210         ToolTip        = 0x0000000D,
0211         Application    = 0x0000000E,
0212         Document       = 0x0000000F,
0213         Pane           = 0x00000010,
0214         Chart          = 0x00000011,
0215         Dialog         = 0x00000012,
0216         Border         = 0x00000013,
0217         Grouping       = 0x00000014,
0218         Separator      = 0x00000015,
0219         ToolBar        = 0x00000016,
0220         StatusBar      = 0x00000017,
0221         Table          = 0x00000018,
0222         ColumnHeader   = 0x00000019,
0223         RowHeader      = 0x0000001A,
0224         Column         = 0x0000001B,
0225         Row            = 0x0000001C,
0226         Cell           = 0x0000001D,
0227         Link           = 0x0000001E,
0228         HelpBalloon    = 0x0000001F,
0229         Assistant      = 0x00000020,
0230         List           = 0x00000021,
0231         ListItem       = 0x00000022,
0232         Tree           = 0x00000023,
0233         TreeItem       = 0x00000024,
0234         PageTab        = 0x00000025,
0235         PropertyPage   = 0x00000026,
0236         Indicator      = 0x00000027,
0237         Graphic        = 0x00000028,
0238         StaticText     = 0x00000029,
0239         EditableText   = 0x0000002A,  // Editable, selectable, etc.
0240         Button         = 0x0000002B,
0241 #ifndef Q_QDOC
0242         PushButton     = Button, // deprecated
0243 #endif
0244         CheckBox       = 0x0000002C,
0245         RadioButton    = 0x0000002D,
0246         ComboBox       = 0x0000002E,
0247         // DropList       = 0x0000002F,
0248         ProgressBar    = 0x00000030,
0249         Dial           = 0x00000031,
0250         HotkeyField    = 0x00000032,
0251         Slider         = 0x00000033,
0252         SpinBox        = 0x00000034,
0253         Canvas         = 0x00000035, // MSAA: ROLE_SYSTEM_DIAGRAM - The object represents a graphical image that is used to diagram data.
0254         Animation      = 0x00000036,
0255         Equation       = 0x00000037,
0256         ButtonDropDown = 0x00000038, // The object represents a button that expands a grid.
0257         ButtonMenu     = 0x00000039,
0258         ButtonDropGrid = 0x0000003A,
0259         Whitespace     = 0x0000003B, // The object represents blank space between other objects.
0260         PageTabList    = 0x0000003C,
0261         Clock          = 0x0000003D,
0262         Splitter       = 0x0000003E,
0263         // Reserved space in case MSAA roles needs to be added
0264
0265         // Additional Qt roles where enum value does not map directly to MSAA:
0266         LayeredPane    = 0x00000080,
0267         Terminal       = 0x00000081,
0268         Desktop        = 0x00000082,
0269         Paragraph      = 0x00000083,
0270         WebDocument    = 0x00000084,
0271         Section        = 0x00000085,
0272         Notification   = 0x00000086,
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     };
0386     Q_ENUM(Attribute)
0387
0388     enum class AnnouncementPoliteness {
0389         Polite,
0390         Assertive,
0391     };
0392     Q_ENUM(AnnouncementPoliteness)
0393
0394     typedef QAccessibleInterface*(*InterfaceFactory)(const QString &key, QObject*);
0395     typedef void(*UpdateHandler)(QAccessibleEvent *event);
0396     typedef void(*RootObjectHandler)(QObject*);
0397
0398     typedef unsigned Id;
0399
0400     static void installFactory(InterfaceFactory);
0401     static void removeFactory(InterfaceFactory);
0402     static UpdateHandler installUpdateHandler(UpdateHandler);
0403     static RootObjectHandler installRootObjectHandler(RootObjectHandler);
0404
0405     class Q_GUI_EXPORT ActivationObserver
0406     {
0407     public:
0408         virtual ~ActivationObserver();
0409         virtual void accessibilityActiveChanged(bool active) = 0;
0410     };
0411     static void installActivationObserver(ActivationObserver *);
0412     static void removeActivationObserver(ActivationObserver *);
0413
0414     static QAccessibleInterface *queryAccessibleInterface(QObject *);
0415     static Id uniqueId(QAccessibleInterface *iface);
0416     static QAccessibleInterface *accessibleInterface(Id uniqueId);
0417     static Id registerAccessibleInterface(QAccessibleInterface *iface);
0418     static void deleteAccessibleInterface(Id uniqueId);
0419
0420     static void updateAccessibility(QAccessibleEvent *event);
0421
0422     static bool isActive();
0423     static void setActive(bool active);
0424     static void setRootObject(QObject *object);
0425
0426     static void cleanup();
0427
0428     static std::pair< int, int > qAccessibleTextBoundaryHelper(const QTextCursor &cursor, TextBoundaryType boundaryType);
0429
0430 private:
0431     static UpdateHandler updateHandler;
0432     static RootObjectHandler rootObjectHandler;
0433
0434     QAccessible() {}
0435
0436     friend class QAccessibleCache;
0437 };
0438
0439 Q_DECLARE_OPERATORS_FOR_FLAGS(QAccessible::Relation)
0440
0441 QT_END_NAMESPACE
0442
0443 #endif // QT_CONFIG(accessibility)
0444 #endif // QACCESSIBLE_BASE_H