QAccessible Class

The QAccessible class provides enums and static functions related to accessibility. More...

Header:	#include <QAccessible>
CMake:	find_package(Qt6 COMPONENTS Gui REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake:	QT += gui

• List of all members, including inherited members

Public Types

struct	State
enum	Event { AcceleratorChanged, ActionChanged, ActiveDescendantChanged, Alert, AttributeChanged, …, VisibleDataChanged }
	Id
	InterfaceFactory
enum	InterfaceType { TextInterface, ValueInterface, ActionInterface, TableInterface, TableCellInterface, HyperlinkInterface }
flags	Relation
enum	RelationFlag { Label, Labelled, Controller, Controlled, AllRelations }
enum	Role { AlertMessage, Animation, Application, Assistant, Border, …, Window }
enum	Text { Name, Description, Value, Help, Accelerator, UserText }
enum	TextBoundaryType { CharBoundary, WordBoundary, SentenceBoundary, ParagraphBoundary, LineBoundary, NoBoundary }

Static Public Members

QAccessibleInterface *	accessibleInterface(QAccessible::Id id)
void	deleteAccessibleInterface(QAccessible::Id id)
void	installFactory(QAccessible::InterfaceFactory factory)
bool	isActive()
QAccessibleInterface *	queryAccessibleInterface(QObject *object)
QAccessible::Id	registerAccessibleInterface(QAccessibleInterface *iface)
void	removeFactory(QAccessible::InterfaceFactory factory)
void	setRootObject(QObject *object)
QAccessible::Id	uniqueId(QAccessibleInterface *iface)
void	updateAccessibility(QAccessibleEvent *event)

Detailed Description

This class is part of Accessibility for QWidget Applications.

Accessible applications can be used by people who are not able to use applications by conventional means.

The functions in this class are used for communication between accessible applications (also called AT Servers) and accessibility tools (AT Clients), such as screen readers and braille displays. Clients and servers communicate in the following way:

• AT Servers notify the clients about events through calls to the updateAccessibility() function.
• AT Clients request information about the objects in the server. The QAccessibleInterface class is the core interface, and encapsulates this information in a pure virtual API. Implementations of the interface are provided by Qt through the queryAccessibleInterface() API.

The communication between servers and clients is initialized by the setRootObject() function. Function pointers can be installed to replace or extend the default behavior of the static functions in QAccessible.

Qt supports Microsoft Active Accessibility (MSAA), macOS Accessibility, and the Unix/X11 AT-SPI standard. Other backends can be supported using QAccessibleBridge.

In the Unix/X11 AT-SPI implementation, applications become accessible when two conditions are met:

• org.a11y.Status.IsEnabled DBus property is true
• org.a11y.Status.ScreenReaderEnabled DBus property is true

An alternative to setting the DBus AT-SPI properties is to set the QT_LINUX_ACCESSIBILITY_ALWAYS_ON environment variable.

In addition to QAccessible's static functions, Qt offers one generic interface, QAccessibleInterface, that can be used to wrap all widgets and objects (e.g., QPushButton). This single interface provides all the metadata necessary for the assistive technologies. Qt provides implementations of this interface for its built-in widgets as plugins.

When you develop custom widgets, you can create custom subclasses of QAccessibleInterface and distribute them as plugins (using QAccessiblePlugin) or compile them into the application. Likewise, Qt's predefined accessibility support can be built as plugin (the default) or directly into the Qt library. The main advantage of using plugins is that the accessibility classes are only loaded into memory if they are actually used; they don't slow down the common case where no assistive technology is being used.

Qt also includes two convenience classes, QAccessibleObject and QAccessibleWidget, that inherit from QAccessibleInterface and provide the lowest common denominator of metadata (e.g., widget geometry, window title, basic help text). You can use them as base classes when wrapping your custom QObject or QWidget subclasses.

See also QAccessibleInterface.

Member Type Documentation

enum QAccessible::Event

This enum type defines accessible event types.

Constant	Value	Description
QAccessible::AcceleratorChanged	0x80C0	The keyboard accelerator for an action has been changed.
QAccessible::ActionChanged	0x0101	An action has been changed.
QAccessible::ActiveDescendantChanged	0x0102
QAccessible::Alert	0x0002	A system alert (e.g., a message from a QMessageBox)
QAccessible::AttributeChanged	0x0103
QAccessible::ContextHelpEnd	0x000D	Context help (QWhatsThis) for an object is finished.
QAccessible::ContextHelpStart	0x000C	Context help (QWhatsThis) for an object is initiated.
QAccessible::DefaultActionChanged	0x80B0	The default QAccessible::Action for the accessible object has changed.
QAccessible::DescriptionChanged	0x800D	The object's QAccessible::Description changed.
QAccessible::DialogEnd	0x0011	A dialog (QDialog) has been hidden
QAccessible::DialogStart	0x0010	A dialog (QDialog) has been set visible.
QAccessible::DocumentContentChanged	0x0104	The contents of a text document have changed.
QAccessible::DocumentLoadComplete	0x0105	A document has been loaded.
QAccessible::DocumentLoadStopped	0x0106	A document load has been stopped.
QAccessible::DocumentReload	0x0107	A document reload has been initiated.
QAccessible::DragDropEnd	0x000F	A drag and drop operation is about to finished.
QAccessible::DragDropStart	0x000E	A drag and drop operation is about to be initiated.
QAccessible::Focus	0x8005	An object has gained keyboard focus.
QAccessible::ForegroundChanged	0x0003	A window has been activated (i.e., a new window has gained focus on the desktop).
QAccessible::HelpChanged	0x80A0	The QAccessible::Help text property of an object has changed.
QAccessible::HyperlinkEndIndexChanged	0x0108	The end position of the display text for a hypertext link has changed.
QAccessible::HyperlinkNumberOfAnchorsChanged	0x0109	The number of anchors in a hypertext link has changed, perhaps because the display text has been split to provide more than one link.
QAccessible::HyperlinkSelectedLinkChanged	0x010A	The link for the selected hypertext link has changed.
QAccessible::HyperlinkStartIndexChanged	0x010D	The start position of the display text for a hypertext link has changed.
QAccessible::HypertextChanged	0x010E	The display text for a hypertext link has changed.
QAccessible::HypertextLinkActivated	0x010B	A hypertext link has been activated, perhaps by being clicked or via a key press.
QAccessible::HypertextLinkSelected	0x010C	A hypertext link has been selected.
QAccessible::HypertextNLinksChanged	0x010F
QAccessible::LocationChanged	0x800B	An object's location on the screen has changed.
QAccessible::MenuCommand	0x0018	A menu item is triggered.
QAccessible::MenuEnd	0x0005	A menu has been closed (Qt uses PopupMenuEnd for all menus).
QAccessible::MenuStart	0x0004	A menu has been opened on the menubar (Qt uses PopupMenuStart for all menus).
QAccessible::NameChanged	0x800C	The QAccessible::Name property of an object has changed.
QAccessible::ObjectAttributeChanged	0x0110
QAccessible::ObjectCreated	0x8000	A new object is created.
QAccessible::ObjectDestroyed	0x8001	An object is deleted.
QAccessible::ObjectHide	0x8003	An object is hidden; for example, with QWidget::hide(). Any children the object that is hidden has do not send this event. It is not sent when an object is hidden as it is being obcured by others.
QAccessible::ObjectReorder	0x8004	A layout or item view has added, removed, or moved an object (Qt does not use this event).
QAccessible::ObjectShow	0x8002	An object is displayed; for example, with QWidget::show().
QAccessible::PageChanged	0x0111
QAccessible::ParentChanged	0x800F	An object's parent object changed.
QAccessible::PopupMenuEnd	0x0007	A pop-up menu has closed.
QAccessible::PopupMenuStart	0x0006	A pop-up menu has opened.
QAccessible::ScrollingEnd	0x0013	A scrollbar scroll operation has ended (the mouse has released the slider handle).
QAccessible::ScrollingStart	0x0012	A scrollbar scroll operation is about to start; this may be caused by a mouse press on the slider handle, for example.
QAccessible::SectionChanged	0x0112
QAccessible::SelectionAdd	0x8007	An item has been added to the selection in an item view.
QAccessible::SelectionRemove	0x8008	An item has been removed from an item view selection.
QAccessible::Selection	0x8006	The selection has changed in a menu or item view.
QAccessible::SelectionWithin	0x8009	Several changes to a selection has occurred in an item view.
QAccessible::SoundPlayed	0x0001	A sound has been played by an object
QAccessible::TableCaptionChanged	0x0113	A table caption has been changed.
QAccessible::TableColumnDescriptionChanged	0x0114	The description of a table column, typically found in the column's header, has been changed.
QAccessible::TableColumnHeaderChanged	0x0115	A table column header has been changed.
QAccessible::TableRowDescriptionChanged	0x0117	The description of a table row, typically found in the row's header, has been changed.
QAccessible::TableRowHeaderChanged	0x0118	A table row header has been changed.
QAccessible::TableSummaryChanged	0x0119	The summary of a table has been changed.
QAccessible::TextColumnChanged	0x011D	A text column has been changed.
QAccessible::VisibleDataChanged	0x0122

The values for this enum are defined to be the same as those defined in the IAccessible2 and MSAA specifications.

QAccessible::Id

Synonym for unsigned, used by the QAccessibleInterface cache.

QAccessible::InterfaceFactory

This is a typedef for a pointer to a function with the following signature:

typedef QAccessibleInterface *myFactoryFunction(const QString &key, QObject *);

The function receives a QString and a QObject pointer, where the QString is the key identifying the interface. The QObject is used to pass on to the QAccessibleInterface so that it can hold a reference to it.

If the key and the QObject does not have a corresponding QAccessibleInterface, nullptr will be returned.

Installed factories are called by queryAccessibilityInterface() until one provides an interface.

enum QAccessible::InterfaceType

QAccessibleInterface supports several sub interfaces. In order to provide more information about some objects, their accessible representation should implement one or more of these interfaces.

Constant	Value	Description
QAccessible::TextInterface	0	For text that supports selections or is more than one line. Simple labels do not need to implement this interface.
QAccessible::ValueInterface	2	For objects that are used to manipulate a value, for example slider or scroll bar.
QAccessible::ActionInterface	3	For interactive objects that allow the user to trigger an action. Basically everything that allows for example mouse interaction.
QAccessible::TableInterface	5	For lists, tables and trees.
QAccessible::TableCellInterface	6	For cells in a TableInterface object.
QAccessible::HyperlinkInterface	7	For hyperlink nodes (usually embedded as children of text nodes)

See also QAccessibleInterface::interface_cast(), QAccessibleTextInterface, QAccessibleValueInterface, QAccessibleActionInterface, QAccessibleTableInterface, and QAccessibleTableCellInterface.

enum QAccessible::RelationFlagflags QAccessible::Relation

This enum type defines bit flags that can be combined to indicate the relationship between two accessible objects.

Constant	Value	Description
QAccessible::Label	0x00000001	The first object is the label of the second object.
QAccessible::Labelled	0x00000002	The first object is labelled by the second object.
QAccessible::Controller	0x00000004	The first object controls the second object.
QAccessible::Controlled	0x00000008	The first object is controlled by the second object.
QAccessible::AllRelations	0xffffffff	Used as a mask to specify that we are interesting in information about all relations

Implementations of relations() return a combination of these flags. Some values are mutually exclusive.

The Relation type is a typedef for QFlags<RelationFlag>. It stores an OR combination of RelationFlag values.

enum QAccessible::Role

This enum defines the role of an accessible object. The roles are:

Constant	Value	Description
QAccessible::AlertMessage	0x00000008	An object that is used to alert the user.
QAccessible::Animation	0x00000036	An object that displays an animation.
QAccessible::Application	0x0000000E	The application's main window.
QAccessible::Assistant	0x00000020	An object that provids interactive help.
QAccessible::Border	0x00000013	An object that represents a border.
QAccessible::ButtonDropDown	0x00000038	A button that drops down a list of items.
QAccessible::ButtonDropGrid	0x0000003A	A button that drops down a grid.
QAccessible::ButtonMenu	0x00000039	A button that drops down a menu.
QAccessible::Canvas	0x00000035	An object that displays graphics that the user can interact with.
QAccessible::Caret	0x00000007	An object that represents the system caret (text cursor).
QAccessible::Cell	0x0000001D	A cell in a table.
QAccessible::Chart	0x00000011	An object that displays a graphical representation of data.
QAccessible::CheckBox	0x0000002C	An object that represents an option that can be checked or unchecked. Some options provide a "mixed" state, e.g. neither checked nor unchecked.
QAccessible::Client	0x0000000A	The client area in a window.
QAccessible::Clock	0x0000003D	A clock displaying time.
QAccessible::ColorChooser	0x404	A dialog that lets the user choose a color.
QAccessible::Column	0x0000001B	A column of cells, usually within a table.
QAccessible::ColumnHeader	0x00000019	A header for a column of data.
QAccessible::ComboBox	0x0000002E	A list of choices that the user can select from.
QAccessible::ComplementaryContent	0x42C	A part of the document or web page that is complementary to the main content, usually a landmark (see WAI-ARIA).
QAccessible::Cursor	0x00000006	An object that represents the mouse cursor.
QAccessible::Desktop	0x00000082	The object represents the desktop or workspace.
QAccessible::Dial	0x00000031	An object that represents a dial or knob.
QAccessible::Dialog	0x00000012	A dialog box.
QAccessible::Document	0x0000000F	A document, for example in an office application.
QAccessible::EditableText	0x0000002A	Editable text such as a line or text edit.
QAccessible::Equation	0x00000037	An object that represents a mathematical equation.
QAccessible::Footer	0x40E	A footer in a page (usually in documents).
QAccessible::Form	0x410	A web form containing controls.
QAccessible::Graphic	0x00000028	A graphic or picture, e.g. an icon.
QAccessible::Grip	0x00000004	A grip that the user can drag to change the size of widgets.
QAccessible::Grouping	0x00000014	An object that represents a logical grouping of other objects.
QAccessible::Heading	0x414	A heading in a document.
QAccessible::HelpBalloon	0x0000001F	An object that displays help in a separate, short lived window.
QAccessible::HotkeyField	0x00000032	A hotkey field that allows the user to enter a key sequence.
QAccessible::Indicator	0x00000027	An indicator that represents a current value or item.
QAccessible::LayeredPane	0x00000080	An object that can contain layered children, e.g. in a stack.
QAccessible::Link	0x0000001E	A link to something else.
QAccessible::List	0x00000021	A list of items, from which the user can select one or more items.
QAccessible::ListItem	0x00000022	An item in a list of items.
QAccessible::MenuBar	0x00000002	A menu bar from which menus are opened by the user.
QAccessible::MenuItem	0x0000000C	An item in a menu or menu bar.
QAccessible::NoRole	0x00000000	The object has no role. This usually indicates an invalid object.
QAccessible::Note	0x41B	A section whose content is parenthetic or ancillary to the main content of the resource.
QAccessible::Notification	0x00000086	An object that represents a notification (e.g. in the system tray). This role only has an effect on Linux.
QAccessible::PageTab	0x00000025	A page tab that the user can select to switch to a different page in a dialog.
QAccessible::PageTabList	0x0000003C	A list of page tabs.
QAccessible::Paragraph	0x00000083	A paragraph of text (usually found in documents).
QAccessible::Pane	0x00000010	A generic container.
QAccessible::PopupMenu	0x0000000B	A menu which lists options that the user can select to perform an action.
QAccessible::ProgressBar	0x00000030	The object displays the progress of an operation in progress.
QAccessible::PropertyPage	0x00000026	A property page where the user can change options and settings.
QAccessible::Button	0x0000002B	A button.
QAccessible::RadioButton	0x0000002D	An object that represents an option that is mutually exclusive with other options.
QAccessible::Row	0x0000001C	A row of cells, usually within a table.
QAccessible::RowHeader	0x0000001A	A header for a row of data.
QAccessible::ScrollBar	0x00000003	A scroll bar, which allows the user to scroll the visible area.
QAccessible::Section	0x00000085	A section (in a document).
QAccessible::Separator	0x00000015	A separator that divides space into logical areas.
QAccessible::Slider	0x00000033	A slider that allows the user to select a value within a given range.
QAccessible::Sound	0x00000005	An object that represents a sound.
QAccessible::SpinBox	0x00000034	A spin box widget that allows the user to enter a value within a given range.
QAccessible::Splitter	0x0000003E	A splitter distributing available space between its child widgets.
QAccessible::StaticText	0x00000029	Static text, such as labels for other widgets.
QAccessible::StatusBar	0x00000017	A status bar.
QAccessible::Table	0x00000018	A table representing data in a grid of rows and columns.
QAccessible::Terminal	0x00000081	A terminal or command line interface.
QAccessible::TitleBar	0x00000001	The title bar caption of a window.
QAccessible::ToolBar	0x00000016	A tool bar, which groups widgets that the user accesses frequently.
QAccessible::ToolTip	0x0000000D	A tool tip which provides information about other objects.
QAccessible::Tree	0x00000023	A list of items in a tree structure.
QAccessible::TreeItem	0x00000024	An item in a tree structure.
QAccessible::UserRole	0x0000ffff	The first value to be used for user defined roles.
QAccessible::WebDocument	0x00000084	HTML document, usually in a browser.
QAccessible::Whitespace	0x0000003B	Blank space between other objects.
QAccessible::Window	0x00000009	A top level window.

enum QAccessible::Text

This enum specifies string information that an accessible object returns.

Constant	Value	Description
QAccessible::Name	0	The name of the object. This can be used both as an identifier or a short description by accessible clients.
QAccessible::Description	1	A short text describing the object.
QAccessible::Value	2	The value of the object.
QAccessible::Help	3	A longer text giving information about how to use the object.
QAccessible::Accelerator	4	The keyboard shortcut that executes the object's default action.
QAccessible::UserText	0x0000ffff	The first value to be used for user defined text.

enum QAccessible::TextBoundaryType

This enum describes different types of text boundaries. It follows the IAccessible2 API and is used in the QAccessibleTextInterface.

Constant	Value	Description
QAccessible::CharBoundary	0	Use individual characters as boundary.
QAccessible::WordBoundary	1	Use words as boundaries.
QAccessible::SentenceBoundary	2	Use sentences as boundary.
QAccessible::ParagraphBoundary	3	Use paragraphs as boundary.
QAccessible::LineBoundary	4	Use newlines as boundary.
QAccessible::NoBoundary	5	No boundary (use the whole text).

See also QAccessibleTextInterface.

Member Function Documentation

[static] QAccessibleInterface *QAccessible::accessibleInterface(QAccessible::Id id)

Returns the QAccessibleInterface belonging to the id.

Returns nullptr if the id is invalid.

[static] void QAccessible::deleteAccessibleInterface(QAccessible::Id id)

Removes the interface belonging to this id from the cache and deletes it. The id becomes invalid an may be re-used by the cache.

[static] void QAccessible::installFactory(QAccessible::InterfaceFactory factory)

Installs the InterfaceFactory factory. The last factory added is the first one used by queryAccessibleInterface().

[static] bool QAccessible::isActive()

Returns true if the platform requested accessibility information.

This function will return false until a tool such as a screen reader accessed the accessibility framework. It is still possible to use QAccessible::queryAccessibleInterface() even if accessibility is not active. But there will be no notifications sent to the platform.

It is recommended to use this function to prevent expensive notifications via updateAccessibility() when they are not needed.

[static] QAccessibleInterface *QAccessible::queryAccessibleInterface(QObject *object)

If a QAccessibleInterface implementation exists for the given object, this function returns a pointer to the implementation; otherwise it returns nullptr.

The function calls all installed factory functions (from most recently installed to least recently installed) until one is found that provides an interface for the class of object. If no factory can provide an accessibility implementation for the class the function loads installed accessibility plugins, and tests if any of the plugins can provide the implementation.

If no implementation for the object's class is available, the function tries to find an implementation for the object's parent class, using the above strategy.

All interfaces are managed by an internal cache and should not be deleted.

[static] QAccessible::Id QAccessible::registerAccessibleInterface(QAccessibleInterface *iface)

Call this function to ensure that manually created interfaces are properly memory managed.

Must only be called exactly once per interface iface. This is implicitly called when calling queryAccessibleInterface, calling this function is only required when QAccessibleInterfaces are instantiated with the "new" operator. This is not recommended, whenever possible use the default functions and let queryAccessibleInterface() take care of this.

When it is necessary to reimplement the QAccessibleInterface::child() function and returning the child after constructing it, this function needs to be called.

[static] void QAccessible::removeFactory(QAccessible::InterfaceFactory factory)

Removes factory from the list of installed InterfaceFactories.

[static] void QAccessible::setRootObject(QObject *object)

Sets the root object of the accessible objects of this application to object. All other accessible objects are reachable using object navigation from the root object.

Normally, it isn't necessary to call this function, because Qt sets the QApplication object as the root object immediately before the event loop is entered in QApplication::exec().

Use QAccessible::installRootObjectHandler() to redirect the function call to a customized handler function.

See also queryAccessibleInterface().

[static] QAccessible::Id QAccessible::uniqueId(QAccessibleInterface *iface)

Returns the unique ID for the QAccessibleInterface iface.

[static] void QAccessible::updateAccessibility(QAccessibleEvent *event)

Notifies about a change that might be relevant for accessibility clients.

event provides details about the change. These include the source of the change and the nature of the change. The event should contain enough information give meaningful notifications.

For example, the type ValueChange indicates that the position of a slider has been changed.

Call this function whenever the state of your accessible object or one of its sub-elements has been changed either programmatically (e.g. by calling QLabel::setText()) or by user interaction.

If there are no accessibility tools listening to this event, the performance penalty for calling this function is small, but if determining the parameters of the call is expensive you can test QAccessible::isActive() to avoid unnecessary computation.