CopperSpice API  1.8.2
QAccessible Class Reference

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


class  State
 Structure which defines bit flags that indicate the state of an accessible object More...

Public Typedefs

using Id = unsigned
using InterfaceFactory = QAccessibleInterface *(*)(const QString &key, QObject *)
using Relation = QFlags< RelationFlag >

Public Types

enum  Event
enum  InterfaceType
enum  RelationFlag
enum  Role
enum  Text
enum  TextBoundaryType

Static Public Methods

static QAccessibleInterfaceaccessibleInterface (Id uniqueId)
static void deleteAccessibleInterface (Id uniqueId)
static void installFactory (InterfaceFactory factory)
static RootObjectHandler installRootObjectHandler (RootObjectHandler handler)
static bool isActive ()
static QAccessibleInterfacequeryAccessibleInterface (QObject *object)
static Id registerAccessibleInterface (QAccessibleInterface *interfaceId)
static void removeFactory (InterfaceFactory factory)
static void setRootObject (QObject *object)
static Id uniqueId (QAccessibleInterface *interfaceId)
static void updateAccessibility (QAccessibleEvent *event)

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

CopperSpice 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, CopperSpice 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. CopperSpice 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, the CopperSpice predefined accessibility support can be built as plugin (the default) or directly into the CopperSpice library. The main advantage of using plugins is that the accessibility classes are only loaded into memory if they are actually used; they do not slow down the common case where no assistive technology is being used.

CopperSpice 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

Member Typedef Documentation

This is a typedef for unsigned, used by the QAccessibleInterface cache.

This is a typedef for a pointer to a method with the following signature.

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

The call back function receives a QString and a QObject pointer, where the QString is the key identifying the interface. The QObject is passed to the QAccessibleInterface. If the key and the QObject do not have a corresponding QAccessibleInterface a null pointer will be returned.

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

Member Enumeration Documentation

This enum type defines accessible event types.

QAccessible::AcceleratorChanged0x80C0The keyboard accelerator for an action has been changed.
QAccessible::ActionChanged0x0101An action has been changed.
QAccessible::Alert0x0002A system alert (e.g., a message from a QMessageBox)
QAccessible::ContextHelpEnd0x000DContext help (QWhatsThis) for an object is finished.
QAccessible::ContextHelpStart0x000CContext help (QWhatsThis) for an object is initiated.
QAccessible::DefaultActionChanged0x80B0 The 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::DragDropStart0x000E A drag and drop operation is about to be initiated.
QAccessible::Focus0x8005 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 0x0108The 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::HyperlinkSelectedLinkChanged0x010A The link for the selected hypertext link has changed.
QAccessible::HyperlinkStartIndexChanged0x010D The start position of the display text for a hypertext link has changed.
QAccessible::HypertextChanged0x010E The display text for a hypertext link has changed.
QAccessible::HypertextLinkActivated0x010B A hypertext link has been activated, perhaps by being clicked or via a key press.
QAccessible::HypertextLinkSelected0x010CA hypertext link has been selected.
QAccessible::LocationChanged0x800BAn object's location on the screen has changed.
QAccessible::MenuCommand0x0018A menu item is triggered.
QAccessible::MenuEnd0x0005A menu has been closed (CopperSpice uses PopupMenuEnd for all menus).
QAccessible::MenuStart 0x0004 A menu has been opened on the menubar (CopperSpice uses PopupMenuStart for all menus).
QAccessible::NameChanged0x800CThe QAccessible::Name property of an object has changed.
QAccessible::ObjectCreated0x8000A new object is created.
QAccessible::ObjectDestroyed0x8001An object is deleted.
QAccessible::ObjectHide 0x8003 An object is hidden, for example with QWidget::hide().
QAccessible::ObjectReorder0x8004 A layout or item view has added, removed, or moved an object (CopperSpice does not use this event).
QAccessible::ObjectShow0x8002 An object is displayed; for example, with QWidget::show().
QAccessible::ParentChanged0x800FAn object's parent object changed.
QAccessible::PopupMenuEnd0x0007 A pop-up menu has closed.
QAccessible::PopupMenuStart0x0006A pop-up menu has opened.
QAccessible::ScrollingEnd0x0013 A scrollbar scroll operation has ended (the mouse has released the slider handle).
QAccessible::ScrollingStart0x0012 A scrollbar scroll operation is about to start; this may be caused by a mouse press on the slider handle, for example.
QAccessible::SelectionAdd0x8007An item has been added to the selection in an item view.
QAccessible::SelectionRemove0x8008 An item has been removed from an item view selection.
QAccessible::Selection0x8006 The selection has changed in a menu or item view.
QAccessible::SelectionWithin0x8009 Several 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::TableColumnDescriptionChanged 0x0114 The description of a table column, typically found in the column's header, has been changed.
QAccessible::TableColumnHeaderChanged0x0115 A table column header has been changed.
QAccessible::TableModelChanged0x0116 The model providing data for a table has been changed.
QAccessible::TableRowDescriptionChanged 0x0117 The description of a table row, typically found in the row's header, has been changed.
QAccessible::TableRowHeaderChanged0x0118 A table row header has been changed.
QAccessible::TableSummaryChanged0x0119The summary of a table has been changed.
QAccessible::TextCaretMoved0x011B The caret has moved in an editable widget. The caret represents the cursor position in an editable widget with the input focus.
QAccessible::TextColumnChanged0x011DText column has been changed.
QAccessible::TextInserted0x011E Text has been inserted into an editable widget.
QAccessible::TextRemoved0x011F Text has been removed from an editable widget.
QAccessible::TextSelectionChanged0x0121 The selected text has changed in an editable widget.
QAccessible::TextUpdated0x0120 Text has been update in an editable widget.
QAccessible::ValueChanged0x800E QAccessible::Value of an object has changed.
QAccessible::VisibleDataChanged 0x0122  

The values for this enum are defined to be the same as those defined in the "AccessibleEventID.idl File Reference" (IAccessible2) and "Microsoft Active Accessibility Event Constants" (MSAA) specifications.

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. When subclassing one of these interfaces, QAccessibleInterface::interface_cast() needs to be implemented.

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. For text that can be edited by the user.
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. For objects that represent an image. This interface is generally less important.
QAccessible::TableInterface 5 For lists, tables and trees.
QAccessible::TableCellInterface 6 For cells in a TableInterface object.
See also
QAccessibleInterface::interface_cast(), QAccessibleTextInterface, QAccessibleValueInterface, QAccessibleActionInterface, QAccessibleTableInterface, QAccessibleTableCellInterface.

This enum defines the relationships between objects on the screen.

ConstantValue Description
QAccessible::Label 0x00000001 First object is the label for the second object
QAccessible::Labelled 0x00000002 Second object is the label for the first object
QAccessible::Controller 0x00000004 First object controls the second object
QAccessible::Controlled 0x00000008 Second object controls the first object
QAccessible::AllRelations 0xffffffff Used as a mask to query for information about all relations

This enum defines the role of an accessible object.

QAccessible::AlertMessage0x00000008 An object that is used to alert the user.
QAccessible::Animation0x00000036 An object that displays an animation.
QAccessible::Application0x0000000E The application's main window.
QAccessible::Assistant0x00000020 An object that provides interactive help.
QAccessible::Border0x00000013 An object that represents a border.
QAccessible::ButtonDropDown0x00000038 A button that drops down a list of items.
QAccessible::ButtonDropGrid 0x0000003A A button that drops down a grid.
QAccessible::ButtonMenu0x00000039 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::CheckBox0x0000002C 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::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::NoRole0x00000000Object has no role. This usually indicates an invalid object.
QAccessible::PageTab 0x00000025A page tab that the user can select to switch to a different page in a dialog.
QAccessible::PageTabList0x0000003C A list of page tabs.
QAccessible::Pane0x00000010A generic container.
QAccessible::PopupMenu0x0000000B A menu which lists options that the user can select to perform an action.
QAccessible::ProgressBar0x00000030 Object displays the progress of an operation in progress.
QAccessible::PropertyPage0x00000026 A property page where the user can change options and settings.
QAccessible::PushButton0x0000002BA button.
QAccessible::RadioButton0x0000002D An object that represents an option that is mutually exclusive with other options.
QAccessible::Row0x0000001C A row of cells, usually within a table.
QAccessible::RowHeader0x0000001A A header for a row of data.
QAccessible::ScrollBar0x00000003 A scroll bar, which allows the user to scroll the visible area.
QAccessible::Separator0x00000015A separator that divides space into logical areas.
QAccessible::Slider0x00000033 A slider that allows the user to select a value within a given range.
QAccessible::Sound0x00000005 An object that represents a sound.
QAccessible::SpinBox0x00000034 A spin box widget that allows the user to enter a value within a given range.
QAccessible::Splitter0x0000003E A splitter distributing available space between its child widgets.
QAccessible::StaticText0x00000029 Static text, such as labels for other widgets.
QAccessible::StatusBar0x00000017 A status bar.
QAccessible::Table0x00000018 A table representing data in a grid of rows and columns.
QAccessible::Terminal0x00000040 A terminal or command line interface.
QAccessible::TitleBar0x00000001 The title bar caption of a window.
QAccessible::ToolBar0x00000016 A toolbar, which groups widgets that the user accesses frequently.
QAccessible::ToolTip0x0000000D A tool tip which provides information about other objects.
QAccessible::Tree0x00000023 A list of items in a tree structure.
QAccessible::TreeItem0x00000024 An item in a tree structure.
QAccessible::UserRole0x0000ffff The first value to be used for user defined roles.
QAccessible::Whitespace0x0000003B Blank space between other objects.
QAccessible::Window0x00000009 A top level window.

This enum specifies string information that an accessible object returns.

QAccessible::Name 0 The name of the object, can be used both 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.

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

Method Documentation

QAccessibleInterface * QAccessible::accessibleInterface ( Id  uniqueId)

Returns the QAccessibleInterface belonging to the uniqueId. Returns nullptr if the id is invalid.

void QAccessible::deleteAccessibleInterface ( Id  uniqueId)

Removes the interface belonging to this uniqueId from the cache and deletes it. The id becomes invalid and may be reused by the cache.

void QAccessible::installFactory ( InterfaceFactory  factory)

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

RootObjectHandler QAccessible::installRootObjectHandler ( RootObjectHandler  handler)

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

bool QAccessible::isActive ( )

Returns true if an accessibility implementation has been requested during the runtime of the application, otherwise returns false. Use this method to prevent potentially expensive notifications via updateAccessibility().

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

The caller is responsible for deleting the returned interface after use.
Id QAccessible::registerAccessibleInterface ( QAccessibleInterface interfaceId)

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

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

When it is necessary to reimplement QAccessibleInterface::child(), call this method before returning the new child.

void QAccessible::removeFactory ( InterfaceFactory  factory)

Removes factory from the list of installed InterfaceFactories.

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 method. CopperSpice sets the QApplication object as the root object immediately before the event loop is entered in QApplication::exec(). Use QAccessible::installRootObjectHandler() to redirect the method to a customized handler function.

See also
Id QAccessible::uniqueId ( QAccessibleInterface interfaceId)

Returns the unique ID for the QAccessibleInterface interfaceId.

void QAccessible::updateAccessibility ( QAccessibleEvent event)

Notifies about a change which might be relevant for accessibility clients. The 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 to give meaningful notifications. For example, the type ValueChange indicates that the position of a slider has been changed.

Call this method whenever the state of your accessible object or one of its sub-elements has been changed either programmatically, by calling a method such as QLabel::setText(), or by user interaction.

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