QAccessible Class Reference
^{[QtGui module]}

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

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.

enum QAccessible::Event

This enum type defines accessible event types.

typedef QAccessible::InterfaceFactory

A function pointer type. Use a function with this prototype to install interface factories with installFactory().

The function receives a QObject pointer. If the QObject provides a QAccessibleInterface, it sets the second parameter to point to the corresponding QAccessibleInterface, and returns true; otherwise returns false.

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

enum QAccessible::RelationFlag
flags QAccessible::Relation

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

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:

typedef QAccessible::RootObjectHandler

A function pointer type. Use a function with this prototype to install your own root object handler.

The function is called by setRootObject().

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:

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.

typedef QAccessible::UpdateHandler

A function pointer type. Use a function with this prototype to install your own update function.

The function is called by updateAccessibility().

Member Function Documentation

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

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

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

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

UpdateHandler QAccessible::installUpdateHandler ( UpdateHandler handler )   [static]

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

bool QAccessible::isActive ()   [static]

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().

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

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.

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

Removes factory from the list of installed InterfaceFactories.

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

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 installRootObjectHandler() to redirect the function call to a customized handler function.

See also RootObjectHandler and queryAccessibleInterface().

void QAccessible::updateAccessibility ( QObject * object, int child, Event reason )   [static]

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 it's 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.