QAccessible Class

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

Header: #include <QAccessible>
Inherited By:

QAccessibleInterface and QAccessiblePlugin

Public Types

enum Action { DefaultAction, Press, SetFocus, Increase, ..., LastStandardAction }
enum Event { AcceleratorChanged, ActionChanged, ActiveDescendantChanged, Alert, ..., VisibleDataChanged }
typedef InterfaceFactory
enum Method { ListSupportedMethods, SetCursorPosition, GetCursorPosition }
flags Relation
enum RelationFlag { Unrelated, Self, Ancestor, Child, ..., Controlled }
enum Role { AlertMessage, Animation, Application, Assistant, ..., Window }
flags State
enum StateFlag { Animated, Busy, Checked, Collapsed, ..., Unavailable }
enum Text { Name, Description, Value, Help, Accelerator, UserText }

Static Public Members

void installFactory(InterfaceFactory factory)
RootObjectHandler installRootObjectHandler(RootObjectHandler handler)
bool isActive()
QAccessibleInterface * queryAccessibleInterface(QObject * object)
void removeFactory(InterfaceFactory factory)
void setRootObject(QObject * object)
void updateAccessibility(QObject * object, int child, Event reason)

Detailed Description

The QAccessible class provides enums and static functions relating to accessibility.

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), Mac OS X Accessibility, and the Unix/X11 AT-SPI standard. Other backends can be supported using QAccessibleBridge.

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::Action

This enum describes the possible types of action that can occur.

ConstantValue
QAccessible::DefaultAction0
QAccessible::Press-1
QAccessible::SetFocus-2
QAccessible::Increase-3
QAccessible::Decrease-4
QAccessible::Accept-5
QAccessible::Cancel-6
QAccessible::Select-7
QAccessible::ClearSelection-8
QAccessible::RemoveSelection-9
QAccessible::ExtendSelection-10
QAccessible::AddToSelection-11
QAccessible::FirstStandardActionPress
QAccessible::LastStandardActionAddToSelection

enum QAccessible::Event

This enum type defines accessible event types.

ConstantValueDescription
QAccessible::AcceleratorChanged0x80C0The keyboard accelerator for an action has been changed.
QAccessible::ActionChanged0x0101An action has been changed.
QAccessible::ActiveDescendantChanged0x0102 
QAccessible::Alert0x0002A system alert (e.g., a message from a QMessageBox)
QAccessible::AttributeChanged0x0103 
QAccessible::ContextHelpEnd0x000DContext help (QWhatsThis) for an object is finished.
QAccessible::ContextHelpStart0x000CContext help (QWhatsThis) for an object is initiated.
QAccessible::DefaultActionChanged0x80B0The default QAccessible::Action for the accessible object has changed.
QAccessible::DescriptionChanged0x800DThe object's QAccessible::Description changed.
QAccessible::DialogEnd0x0011A dialog (QDialog) has been hidden
QAccessible::DialogStart0x0010A dialog (QDialog) has been set visible.
QAccessible::DocumentContentChanged0x0104The contents of a text document have changed.
QAccessible::DocumentLoadComplete0x0105A document has been loaded.
QAccessible::DocumentLoadStopped0x0106A document load has been stopped.
QAccessible::DocumentReload0x0107A document reload has been initiated.
QAccessible::DragDropEnd0x000FA drag and drop operation is about to finished.
QAccessible::DragDropStart0x000EA drag and drop operation is about to be initiated.
QAccessible::Focus0x8005An object has gained keyboard focus.
QAccessible::ForegroundChanged0x0003A window has been activated (i.e., a new window has gained focus on the desktop).
QAccessible::HelpChanged0x80A0The QAccessible::Help text property of an object has changed.
QAccessible::HyperlinkEndIndexChanged0x0108The end position of the display text for a hypertext link has changed.
QAccessible::HyperlinkNumberOfAnchorsChanged0x0109The number of anchors in a hypertext link has changed, perhaps because the display text has been split to provide more than one link.
QAccessible::HyperlinkSelectedLinkChanged0x010AThe link for the selected hypertext link has changed.
QAccessible::HyperlinkStartIndexChanged0x010DThe start position of the display text for a hypertext link has changed.
QAccessible::HypertextChanged0x010EThe display text for a hypertext link has changed.
QAccessible::HypertextLinkActivated0x010BA hypertext link has been activated, perhaps by being clicked or via a key press.
QAccessible::HypertextLinkSelected0x010CA hypertext link has been selected.
QAccessible::HypertextNLinksChanged0x010F 
QAccessible::LocationChanged0x800BAn object's location on the screen has changed.
QAccessible::MenuCommand0x0018A menu item is triggered.
QAccessible::MenuEnd0x0005A menu has been closed (Qt uses PopupMenuEnd for all menus).
QAccessible::MenuStart0x0004A menu has been opened on the menubar (Qt uses PopupMenuStart for all menus).
QAccessible::NameChanged0x800CThe QAccessible::Name property of an object has changed.
QAccessible::ObjectAttributeChanged0x0110 
QAccessible::ObjectCreated0x8000A new object is created.
QAccessible::ObjectDestroyed0x8001An object is deleted.
QAccessible::ObjectHide0x8003An 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::ObjectReorder0x8004A layout or item view has added, removed, or moved an object (Qt does not use this event).
QAccessible::ObjectShow0x8002An object is displayed; for example, with QWidget::show().
QAccessible::PageChanged0x0111 
QAccessible::ParentChanged0x800FAn object's parent object changed.
QAccessible::PopupMenuEnd0x0007A pop-up menu has closed.
QAccessible::PopupMenuStart0x0006A pop-up menu has opened.
QAccessible::ScrollingEnd0x0013A scrollbar scroll operation has ended (the mouse has released the slider handle).
QAccessible::ScrollingStart0x0012A scrollbar scroll operation is about to start; this may be caused by a mouse press on the slider handle, for example.
QAccessible::SectionChanged0x0112 
QAccessible::SelectionAdd0x8007An item has been added to the selection in an item view.
QAccessible::SelectionRemove0x8008An item has been removed from an item view selection.
QAccessible::Selection0x8006The selection has changed in a menu or item view.
QAccessible::SelectionWithin0x8009Several changes to a selection has occurred in an item view.
QAccessible::SoundPlayed0x0001A sound has been played by an object
QAccessible::StateChanged0x800AThe QAccessible::State of an object has changed.
QAccessible::TableCaptionChanged0x0113A table caption has been changed.
QAccessible::TableColumnDescriptionChanged0x0114The description of a table column, typically found in the column's header, has been changed.
QAccessible::TableColumnHeaderChanged0x0115A table column header has been changed.
QAccessible::TableModelChanged0x0116The model providing data for a table has been changed.
QAccessible::TableRowDescriptionChanged0x0117The description of a table row, typically found in the row's header, has been changed.
QAccessible::TableRowHeaderChanged0x0118A table row header has been changed.
QAccessible::TableSummaryChanged0x0119The summary of a table has been changed.
QAccessible::TextAttributeChanged0x011A 
QAccessible::TextCaretMoved0x011BThe caret has moved in an editable widget. The caret represents the cursor position in an editable widget with the input focus.
QAccessible::TextColumnChanged0x011DA text column has been changed.
QAccessible::TextInserted0x011EText has been inserted into an editable widget.
QAccessible::TextRemoved0x011FText has been removed from an editable widget.
QAccessible::TextSelectionChanged0x0121The selected text has changed in an editable widget.
QAccessible::TextUpdated0x0120The text has been update in an editable widget.
QAccessible::ValueChanged0x800EThe QAccessible::Value of an object has changed.
QAccessible::VisibleDataChanged0x0122 

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

typedef 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, a null-pointer will be returned.

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

enum QAccessible::Method

This enum describes the possible types of methods that can be invoked on an accessible object.

ConstantValue
QAccessible::ListSupportedMethods0
QAccessible::SetCursorPosition1
QAccessible::GetCursorPosition2

See also QAccessibleInterface::invokeMethod().

enum QAccessible::RelationFlag
flags QAccessible::Relation

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

ConstantValueDescription
QAccessible::Unrelated0x00000000The objects are unrelated.
QAccessible::Self0x00000001The objects are the same.
QAccessible::Ancestor0x00000002The first object is a parent of the second object.
QAccessible::Child0x00000004The first object is a direct child of the second object.
QAccessible::Descendent0x00000008The first object is an indirect child of the second object.
QAccessible::Sibling0x00000010The objects are siblings.
QAccessible::Up0x00000100The first object is above the second object.
QAccessible::Down0x00000200The first object is below the second object.
QAccessible::Left0x00000400The first object is left of the second object.
QAccessible::Right0x00000800The first object is right of the second object.
QAccessible::Covers0x00001000The first object covers the second object.
QAccessible::Covered0x00002000The first object is covered by the second object.
QAccessible::FocusChild0x00010000The first object is the second object's focus child.
QAccessible::Label0x00020000The first object is the label of the second object.
QAccessible::Labelled0x00040000The first object is labelled by the second object.
QAccessible::Controller0x00080000The first object controls the second object.
QAccessible::Controlled0x00100000The first object is controlled by the second object.

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

Implementations of navigate() can accept only one distinct value.

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:

ConstantValueDescription
QAccessible::AlertMessage0x00000008An object that is used to alert the user.
QAccessible::Animation0x00000036An object that displays an animation.
QAccessible::Application0x0000000EThe application's main window.
QAccessible::Assistant0x00000020An object that provids interactive help.
QAccessible::Border0x00000013An object that represents a border.
QAccessible::ButtonDropDown0x00000038A button that drops down a list of items.
QAccessible::ButtonDropGrid0x0000003AA button that drops down a grid.
QAccessible::ButtonMenu0x00000039A button that drops down a menu.
QAccessible::Canvas0x00000035An object that displays graphics that the user can interact with.
QAccessible::Caret0x00000007An object that represents the system caret (text cursor).
QAccessible::Cell0x0000001DA cell in a table.
QAccessible::Chart0x00000011An object that displays a graphical representation of data.
QAccessible::CheckBox0x0000002CAn object that represents an option that can be checked or unchecked. Some options provide a "mixed" state, e.g. neither checked nor unchecked.
QAccessible::Client0x0000000AThe client area in a window.
QAccessible::Clock0x0000003DA clock displaying time.
QAccessible::Column0x0000001BA column of cells, usually within a table.
QAccessible::ColumnHeader0x00000019A header for a column of data.
QAccessible::ComboBox0x0000002EA list of choices that the user can select from.
QAccessible::Cursor0x00000006An object that represents the mouse cursor.
QAccessible::Desktop0x00000041The object represents the desktop or workspace.
QAccessible::Dial0x00000031An object that represents a dial or knob.
QAccessible::Dialog0x00000012A dialog box.
QAccessible::Document0x0000000FA document window, usually in an MDI environment.
QAccessible::EditableText0x0000002AEditable text
QAccessible::Equation0x00000037An object that represents a mathematical equation.
QAccessible::Graphic0x00000028A graphic or picture, e.g. an icon.
QAccessible::Grip0x00000004A grip that the user can drag to change the size of widgets.
QAccessible::Grouping0x00000014An object that represents a logical grouping of other objects.
QAccessible::HelpBalloon0x0000001FAn object that displays help in a separate, short lived window.
QAccessible::HotkeyField0x00000032A hotkey field that allows the user to enter a key sequence.
QAccessible::Indicator0x00000027An indicator that represents a current value or item.
QAccessible::LayeredPane0x0000003FAn object that can contain layered children, e.g. in a stack.
QAccessible::Link0x0000001EA link to something else.
QAccessible::List0x00000021A list of items, from which the user can select one or more items.
QAccessible::ListItem0x00000022An item in a list of items.
QAccessible::MenuBar0x00000002A menu bar from which menus are opened by the user.
QAccessible::MenuItem0x0000000CAn item in a menu or menu bar.
QAccessible::NoRole0x00000000The object has no role. This usually indicates an invalid object.
QAccessible::PageTab0x00000025A page tab that the user can select to switch to a different page in a dialog.
QAccessible::PageTabList0x0000003CA list of page tabs.
QAccessible::Pane0x00000010A generic container.
QAccessible::PopupMenu0x0000000BA menu which lists options that the user can select to perform an action.
QAccessible::ProgressBar0x00000030The object displays the progress of an operation in progress.
QAccessible::PropertyPage0x00000026A property page where the user can change options and settings.
QAccessible::PushButton0x0000002BA button.
QAccessible::RadioButton0x0000002DAn object that represents an option that is mutually exclusive with other options.
QAccessible::Row0x0000001CA row of cells, usually within a table.
QAccessible::RowHeader0x0000001AA header for a row of data.
QAccessible::ScrollBar0x00000003A scroll bar, which allows the user to scroll the visible area.
QAccessible::Separator0x00000015A separator that divides space into logical areas.
QAccessible::Slider0x00000033A slider that allows the user to select a value within a given range.
QAccessible::Sound0x00000005An object that represents a sound.
QAccessible::SpinBox0x00000034A spin box widget that allows the user to enter a value within a given range.
QAccessible::Splitter0x0000003EA splitter distributing available space between its child widgets.
QAccessible::StaticText0x00000029Static text, such as labels for other widgets.
QAccessible::StatusBar0x00000017A status bar.
QAccessible::Table0x00000018A table representing data in a grid of rows and columns.
QAccessible::Terminal0x00000040A terminal or command line interface.
QAccessible::TitleBar0x00000001The title bar caption of a window.
QAccessible::ToolBar0x00000016A tool bar, which groups widgets that the user accesses frequently.
QAccessible::ToolTip0x0000000DA tool tip which provides information about other objects.
QAccessible::Tree0x00000023A list of items in a tree structure.
QAccessible::TreeItem0x00000024An item in a tree structure.
QAccessible::UserRole0x0000ffffThe first value to be used for user defined roles.
QAccessible::Whitespace0x0000003BBlank space between other objects.
QAccessible::Window0x00000009A top level window.

enum QAccessible::StateFlag
flags QAccessible::State

This enum type defines bit flags that can be combined to indicate the state of an accessible object. The values are:

ConstantValueDescription
QAccessible::Animated0x00004000The object's appearance changes frequently.
QAccessible::Busy0x00000800The object cannot accept input at the moment.
QAccessible::Checked0x00000010The object's check box is checked.
QAccessible::Collapsed0x00000400The object is collapsed, e.g. a closed listview item, or an iconified window.
QAccessible::DefaultButton0x00000100The object represents the default button in a dialog.
QAccessible::Expanded0x00000200The object is expandable, and currently the children are visible.
QAccessible::ExtSelectable0x02000000The object supports extended selection.
QAccessible::Focusable0x00100000The object can receive focus. Only objects in the active window can receive focus.
QAccessible::Focused0x00000004The object has keyboard focus.
QAccessible::HasPopup0x40000000The object opens a popup.
QAccessible::HotTracked0x00000080The object's appearance is sensitive to the mouse cursor position.
QAccessible::Invisible0x00008000The object is not visible to the user.
QAccessible::Linked0x00400000The object is linked to another object, e.g. a hyperlink.
QAccessible::Marqueed0x00002000The object displays scrolling contents, e.g. a log view.
QAccessible::Mixed0x00000020The state of the object is not determined, e.g. a tri-state check box that is neither checked nor unchecked.
QAccessible::Modal0x80000000The object blocks input from other objects.
QAccessible::Movable0x00040000The object can be moved.
QAccessible::MultiSelectable0x01000000The object supports multiple selected items.
QAccessible::Normal0x00000000The normal state.
QAccessible::Offscreen0x00010000The object is clipped by the visible area. Objects that are off screen are also invisible.
QAccessible::Pressed0x00000008The object is pressed.
QAccessible::Protected0x20000000The object is password protected, e.g. a line edit for entering a Password.
QAccessible::ReadOnly0x00000040The object can usually be edited, but is explicitly set to read-only.
QAccessible::Selectable0x00200000The object is selectable.
QAccessible::Selected0x00000002The object is selected.
QAccessible::SelfVoicing0x00080000The object describes itself through speech or sound.
QAccessible::Sizeable0x00020000The object can be resized, e.g. top-level windows.
QAccessible::Traversed0x00800000The object is linked and has been visited.
QAccessible::Unavailable0x00000001The object is unavailable to the user, e.g. a disabled widget.

Implementations of QAccessibleInterface::state() return a combination of these flags.

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

enum QAccessible::Text

This enum specifies string information that an accessible object returns.

ConstantValueDescription
QAccessible::Name0The name of the object. This can be used both as an identifier or a short description by accessible clients.
QAccessible::Description1A short text describing the object.
QAccessible::Value2The value of the object.
QAccessible::Help3A longer text giving information about how to use the object.
QAccessible::Accelerator4The keyboard shortcut that executes the object's default action.
QAccessible::UserText0x0000ffffThe first value to be used for user defined text.

Member Function Documentation

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

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

[static] RootObjectHandler QAccessible::installRootObjectHandler(RootObjectHandler handler)

Installs the given handler as the function to be used by setRootObject(), and returns the previously installed handler.

[static] bool QAccessible::isActive()

Returns true if an accessibility implementation has been requested during the runtime of the application; otherwise returns false.

Use this function to prevent potentially expensive notifications via updateAccessibility().

[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 0.

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.

Warning: The caller is responsible for deleting the returned interface after use.

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

Removes factory from the list of installed InterfaceFactories.

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

Sets the root accessible object of this application to object. All other accessible objects in the application can be reached by the client using object navigation.

You should never need to call this function. 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] void QAccessible::updateAccessibility(QObject * object, int child, Event reason)

Notifies accessibility clients about a change in object's accessibility information.

reason specifies the cause of the change, for example, ValueChange when the position of a slider has been changed. child is the (1-based) index of the child element that has changed. When child is 0, the object itself has 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 computations.

© 2016 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.