QAccessibleclass provides enums and static functions related to accessibility. More…
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
AT Clients request information about the objects in the server. The
QAccessibleInterfaceclass is the core interface, and encapsulates this information in a pure virtual API. Implementations of the interface are provided by Qt through the
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
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
QAccessibleInterfaceand 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,
QAccessibleWidget, that inherit from
QAccessibleInterfaceand 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
This enum type defines accessible event types.
The keyboard accelerator for an action has been changed.
An action has been changed.
A system alert (e.g., a message from a
Context help (
QWhatsThis) for an object is finished.
Context help (
QWhatsThis) for an object is initiated.
The default QAccessible::Action for the accessible object has changed.
A dialog (
QDialog) has been hidden
A dialog (
QDialog) has been set visible.
The contents of a text document have changed.
A document has been loaded.
A document load has been stopped.
A document reload has been initiated.
A drag and drop operation is about to finished.
A drag and drop operation is about to be initiated.
An object has gained keyboard focus.
A window has been activated (i.e., a new window has gained focus on the desktop).
Helptext property of an object has changed.
The end position of the display text for a hypertext link has changed.
The number of anchors in a hypertext link has changed, perhaps because the display text has been split to provide more than one link.
The link for the selected hypertext link has changed.
The start position of the display text for a hypertext link has changed.
The display text for a hypertext link has changed.
A hypertext link has been activated, perhaps by being clicked or via a key press.
A hypertext link has been selected.
An object’s location on the screen has changed.
A menu item is triggered.
A menu has been closed (Qt uses for all menus).
A menu has been opened on the menubar (Qt uses for all menus).
Nameproperty of an object has changed.
A new object is created.
An object is deleted.
An object is hidden; for example, with
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.
A layout or item view has added, removed, or moved an object (Qt does not use this event).
An object is displayed; for example, with
An object’s parent object changed.
A pop-up menu has closed.
A pop-up menu has opened.
A scrollbar scroll operation has ended (the mouse has released the slider handle).
A scrollbar scroll operation is about to start; this may be caused by a mouse press on the slider handle, for example.
An item has been added to the selection in an item view.
An item has been removed from an item view selection.
The selection has changed in a menu or item view.
Several changes to a selection has occurred in an item view.
A sound has been played by an object
A table caption has been changed.
The description of a table column, typically found in the column’s header, has been changed.
A table column header has been changed.
The description of a table row, typically found in the row’s header, has been changed.
A table row header has been changed.
The summary of a table has been changed.
A text column has been changed.
The values for this enum are defined to be the same as those defined in the IAccessible2 and MSAA specifications.
This enum defines the role of an accessible object. The roles are:
An object that is used to alert the user.
An object that displays an animation.
The application’s main window.
An object that provids interactive help.
An object that represents a border.
A button that drops down a list of items.
A button that drops down a grid.
A button that drops down a menu.
An object that displays graphics that the user can interact with.
An object that represents the system caret (text cursor).
A cell in a table.
An object that displays a graphical representation of data.
An object that represents an option that can be checked or unchecked. Some options provide a “mixed” state, e.g. neither checked nor unchecked.
The client area in a window.
A clock displaying time.
A dialog that lets the user choose a color.
A column of cells, usually within a table.
A header for a column of data.
A list of choices that the user can select from.
A part of the document or web page that is complementary to the main content, usually a landmark (see WAI-ARIA).
An object that represents the mouse cursor.
The object represents the desktop or workspace.
An object that represents a dial or knob.
A dialog box.
A document, for example in an office application.
Editable text such as a line or text edit.
An object that represents a mathematical equation.
A footer in a page (usually in documents).
A web form containing controls.
A graphic or picture, e.g. an icon.
A grip that the user can drag to change the size of widgets.
An object that represents a logical grouping of other objects.
A heading in a document.
An object that displays help in a separate, short lived window.
A hotkey field that allows the user to enter a key sequence.
An indicator that represents a current value or item.
An object that can contain layered children, e.g. in a stack.
A link to something else.
A list of items, from which the user can select one or more items.
An item in a list of items.
A menu bar from which menus are opened by the user.
An item in a menu or menu bar.
The object has no role. This usually indicates an invalid object.
A section whose content is parenthetic or ancillary to the main content of the resource.
An object that represents a notification (e.g. in the system tray). This role only has an effect on Linux.
A page tab that the user can select to switch to a different page in a dialog.
A list of page tabs.
A paragraph of text (usually found in documents).
A generic container.
A menu which lists options that the user can select to perform an action.
The object displays the progress of an operation in progress.
A property page where the user can change options and settings.
An object that represents an option that is mutually exclusive with other options.
A row of cells, usually within a table.
A header for a row of data.
A scroll bar, which allows the user to scroll the visible area.
A section (in a document).
A separator that divides space into logical areas.
A slider that allows the user to select a value within a given range.
An object that represents a sound.
A spin box widget that allows the user to enter a value within a given range.
A splitter distributing available space between its child widgets.
Static text, such as labels for other widgets.
A status bar.
A table representing data in a grid of rows and columns.
A terminal or command line interface.
The title bar caption of a window.
A tool bar, which groups widgets that the user accesses frequently.
A tool tip which provides information about other objects.
A list of items in a tree structure.
An item in a tree structure.
The first value to be used for user defined roles.
HTML document, usually in a browser.
Blank space between other objects.
A top level window.
This enum specifies string information that an accessible object returns.
The name of the object. This can be used both as an identifier or a short description by accessible clients.
A short text describing the object.
The value of the object.
A longer text giving information about how to use the object.
The keyboard shortcut that executes the object’s default action.
The first value to be used for user defined text.
This enum type defines bit flags that can be combined to indicate the relationship between two accessible objects.
The first object is the label of the second object.
The first object is labelled by the second object.
The first object controls the second object.
The first object is controlled by the second object.
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.
QAccessibleInterfacesupports several sub interfaces. In order to provide more information about some objects, their accessible representation should implement one or more of these interfaces.
When subclassing one of these interfaces,
interface_cast()needs to be implemented.
For text that supports selections or is more than one line. Simple labels do not need to implement this interface.
For objects that are used to manipulate a value, for example slider or scroll bar.
For interactive objects that allow the user to trigger an action. Basically everything that allows for example mouse interaction.
For lists, tables and trees.
For cells in a object.
This enum describes different types of text boundaries. It follows the IAccessible2 API and is used in the
Use individual characters as boundary.
Use words as boundaries.
Use sentences as boundary.
Use paragraphs as boundary.
Use newlines as boundary.
No boundary (use the whole text).
uniqueId – long
- Return type
QAccessibleInterfacebelonging to the
Noneif the id is invalid.
uniqueId – long
Removes the interface belonging to this
idfrom the cache and deletes it. The id becomes invalid an may be re-used by the cache.
- Return type
trueif 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
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.
getBoundaries is a helper function to find the accessible text boundaries for
QTextCursorbased documents. documentCursor a valid cursor bound to the document (not null). It needs to ba at the position to look for the boundary boundaryType the type of boundary to find Returns the boundaries as pair
- Return type
QAccessibleInterfaceimplementation exists for the given
object, this function returns a pointer to the implementation; otherwise it returns
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.
- Return type
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
child()function and returning the child after constructing it, this function needs to be called.
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
QApplicationobject as the root object immediately before the event loop is entered in
Use to redirect the function call to a customized handler function.
- Return type
Returns the unique ID for the
Notifies about a change that might be relevant for accessibility clients.
eventprovides details about the change. These include the source of the change and the nature of the change. The
eventshould contain enough information give meaningful notifications.
For example, the type
ValueChangeindicates 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
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
isActive()to avoid unnecessary computation.
© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.