Update copyright headers
[qt:qt.git] / doc / src / frameworks-technologies / accessible.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
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.
16 **
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.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \group accessibility
30     \title Accessibility Classes
31 */
32
33 /*!
34     \page accessible.html
35     \title Accessibility
36     \brief How to make your applications accessible to those with disabilities.
37
38     \ingroup technology-apis
39     \ingroup qt-basic-concepts
40     \ingroup best-practices
41
42     \tableofcontents
43
44     \section1 Introduction
45
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.
51
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.
63
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. 
67
68     \section1 Architecture
69
70     Providing accessibility is a collaboration between accessibility
71     compliant applications, the assistive technology, and the
72     assistive tools. 
73
74     \image accessibilityarchitecture.png
75
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
81     document.
82
83     We will from now on focus on the Qt accessibility interface and
84     how it is implemented to create Qt applications that support
85     accessibility.
86
87     \section2 Accessibility in Qt
88     
89     These classes provide support for accessible applications.
90
91     \annotatedlist accessibility
92
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.
102
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.
108
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().
115
116     Three of the enums in QAccessible help clients query and alter
117     accessible objects:
118
119     \list
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
125             button.
126         \o \l{QAccessible::}{Relation}: Describes the relationship
127             between objects in the object tree.
128             This is used for navigation.
129     \endlist
130
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
134     about content.
135
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
139     menu.
140
141     \section2 The Accessible Object Tree
142
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
149     for.
150
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.
154
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
162     tree.
163
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().
173
174     To illustrate, we present an image of an accessible object tree.
175     Beneath the tree is a table with examples of object relationships.
176
177     \image accessibleobjecttree.png
178
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.
185
186     \table 40%
187         \header
188             \o Source Object
189             \o Target Object
190             \o Relation
191         \row
192             \o Slider
193             \o Indicator
194             \o Controller
195         \row
196             \o Indicator
197             \o Slider
198             \o Controlled
199         \row
200             \o Slider
201             \o Application
202             \o Ancestor
203         \row
204             \o Application
205             \o Slider
206             \o Child
207         \row
208             \o PushButton
209             \o Indicator
210             \o Sibling
211     \endtable
212
213     \section2 The Static QAccessible Functions
214
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}.
222
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
226     to do this yourself.
227
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()}.
233
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.
240
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
249     later.
250
251     \section2 Enabling Accessibility Support
252
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
257     the bash shell:
258
259     \snippet doc/src/snippets/code/doc_src_qt4-accessibility.cpp environment
260
261     Accessibility features are built into Qt by default when the libraries
262     are configured and built.
263
264     \section1 Implementing Accessibility
265
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.
274
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:
278
279     \list
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.
286     \endlist
287
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
292     need to consider.
293
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.
299
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.
307
308     \section2 The QAccessibleObject and QAccessibleWidget Convenience Classes
309
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.
315
316     The QAccessibleWidget provides the following functionality:
317
318     \list
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
322            \l{QWidget}s.
323         \o It handles action and methods that can be performed on
324            all widgets.
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.
331     \endlist
332
333     \section2 QAccessibleWidget Example
334
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:
344
345     \snippet doc/src/snippets/accessibilityslidersnippet.cpp 0
346
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:
354
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
358     specified.
359
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:
365
366     \snippet doc/src/snippets/qabstractsliderisnippet.cpp 0
367     \dots
368     \snippet doc/src/snippets/qabstractsliderisnippet.cpp 1
369     \dots
370     \snippet doc/src/snippets/qabstractsliderisnippet.cpp 2
371
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
374     receiving the event.
375
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()}:
384
385     \snippet doc/src/snippets/accessibilityslidersnippet.cpp 1
386     \dots
387     \snippet doc/src/snippets/accessibilityslidersnippet.cpp 2
388     \dots
389
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().
397
398     \snippet doc/src/snippets/accessibilityslidersnippet.cpp 3
399
400     Before the rectangle is returned it must be mapped to screen
401     coordinates.
402
403     The QAccessibleSlider must reimplement
404     QAccessibleInterface::childCount() since it manages children
405     without interfaces.
406
407     The \l{QAccessibleInterface::}{text()} function returns the
408     QAccessible::Text strings for the slider:
409
410     \snippet doc/src/snippets/accessibilityslidersnippet.cpp 4
411
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
417     provided.
418
419     The implementation of the \l{QAccessibleInterface::}{role()}
420     function is straightforward:
421
422     \snippet doc/src/snippets/accessibilityslidersnippet.cpp 5
423
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.
427
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:
432
433     \snippet doc/src/snippets/accessibilityslidersnippet.cpp 6
434     \dots
435     \snippet doc/src/snippets/accessibilityslidersnippet.cpp 7
436
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.
441
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.
447
448     \section2 Handling Action Requests from Clients
449
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:
454
455     \list
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.
462     \endlist
463
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()}.
467
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
474     application.
475
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:
482
483     \list
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.
489     \endlist
490
491     The action mechanism will probably be substituted by providing
492     methods in place of the standard actions. 
493
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
497     MSAA documentation.
498
499     \section2 Implementing Accessible Plugins
500
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.
506
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.
513
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()
517     function:
518
519     \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 0
520
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:
525
526     \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 1
527
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.
534
535     Finally, you need to include macros in the cpp file:
536
537     \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 2
538
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}.
545
546     You can omit the first macro unless you want the plugin
547     to be statically linked with the application.
548
549     \section2 Implementing Interface Factories
550
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.
555
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:
562
563     \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 0
564     \dots
565     \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 1
566
567     \omit
568
569     \section1 Implementing Bridges for Other Assistive Technologies
570
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.
576
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:
580
581     \list
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.
585     \endlist
586
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
590     application.
591
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.
599
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.
607
608     \endomit
609
610     \section1 Further Reading
611
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.
615     issues
616 */