class QAccessible

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

Synopsis

Static functions

• def accessibleInterface()

• def cleanup()

• def deleteAccessibleInterface()

• def installFactory()

• def isActive()

• def qAccessibleTextBoundaryHelper()

• def queryAccessibleInterface()

• def registerAccessibleInterface()

• def setActive()

• def setRootObject()

• def uniqueId()

• def updateAccessibility()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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

class Event

This enum type defines accessible event types.

Constant	Description
QAccessible.AcceleratorChanged	The keyboard accelerator for an action has been changed.
QAccessible.ActionChanged	An action has been changed.
QAccessible.ActiveDescendantChanged
QAccessible.Alert	A system alert (e.g., a message from a QMessageBox)
QAccessible.Announcement	The announcement of a message is requested.
QAccessible.AttributeChanged
QAccessible.ContextHelpEnd	Context help (QWhatsThis) for an object is finished.
QAccessible.ContextHelpStart	Context help (QWhatsThis) for an object is initiated.
QAccessible.DefaultActionChanged	The default QAccessible::Action for the accessible object has changed.
QAccessible.DescriptionChanged	The object’s Description changed.
QAccessible.DialogEnd	A dialog (QDialog) has been hidden
QAccessible.DialogStart	A dialog (QDialog) has been set visible.
QAccessible.DocumentContentChanged	The contents of a text document have changed.
QAccessible.DocumentLoadComplete	A document has been loaded.
QAccessible.DocumentLoadStopped	A document load has been stopped.
QAccessible.DocumentReload	A document reload has been initiated.
QAccessible.DragDropEnd	A drag and drop operation is about to finished.
QAccessible.DragDropStart	A drag and drop operation is about to be initiated.
QAccessible.Focus	An object has gained keyboard focus.
QAccessible.ForegroundChanged	A window has been activated (i.e., a new window has gained focus on the desktop).
QAccessible.HelpChanged	The Help text property of an object has changed.
QAccessible.HyperlinkEndIndexChanged	The end position of the display text for a hypertext link has changed.
QAccessible.HyperlinkNumberOfAnchorsChanged	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	The link for the selected hypertext link has changed.
QAccessible.HyperlinkStartIndexChanged	The start position of the display text for a hypertext link has changed.
QAccessible.HypertextChanged	The display text for a hypertext link has changed.
QAccessible.HypertextLinkActivated	A hypertext link has been activated, perhaps by being clicked or via a key press.
QAccessible.HypertextLinkSelected	A hypertext link has been selected.
QAccessible.HypertextNLinksChanged
QAccessible.IdentifierChanged	The identifier of an object has changed.
QAccessible.LocationChanged	An object’s location on the screen has changed.
QAccessible.MenuCommand	A menu item is triggered.
QAccessible.MenuEnd	A menu has been closed (Qt uses PopupMenuEnd for all menus).
QAccessible.MenuStart	A menu has been opened on the menubar (Qt uses PopupMenuStart for all menus).
QAccessible.NameChanged	The Name property of an object has changed.
QAccessible.ObjectAttributeChanged
QAccessible.ObjectCreated	A new object is created.
QAccessible.ObjectDestroyed	An object is deleted.
QAccessible.ObjectHide	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 obscured by others.
QAccessible.ObjectReorder	A layout or item view has added, removed, or moved an object (Qt does not use this event).
QAccessible.ObjectShow	An object is displayed; for example, with QWidget::show().
QAccessible.PageChanged
QAccessible.ParentChanged	An object’s parent object changed.
QAccessible.PopupMenuEnd	A pop-up menu has closed.
QAccessible.PopupMenuStart	A pop-up menu has opened.
QAccessible.ScrollingEnd	A scrollbar scroll operation has ended (the mouse has released the slider handle).
QAccessible.ScrollingStart	A scrollbar scroll operation is about to start; this may be caused by a mouse press on the slider handle, for example.
QAccessible.SectionChanged
QAccessible.SelectionAdd	An item has been added to the selection in an item view.
QAccessible.SelectionRemove	An item has been removed from an item view selection.
QAccessible.Selection	The selection has changed in a menu or item view.
QAccessible.SelectionWithin	Several changes to a selection has occurred in an item view.
QAccessible.SoundPlayed	A sound has been played by an object
QAccessible.TableCaptionChanged	A table caption has been changed.
QAccessible.TableColumnDescriptionChanged	The description of a table column, typically found in the column’s header, has been changed.
QAccessible.TableColumnHeaderChanged	A table column header has been changed.
QAccessible.TableRowDescriptionChanged	The description of a table row, typically found in the row’s header, has been changed.
QAccessible.TableRowHeaderChanged	A table row header has been changed.
QAccessible.TableSummaryChanged	The summary of a table has been changed.
QAccessible.TextColumnChanged	A text column has been changed.
QAccessible.VisibleDataChanged

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

class Role

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

Constant	Description
QAccessible.AlertMessage	An object that is used to alert the user.
QAccessible.Animation	An object that displays an animation.
QAccessible.Application	The application’s main window.
QAccessible.Assistant	An object that provides interactive help.
QAccessible.Border	An object that represents a border.
QAccessible.ButtonDropDown	A button that drops down a list of items.
QAccessible.ButtonDropGrid	A button that drops down a grid.
QAccessible.ButtonMenu	A button that drops down a menu.
QAccessible.Canvas	An object that displays graphics that the user can interact with.
QAccessible.Caret	An object that represents the system caret (text cursor).
QAccessible.Cell	A cell in a table.
QAccessible.Chart	An object that displays a graphical representation of data.
QAccessible.CheckBox	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	The client area in a window.
QAccessible.Clock	A clock displaying time.
QAccessible.ColorChooser	A dialog that lets the user choose a color.
QAccessible.Column	A column of cells, usually within a table.
QAccessible.ColumnHeader	A header for a column of data.
QAccessible.ComboBox	A list of choices that the user can select from.
QAccessible.ComplementaryContent	A part of the document or web page that is complementary to the main content, usually a landmark (see WAI-ARIA).
QAccessible.Cursor	An object that represents the mouse cursor.
QAccessible.Desktop	The object represents the desktop or workspace.
QAccessible.Dial	An object that represents a dial or knob.
QAccessible.Dialog	A dialog box.
QAccessible.Document	A document, for example in an office application.
QAccessible.EditableText	Editable text such as a line or text edit.
QAccessible.Equation	An object that represents a mathematical equation.
QAccessible.Footer	A footer in a page (usually in documents).
QAccessible.Form	A web form containing controls.
QAccessible.Graphic	A graphic or picture, e.g. an icon.
QAccessible.Grip	A grip that the user can drag to change the size of widgets.
QAccessible.Grouping	An object that represents a logical grouping of other objects.
QAccessible.Heading	A heading in a document.
QAccessible.HelpBalloon	An object that displays help in a separate, short lived window.
QAccessible.HotkeyField	A hotkey field that allows the user to enter a key sequence.
QAccessible.Indicator	An indicator that represents a current value or item.
QAccessible.LayeredPane	An object that can contain layered children, e.g. in a stack.
QAccessible.Link	A link to something else.
QAccessible.List	A list of items, from which the user can select one or more items.
QAccessible.ListItem	An item in a list of items.
QAccessible.MenuBar	A menu bar from which menus are opened by the user.
QAccessible.MenuItem	An item in a menu or menu bar.
QAccessible.NoRole	The object has no role. This usually indicates an invalid object.
QAccessible.Note	A section whose content is parenthetic or ancillary to the main content of the resource.
QAccessible.Notification	An object that represents a notification (e.g. in the system tray). This role only has an effect on Linux.
QAccessible.PageTab	A page tab that the user can select to switch to a different page in a dialog.
QAccessible.PageTabList	A list of page tabs.
QAccessible.Paragraph	A paragraph of text (usually found in documents).
QAccessible.Pane	A generic container.
QAccessible.PopupMenu	A menu which lists options that the user can select to perform an action.
QAccessible.ProgressBar	The object displays the progress of an operation in progress.
QAccessible.PropertyPage	A property page where the user can change options and settings.
QAccessible.Button	A button.
QAccessible.RadioButton	An object that represents an option that is mutually exclusive with other options.
QAccessible.Row	A row of cells, usually within a table.
QAccessible.RowHeader	A header for a row of data.
QAccessible.ScrollBar	A scroll bar, which allows the user to scroll the visible area.
QAccessible.Section	A section (in a document).
QAccessible.Separator	A separator that divides space into logical areas.
QAccessible.Slider	A slider that allows the user to select a value within a given range.
QAccessible.Sound	An object that represents a sound.
QAccessible.SpinBox	A spin box widget that allows the user to enter a value within a given range.
QAccessible.Splitter	A splitter distributing available space between its child widgets.
QAccessible.StaticText	Static text, such as labels for other widgets.
QAccessible.StatusBar	A status bar.
QAccessible.Table	A table representing data in a grid of rows and columns.
QAccessible.Terminal	A terminal or command line interface.
QAccessible.TitleBar	The title bar caption of a window.
QAccessible.ToolBar	A tool bar, which groups widgets that the user accesses frequently.
QAccessible.ToolTip	A tool tip which provides information about other objects.
QAccessible.Tree	A list of items in a tree structure.
QAccessible.TreeItem	An item in a tree structure.
QAccessible.UserRole	The first value to be used for user defined roles.
QAccessible.WebDocument	HTML document, usually in a browser.
QAccessible.Whitespace	Blank space between other objects.
QAccessible.Window	A top level window.

class Text

This enum specifies string information that an accessible object returns.

Constant	Description
QAccessible.Name	The name of the object. This can be used both as an identifier or a short description by accessible clients.
QAccessible.Description	A short text describing the object.
QAccessible.Value	The value of the object.
QAccessible.Help	A longer text giving information about how to use the object.
QAccessible.Accelerator	The keyboard shortcut that executes the object’s default action.
QAccessible.UserText	The first value to be used for user defined text.
QAccessible.Identifier	An identifier for the object for e.g. UI tests.

class RelationFlag

(inherits enum.Flag) This enum type defines bit flags that can be combined to indicate the relationship between two accessible objects. It is used by the relations() function, which returns a list of all the related interfaces of the calling object, together with the relations for each object.

Each entry in the list is a QPair where the second member stores the relation type(s) between the returned object represented by the first member and the origin (the caller) interface/object.

In the table below, the returned object refers to the object in the returned list, and the origin object is the one represented by the calling interface.

Constant	Description
QAccessible.Label	The returned object is the label for the origin object.
QAccessible.Labelled	The returned object is labelled by the origin object.
QAccessible.Controller	The returned object controls the origin object.
QAccessible.Controlled	The returned object is controlled by the origin object.
QAccessible.DescriptionFor	The returned object provides a description for the origin object.
QAccessible.Described	The returned object is described by the origin object.
QAccessible.FlowsFrom	Content logically flows from the returned object to the origin object.
QAccessible.FlowsTo	Content logically flows to the returned object from the origin object.
QAccessible.AllRelations	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.

class 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.

Note

When subclassing one of these interfaces, interface_cast() needs to be implemented.

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

See also

interface_cast() QAccessibleTextInterface QAccessibleValueInterface QAccessibleActionInterface QAccessibleTableInterface QAccessibleTableCellInterface QAccessibleSelectionInterface QAccessibleAttributesInterface

class TextBoundaryType

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

Constant	Description
QAccessible.CharBoundary	Use individual characters as boundary.
QAccessible.WordBoundary	Use words as boundaries.
QAccessible.SentenceBoundary	Use sentences as boundary.
QAccessible.ParagraphBoundary	Use paragraphs as boundary.
QAccessible.LineBoundary	Use newlines as boundary.
QAccessible.NoBoundary	No boundary (use the whole text).

See also

QAccessibleTextInterface

class Attribute

This enum describes different types of attributes used by the QAccessibleAttributesInterface .

These attributes are comparable to the concept of properties/(object) attributes found in ARIA, AT-SPI2, IAccessible, UIA and NSAccessibility and are mapped to their platform counterpart where applicable.

Each attribute is handled as a key-value pair, with the values of this enumeration being used as keys.

Attribute values are represented in a QVariant. The type of the value stored in the QVariant is fixed and specified below for each of the attribute types.

Constant	Description
QAccessible.Attribute.Custom	value type: QHash<QString, QString> The Custom attribute is special in that it can effectively represent multiple attributes at once, since it itself is a QHash used to represent key-value pairs. For platforms supporting custom key-value pairs for attributes, those set in the Custom attribute are bridged to the platform layer without applying any translation to platform-specific attributes. In general, the other, more strongly typed attributes should be used. This attribute can e.g. be used for prototyping before officially adding an official new enumeration value for a specific feature.
QAccessible.Attribute.Level	value type: int Defines the hierarchical level of an element within a structure, e.g. the heading level of a heading. This attribute conceptually matches the “aria-level” property in ARIA.

See also

QAccessibleAttributesInterface

Added in version 6.8.

class AnnouncementPoliteness

This enum describes the priority for announcements used by the QAccessibleAnnouncementEvent .

With QAccessible::AnouncementPoliteness::Polite, assistive technologies should announce the message at the next graceful opportunity such as at the end of speaking the current sentence or when the user pauses typing.

When specifying QAccessible::AnouncementPoliteness::Assertive, assistive technologies should notify the user immediately.

Because an interruption might disorient users or cause them to not complete their current task, QAccessible::AnouncementPoliteness::Assertive should not be used unless the interruption is imperative.

Constant	Description
QAccessible.AnnouncementPoliteness.Polite	The announcement has normal priority.
QAccessible.AnnouncementPoliteness.Assertive	The announcement has high priority and should notify the user immediately, even if that means interrupting the user’s current task.

See also

QAccessibleAnnouncementEvent

Added in version 6.8.

static accessibleInterface(uniqueId)

Parameters:

uniqueId – int

Return type:

QAccessibleInterface

Returns the QAccessibleInterface belonging to the id.

Returns None if the id is invalid.

static cleanup()

static deleteAccessibleInterface(uniqueId)

Parameters:

uniqueId – int

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 installFactory(arg__1)

Parameters:

arg__1 – PyCallable

static isActive()

Return type:

bool

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 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 qAccessibleTextBoundaryHelper(cursor, boundaryType)

Parameters:

• cursor – QTextCursor

• boundaryType – TextBoundaryType

Return type:

.std.pairint,int

static queryAccessibleInterface(arg__1)

Parameters:

arg__1 – QObject

Return type:

QAccessibleInterface

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

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 registerAccessibleInterface(iface)

Parameters:

iface – QAccessibleInterface

Return type:

int

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.

static setActive(active)

Parameters:

active – bool

static setRootObject(object)

Parameters:

object – QObject

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 uniqueId(iface)

Parameters:

iface – QAccessibleInterface

Return type:

int

Returns the unique ID for the QAccessibleInterface iface.

static updateAccessibility(event)

Parameters:

event – QAccessibleEvent

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 isActive() to avoid unnecessary computation.