1 /****************************************************************************
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file. Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
26 ****************************************************************************/
30 \title Accessibility Classes
36 \brief How to make your applications accessible to those with disabilities.
38 \ingroup technology-apis
39 \ingroup qt-basic-concepts
40 \ingroup best-practices
44 \section1 Introduction
46 Accessibility in computer software is making applications usable
47 for people with disabilities. This could be achieved by providing
48 keyboard shortcuts, a high-contrast user interface that uses
49 specially selected colors and fonts, or support for assistive tools
50 such as screen readers and braille displays.
52 An application does not usually communicate directly with
53 assistive tools but through an assistive technology, which is a
54 bridge for exchange of information between the applications and
55 the tools. Information about user interface elements, such as
56 buttons and scroll bars, is exposed to the assistive technologies.
57 Qt supports Microsoft Active Accessibility (MSAA) on Windows, Mac
58 OS X Accessibility on Mac OS X, and AT-SPI on Unix/X11. On
59 Unix/X11, support is preliminary. The individual technologies are
60 abstracted from Qt, and there is only a single interface to
61 consider. We will use MSAA throughout this document when we need
62 to address technology related issues.
64 In this overview document, we will examine the overall Qt
65 accessibility architecture, and how to implement accessibility for
66 custom widgets and elements.
68 \section1 Architecture
70 Providing accessibility is a collaboration between accessibility
71 compliant applications, the assistive technology, and the
74 \image accessibilityarchitecture.png
76 Accessibility compliant applications are called AT-Servers while
77 assistive tools are called AT-Clients. A Qt application will
78 typically be an AT-Server, but specialized programs might also
79 function like AT-Clients. We will refer to clients and servers
80 when talking about AT-Clients and AT-Servers in the rest of this
83 We will from now on focus on the Qt accessibility interface and
84 how it is implemented to create Qt applications that support
87 \section2 Accessibility in Qt
89 These classes provide support for accessible applications.
91 \annotatedlist accessibility
93 When we communicate with the assistive technologies, we need to
94 describe Qt's user interface in a way that they can understand. Qt
95 applications use QAccessibleInterface to expose information about the
96 individual UI elements. Currently, Qt provides support for its widgets
97 and widget parts, e.g., slider handles, but the interface could
98 also be implemented for any QObject if necessary. QAccessible
99 contains enums that describe the UI. The description is mainly
100 based on MSAA and is independent of Qt. We will examine the enums
101 in the course of this document.
103 The structure of the UI is represented as a tree of
104 QAccessibleInterface subclasses. You can think of this as a
105 representation of a UI like the QObject tree built by Qt. Objects
106 can be widgets or widget parts (such as scroll bar handles). We
107 examine the tree in detail in the next section.
109 Servers notify clients through \l{QAccessible::}{updateAccessibility()}
110 about changes in objects by sending events, and the clients
111 register to receive the events. The available events are defined
112 by the QAccessible::Event enum. The clients may then query for
113 the object that generated the event through
114 QAccessible::queryAccessibleInterface().
116 Three of the enums in QAccessible help clients query and alter
120 \o \l{QAccessible::}{Role}: Describes the role the object
121 fills in the user interface, e.g., if it is a main
122 window, a text caret, or a cell in an item view.
123 \o \l{QAccessible::}{Action}: The actions that the
124 clients can perform on the objects, e.g., pushing a
126 \o \l{QAccessible::}{Relation}: Describes the relationship
127 between objects in the object tree.
128 This is used for navigation.
131 The clients also have some possibilities to get the content of
132 objects, e.g., a button's text; the object provides strings
133 defined by the QAccessible::Text enum, that give information
136 The objects can be in a number of different states as defined by
137 the \l{QAccessible::}{State} enum. Examples of states are whether
138 the object is disabled, if it has focus, or if it provides a pop-up
141 \section2 The Accessible Object Tree
143 As mentioned, a tree structure is built from the accessible
144 objects of an application. By navigating through the tree, the
145 clients can access all elements in the UI. Object relations give
146 clients information about the UI. For instance, a slider handle is
147 a child of the slider to which it belongs. QAccessible::Relation
148 describes the various relationships the clients can ask objects
151 Note that there are no direct mapping between the Qt QObject tree
152 and the accessible object tree. For instance, scroll bar handles
153 are accessible objects but are not widgets or objects in Qt.
155 AT-Clients have access to the accessibility object tree through
156 the root object in the tree, which is the QApplication. They can
157 query other objects through QAccessible::navigate(), which fetches
158 objects based on \l{QAccessible::}{Relation}s. The children of any
159 node is 1-based numbered. The child numbered 0 is the object
160 itself. The children of all interfaces are numbered this way,
161 i.e., it is not a fixed numbering from the root node in the entire
164 Qt provides accessible interfaces for its widgets. Interfaces for
165 any QObject subclass can be requested through
166 QAccessible::queryInterface(). A default implementation is
167 provided if a more specialized interface is not defined. An
168 AT-Client cannot acquire an interface for accessible objects that
169 do not have an equivalent QObject, e.g., scroll bar handles, but
170 they appear as normal objects through interfaces of parent
171 accessible objects, e.g., you can query their relationships with
172 QAccessible::relationTo().
174 To illustrate, we present an image of an accessible object tree.
175 Beneath the tree is a table with examples of object relationships.
177 \image accessibleobjecttree.png
179 The labels in top-down order are: the QAccessibleInterface class
180 name, the widget for which an interface is provided, and the
181 \l{QAccessible::}{Role} of the object. The Position, PageLeft and
182 PageRight correspond to the slider handle, the slider groove left
183 and the slider groove right, respectively. These accessible objects
184 do not have an equivalent QObject.
213 \section2 The Static QAccessible Functions
215 The accessibility is managed by QAccessible's static functions,
216 which we will examine shortly. They produce QAccessible
217 interfaces, build the object tree, and initiate the connection
218 with MSAA or the other platform specific technologies. If you are
219 only interested in learning how to make your application
220 accessible, you can safely skip over this section to
221 \l{Implementing Accessibility}.
223 The communication between clients and the server is initiated when
224 \l{QAccessible::}{setRootObject()} is called. This is done when
225 the QApplication instance is instantiated and you should not have
228 When a QObject calls \l{QAccessible::}{updateAccessibility()},
229 clients that are listening to events are notified of the
230 change. The function is used to post events to the assistive
231 technology, and accessible \l{QAccessible::Event}{events} are
232 posted by \l{QAccessible::}{updateAccessibility()}.
234 \l{QAccessible::}{queryAccessibleInterface()} returns accessible
235 interfaces for \l{QObject}s. All widgets in Qt provide interfaces;
236 if you need interfaces to control the behavior of other \l{QObject}
237 subclasses, you must implement the interfaces yourself, although
238 the QAccessibleObject convenience class implements parts of the
239 functionality for you.
241 The factory that produces accessibility interfaces for QObjects is
242 a function of type QAccessible::InterfaceFactory. It is possible
243 to have several factories installed. The last factory installed
244 will be the first to be asked for interfaces.
245 \l{QAccessible::}{queryAccessibleInterface()} uses the factories
246 to create interfaces for \l{QObject}s. Normally, you need not be
247 concerned about factories because you can implement plugins that
248 produce interfaces. We will give examples of both approaches
251 \section2 Enabling Accessibility Support
253 By default, Qt applications are run with accessibility support
254 enabled on Windows and Mac OS X. On Unix/X11 platforms, applications
255 must be launched in an environment with the \c QT_ACCESSIBILITY
256 variable set to 1. For example, this is set in the following way with
259 \snippet doc/src/snippets/code/doc_src_qt4-accessibility.cpp environment
261 Accessibility features are built into Qt by default when the libraries
262 are configured and built.
264 \section1 Implementing Accessibility
266 To provide accessibility support for a widget or other user
267 interface element, you need to implement the QAccessibleInterface
268 and distribute it in a QAccessiblePlugin. It is also possible to
269 compile the interface into the application and provide a
270 QAccessible::InterfaceFactory for it. The factory can be used if
271 you link statically or do not want the added complexity of
272 plugins. This can be an advantage if you, for instance, are
273 delivering a 3-rd party library.
275 All widgets and other user interface elements should have
276 interfaces and plugins. If you want your application to support
277 accessibility, you will need to consider the following:
280 \o Qt already implements accessibility for its own widgets.
281 We therefore recommend that you use Qt widgets where possible.
282 \o A QAccessibleInterface needs to be implemented for each element
283 that you want to make available to accessibility clients.
284 \o You need to send accessibility events from the custom
285 user interface elements that you implement.
288 In general, it is recommended that you are somewhat familiar with
289 MSAA, which Qt's accessibility support originally was built for.
290 You should also study the enum values of QAccessible, which
291 describe the roles, actions, relationships, and events that you
294 Note that you can examine how Qt's widgets implement their
295 accessibility. One major problem with the MSAA standard is that
296 interfaces are often implemented in an inconsistent way. This
297 makes life difficult for clients and often leads to guesswork on
298 object functionality.
300 It is possible to implement interfaces by inheriting
301 QAccessibleInterface and implementing its pure virtual functions.
302 In practice, however, it is usually preferable to inherit
303 QAccessibleObject or QAccessibleWidget, which implement part of
304 the functionality for you. In the next section, we will see an
305 example of implementing accessibility for a widget by inheriting
306 the QAccessibleWidget class.
308 \section2 The QAccessibleObject and QAccessibleWidget Convenience Classes
310 When implementing an accessibility interface for widgets, one would
311 as a rule inherit QAccessibleWidget, which is a convenience class
312 for widgets. Another available convenience class, which is
313 inherited by QAccessibleWidget, is the QAccessibleObject, which
314 implements part of the interface for QObjects.
316 The QAccessibleWidget provides the following functionality:
319 \o It handles the navigation of the tree and
320 hit testing of the objects.
321 \o It handles events, roles, and actions that are common for all
323 \o It handles action and methods that can be performed on
325 \o It calculates bounding rectangles with
326 \l{QAccessibleInterface::}{rect()}.
327 \o It gives \l{QAccessibleInterface::}{text()} strings that are
328 appropriate for a generic widget.
329 \o It sets the \l{QAccessible::State}{states} that
330 are common for all widgets.
333 \section2 QAccessibleWidget Example
335 Instead of creating a custom widget and implementing an interface
336 for it, we will show how accessibility is implemented for one of
337 Qt's standard widgets: QSlider. The accessible interface,
338 QAccessibleSlider, inherits from QAccessibleAbstractSlider, which
339 in turn inherits QAccessibleWidget. You do not need to examine the
340 QAccessibleAbstractSlider class to read this section. If you want
341 to take a look, the code for all of Qt's accessible interfaces are
342 found in src/plugins/accessible/widgets. Here is the
343 QAccessibleSlider's constructor:
345 \snippet doc/src/snippets/accessibilityslidersnippet.cpp 0
347 The slider is a complex control that functions as a
348 \l{QAccessible::}{Controller} for its accessible children.
349 This relationship must be known by the interface (for
350 \l{QAccessibleInterface::}{relationTo()} and
351 \l{QAccessibleInterface::}{navigate()}). This can be done
352 using a controlling signal, which is a mechanism provided by
353 QAccessibleWidget. We do this in the constructor:
355 The choice of signal shown is not important; the same principles
356 apply to all signals that are declared in this way. Note that we
357 use QLatin1String to ensure that the signal name is correctly
360 When an accessible object is changed in a way that users need
361 to know about, it notifies clients of the change by sending them
362 an event via the accessible interface. This is how QSlider calls
363 \l{QAccessibleInterface::}{updateAccessibility()} to indicate that
364 its value has changed:
366 \snippet doc/src/snippets/qabstractsliderisnippet.cpp 0
368 \snippet doc/src/snippets/qabstractsliderisnippet.cpp 1
370 \snippet doc/src/snippets/qabstractsliderisnippet.cpp 2
372 Note that the call is made after the value of the slider has
373 changed because clients may query the new value immediately after
376 The interface must be able to calculate bounding rectangles of
377 itself and any children that do not provide an interface of their
378 own. The \c QAccessibleSlider has three such children identified by
379 the private enum, \c SliderElements, which has the following values:
380 \c PageLeft (the rectangle on the left hand side of the slider
381 handle), \c PageRight (the rectangle on the right hand side of the
382 handle), and \c Position (the slider handle). Here is the
383 implementation of \l{QAccessibleInterface::}{rect()}:
385 \snippet doc/src/snippets/accessibilityslidersnippet.cpp 1
387 \snippet doc/src/snippets/accessibilityslidersnippet.cpp 2
390 The first part of the function, which we have omitted, uses the
391 current \l{QStyle}{style} to calculate the slider handle's
392 bounding rectangle; it is stored in \c srect. Notice that child 0,
393 covered in the default case in the above code, is the slider itself,
394 so we can simply return the QSlider bounding rectangle obtained
395 from the superclass, which is effectively the value obtained from
396 QAccessibleWidget::rect().
398 \snippet doc/src/snippets/accessibilityslidersnippet.cpp 3
400 Before the rectangle is returned it must be mapped to screen
403 The QAccessibleSlider must reimplement
404 QAccessibleInterface::childCount() since it manages children
407 The \l{QAccessibleInterface::}{text()} function returns the
408 QAccessible::Text strings for the slider:
410 \snippet doc/src/snippets/accessibilityslidersnippet.cpp 4
412 The \c slider() function returns a pointer to the interface's
413 QSlider. Some values are left for the superclass's implementation.
414 Not all values are appropriate for all accessible objects, as you
415 can see for QAccessible::Value case. You should just return an
416 empty string for those values where no relevant text can be
419 The implementation of the \l{QAccessibleInterface::}{role()}
420 function is straightforward:
422 \snippet doc/src/snippets/accessibilityslidersnippet.cpp 5
424 The role function should be reimplemented by all objects and
425 describes the role of themselves and the children that do not
426 provide accessible interfaces of their own.
428 Next, the accessible interface needs to return the
429 \l{QAccessible::State}{states} that the slider can be in. We look
430 at parts of the \c state() implementation to show how just a few
431 of the states are handled:
433 \snippet doc/src/snippets/accessibilityslidersnippet.cpp 6
435 \snippet doc/src/snippets/accessibilityslidersnippet.cpp 7
437 The superclass implementation of
438 \l{QAccessibleInterface::}{state()}, uses the
439 QAccessibleInterface::state() implementation. We simply need to
440 disable the buttons if the slider is at its minimum or maximum.
442 We have now exposed the information we have about the slider to
443 the clients. For the clients to be able to alter the slider - for
444 example, to change its value - we must provide information about
445 the actions that can be performed and perform them upon request.
446 We discuss this in the next section.
448 \section2 Handling Action Requests from Clients
450 QAccessible provides a number of \l{QAccessible::}{Action}s
451 that can be performed on request from clients. If an
452 accessible object supports actions, it should reimplement the
453 following functions from QAccessibleInterface:
456 \o \l{QAccessibleInterface::}{actionText()} returns
457 strings that describe each action. The descriptions
458 to be made available are one for each
459 \l{QAccessible::}{Text} enum value.
460 \o \l{QAccessibleInterface::}{doAction()} executes requests
461 from clients to perform actions.
464 Note that a client can request any action from an object. If
465 the object does not support the action, it returns false from
466 \l{QAccessibleInterface::}{doAction()}.
468 None of the standard actions take any parameters. It is possible
469 to provide user-defined actions that can take parameters.
470 The interface must then also reimplement
471 \l{QAccessibleInterface::}{userActionCount()}. Since this is not
472 defined in the MSAA specification, it is probably only useful to
473 use this if you know which specific AT-Clients will use the
476 QAccessibleInterface gives another technique for clients to handle
477 accessible objects. It works basically the same way, but uses the
478 concept of methods in place of actions. The available methods are
479 defined by the QAccessible::Method enum. The following functions
480 need to be reimplemented from QAccessibleInterface if the
481 accessible object is to support methods:
484 \o \l{QAccessibleInterface::}{supportedMethods()} returns
485 a QSet of \l{QAccessible::}{Method} values that are
486 supported by the object.
487 \o \l{QAccessibleInterface::}{invokeMethod()} executes
488 methods requested by clients.
491 The action mechanism will probably be substituted by providing
492 methods in place of the standard actions.
494 To see examples on how to implement actions and methods, you
495 could examine the QAccessibleObject and QAccessibleWidget
496 implementations. You might also want to take a look at the
499 \section2 Implementing Accessible Plugins
501 In this section we will explain the procedure of implementing
502 accessible plugins for your interfaces. A plugin is a class stored
503 in a shared library that can be loaded at run-time. It is
504 convenient to distribute interfaces as plugins since they will only
505 be loaded when required.
507 Creating an accessible plugin is achieved by inheriting
508 QAccessiblePlugin, reimplementing \l{QAccessiblePlugin::}{keys()}
509 and \l{QAccessiblePlugin::}{create()} from that class, and adding
510 one or two macros. The \c .pro file must be altered to use the
511 plugin template, and the library containing the plugin must be
512 placed on a path where Qt searches for accessible plugins.
514 We will go through the implementation of \c SliderPlugin, which is
515 an accessible plugin that produces the QAccessibleSlider interface
516 from the \l{QAccessibleWidget Example}. We start with the \c key()
519 \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 0
521 We simply need to return the class name of the single interface
522 our plugin can create an accessible interface for. A plugin
523 can support any number of classes; just add more class names
524 to the string list. We move on to the \c create() function:
526 \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 1
528 We check whether the interface requested is for QSlider; if it is,
529 we create and return an interface for it. Note that \c object will
530 always be an instance of \c classname. You must return 0 if you do
531 not support the class. \l{QAccessible::}{updateAccessibility()}
532 checks with the available accessibility plugins until it finds one
533 that does not return 0.
535 Finally, you need to include macros in the cpp file:
537 \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 2
539 The Q_EXPORT_PLUGIN2 macro exports the plugin in the \c
540 SliderPlugin class into the \c acc_sliderplugin library. The first
541 argument is the name of the plugin library file, excluding the
542 file suffix, and the second is the class name. For more
543 information on plugins, you can consult the plugins \l{How to
544 Create Qt Plugins}{overview document}.
546 You can omit the first macro unless you want the plugin
547 to be statically linked with the application.
549 \section2 Implementing Interface Factories
551 If you do not want to provide plugins for your accessibility
552 interfaces, you can use an interface factory
553 (QAccessible::InterfaceFactory), which is the recommended way to
554 provide accessible interfaces in a statically-linked application.
556 A factory is a function pointer for a function that takes the same
557 parameters as \l{QAccessiblePlugin}'s
558 \l{QAccessiblePlugin::}{create()} - a QString and a QObject. It
559 also works the same way. You install the factory with the
560 \l{QAccessible::}{installFactory()} function. We give an example
561 of how to create a factory for the \c QAccessibleSlider interface:
563 \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 0
565 \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 1
569 \section1 Implementing Bridges for Other Assistive Technologies
571 An accessibility bridge provides the means for an assistive
572 technology to talk to Qt. On Windows and Mac, the built-in bridges
573 will be used. On UNIX, however, there are no built-in standard
574 assistive technology, and it might therefore be necessary to
575 implement an accessible bridge.
577 A bridge is implemented by inheriting QAccessibleBridge for the
578 technology to support. The class defines the interface that Qt
579 needs an assistive technology to support:
582 \o A root object. This is the root in the accessible
583 object tree and is of type QAccessibleInterface.
584 \o Receive events from from accessible objects.
587 The root object is set with the
588 \l{QAccessibleBridge::}{setRootObject()}. In the case of Qt, this
589 will always be an interface for the QApplication instance of the
592 Event notification is sent through
593 \l{QAccessibleBridge::}{notifyAccessibilityUpdate()}. This
594 function is called by \l{QAccessible::}{updateAccessibility()}. Even
595 though the bridge needs only to implement these two functions, it
596 must be able to communicate the entire QAccessibleInterface to the
597 underlying technology. How this is achieved is, naturally, up to
598 the individual bridge and none of Qt's concern.
600 As with accessible interfaces, you distribute accessible bridges
601 in plugins. Accessible bridge plugins are subclasses of the
602 QAccessibleBridgePlugin class; the class defines the functions
603 \l{QAccessibleBridgePlugin::}{create()} and
604 \l{QAccessibleBridgePlugin::}{keys()}, which must me
605 reimplemented. If Qt finds a built-in bridge to use, it will
606 ignore any available plugins.
610 \section1 Further Reading
612 The \l{Cross-Platform Accessibility Support in Qt 4} document contains a more
613 general overview of Qt's accessibility features and discusses how it is
614 used on each platform.
projects / qt:qt.git / blob