source: trunk/doc/src/frameworks-technologies/accessible.qdoc@ 651

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \group accessibility
    \title Accessibility Classes
*/

/*!
    \page accessible.html
    \title Accessibility
    
    \ingroup frameworks-technologies

    \tableofcontents

    \section1 Introduction

    Accessibility in computer software is making applications usable
    for people with disabilities. This could be achieved by providing
    keyboard shortcuts, a high-contrast user interface that uses
    specially selected colors and fonts, or support for assistive tools
    such as screen readers and braille displays.

    An application does not usually communicate directly with
    assistive tools but through an assistive technology, which is a
    bridge for exchange of information between the applications and
    the tools. Information about user interface elements, such
    as buttons and scroll bars, is exposed to the assistive technologies.
    Qt supports Microsoft Active Accessibility (MSAA) on Windows and
    Mac OS X Accessibility on Mac OS X.
    On Unix/X11, support is preliminary. The individual technologies
    are abstracted from Qt, and there is only a single interface to
    consider. We will use MSAA throughout this document when we need
    to address technology related issues.

    In this overview document, we will examine the overall Qt
    accessibility architecture, and how to implement accessibility for
    custom widgets and elements. 

    \section1 Architecture

    Providing accessibility is a collaboration between accessibility
    compliant applications, the assistive technology, and the
    assistive tools. 

    \image accessibilityarchitecture.png

    Accessibility compliant applications are called AT-Servers while
    assistive tools are called AT-Clients. A Qt application will
    typically be an AT-Server, but specialized programs might also
    function like AT-Clients. We will refer to clients and servers
    when talking about AT-Clients and AT-Servers in the rest of this
    document.

    We will from now on focus on the Qt accessibility interface and
    how it is implemented to create Qt applications that support
    accessibility.

    \section2 Accessibility in Qt
    
    These classes provide support for accessible applications.

    \annotatedlist accessibility

    When we communicate with the assistive technologies, we need to
    describe Qt's user interface in a way that they can understand. Qt
    applications use QAccessibleInterface to expose information about the
    individual UI elements. Currently, Qt provides support for its widgets
    and widget parts, e.g., slider handles, but the interface could
    also be implemented for any QObject if necessary. QAccessible
    contains enums that describe the UI. The description is mainly
    based on MSAA and is independent of Qt. We will examine the enums
    in the course of this document.

    The structure of the UI is represented as a tree of
    QAccessibleInterface subclasses. You can think of this as a
    representation of a UI like the QObject tree built by Qt. Objects
    can be widgets or widget parts (such as scroll bar handles). We
    examine the tree in detail in the next section.

    Servers notify clients through \l{QAccessible::}{updateAccessibility()}
    about changes in objects by sending events, and the clients
    register to receive the events. The available events are defined
    by the QAccessible::Event enum. The clients may then query for
    the object that generated the event through
    QAccessible::queryAccessibleInterface().

    Three of the enums in QAccessible help clients query and alter
    accessible objects:

    \list
        \o \l{QAccessible::}{Role}: Describes the role the object
            fills in the user interface, e.g., if it is a main
            window, a text caret, or a cell in an item view.
        \o \l{QAccessible::}{Action}: The actions that the
            clients can perform on the objects, e.g., pushing a
            button.
        \o \l{QAccessible::}{Relation}: Describes the relationship
            between objects in the object tree.
            This is used for navigation.
    \endlist

    The clients also have some possibilities to get the content of
    objects, e.g., a button's text; the object provides strings
    defined by the QAccessible::Text enum, that give information
    about content.

    The objects can be in a number of different states as defined by
    the \l{QAccessible::}{State} enum. Examples of states are whether
    the object is disabled, if it has focus, or if it provides a pop-up
    menu.

    \section2 The Accessible Object Tree

    As mentioned, a tree structure is built from the accessible
    objects of an application. By navigating through the tree, the
    clients can access all elements in the UI. Object relations give
    clients information about the UI. For instance, a slider handle is
    a child of the slider to which it belongs. QAccessible::Relation
    describes the various relationships the clients can ask objects
    for.

    Note that there are no direct mapping between the Qt QObject tree
    and the accessible object tree. For instance, scroll bar handles
    are accessible objects but are not widgets or objects in Qt.

    AT-Clients have access to the accessibility object tree through
    the root object in the tree, which is the QApplication. They can
    query other objects through QAccessible::navigate(), which fetches
    objects based on \l{QAccessible::}{Relation}s. The children of any
    node is 1-based numbered. The child numbered 0 is the object
    itself. The children of all interfaces are numbered this way,
    i.e., it is not a fixed numbering from the root node in the entire
    tree.

    Qt provides accessible interfaces for its widgets. Interfaces for
    any QObject subclass can be requested through
    QAccessible::queryInterface(). A default implementation is
    provided if a more specialized interface is not defined. An
    AT-Client cannot acquire an interface for accessible objects that
    do not have an equivalent QObject, e.g., scroll bar handles, but
    they appear as normal objects through interfaces of parent
    accessible objects, e.g., you can query their relationships with
    QAccessible::relationTo().

    To illustrate, we present an image of an accessible object tree.
    Beneath the tree is a table with examples of object relationships.

    \image accessibleobjecttree.png

    The labels in top-down order are: the QAccessibleInterface class
    name, the widget for which an interface is provided, and the
    \l{QAccessible::}{Role} of the object. The Position, PageLeft and 
    PageRight correspond to the slider handle, the slider groove left
    and the slider groove right, respectively. These accessible objects
    do not have an equivalent QObject.

    \table 40%
        \header
            \o Source Object
            \o Target Object
            \o Relation
        \row
            \o Slider
            \o Indicator
            \o Controller
        \row
            \o Indicator
            \o Slider
            \o Controlled
        \row
            \o Slider
            \o Application
            \o Ancestor
        \row
            \o Application
            \o Slider
            \o Child
        \row
            \o PushButton
            \o Indicator
            \o Sibling
    \endtable

    \section2 The Static QAccessible Functions

    The accessibility is managed by QAccessible's static functions,
    which we will examine shortly. They produce QAccessible
    interfaces, build the object tree, and initiate the connection
    with MSAA or the other platform specific technologies. If you are
    only interested in learning how to make your application
    accessible, you can safely skip over this section to
    \l{Implementing Accessibility}.

    The communication between clients and the server is initiated when
    \l{QAccessible::}{setRootObject()} is called. This is done when
    the QApplication instance is instantiated and you should not have
    to do this yourself.

    When a QObject calls \l{QAccessible::}{updateAccessibility()},
    clients that are listening to events are notified of the
    change. The function is used to post events to the assistive
    technology, and accessible \l{QAccessible::Event}{events} are
    posted by \l{QAccessible::}{updateAccessibility()}.

    \l{QAccessible::}{queryAccessibleInterface()} returns accessible
    interfaces for \l{QObject}s. All widgets in Qt provide interfaces;
    if you need interfaces to control the behavior of other \l{QObject}
    subclasses, you must implement the interfaces yourself, although
    the QAccessibleObject convenience class implements parts of the
    functionality for you.

    The factory that produces accessibility interfaces for QObjects is
    a function of type QAccessible::InterfaceFactory. It is possible
    to have several factories installed. The last factory installed
    will be the first to be asked for interfaces.
    \l{QAccessible::}{queryAccessibleInterface()} uses the factories
    to create interfaces for \l{QObject}s. Normally, you need not be
    concerned about factories because you can implement plugins that
    produce interfaces. We will give examples of both approaches
    later.

    \section2 Enabling Accessibility Support

    By default, Qt applications are run with accessibility support
    enabled on Windows and Mac OS X. On Unix/X11 platforms, applications
    must be launched in an environment with the \c QT_ACCESSIBILITY
    variable set to 1. For example, this is set in the following way with
    the bash shell:

    \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc environment

    Accessibility features are built into Qt by default when the libraries
    are configured and built.

    \section1 Implementing Accessibility

    To provide accessibility support for a widget or other user
    interface element, you need to implement the QAccessibleInterface
    and distribute it in a QAccessiblePlugin. It is also possible to
    compile the interface into the application and provide a
    QAccessible::InterfaceFactory for it. The factory can be used if
    you link statically or do not want the added complexity of
    plugins.  This can be an advantage if you, for instance, are
    delivering a 3-rd party library.

    All widgets and other user interface elements should have
    interfaces and plugins. If you want your application to support
    accessibility, you will need to consider the following:

    \list
        \o Qt already implements accessibility for its own widgets.
           We therefore recommend that you use Qt widgets where possible.
        \o A QAccessibleInterface needs to be implemented for each element
           that you want to make available to accessibility clients.
        \o You need to send accessibility events from the custom
           user interface elements that you implement.
    \endlist

    In general, it is recommended that you are somewhat familiar with
    MSAA, which Qt's accessibility support originally was built for.
    You should also study the enum values of QAccessible, which
    describe the roles, actions, relationships, and events that you
    need to consider.

    Note that you can examine how Qt's widgets implement their
    accessibility. One major problem with the MSAA standard is that
    interfaces are often implemented in an inconsistent way. This
    makes life difficult for clients and often leads to guesswork on
    object functionality.

    It is possible to implement interfaces by inheriting
    QAccessibleInterface and implementing its pure virtual functions.
    In practice, however, it is usually preferable to inherit
    QAccessibleObject or QAccessibleWidget, which implement part of
    the functionality for you. In the next section, we will see an
    example of implementing accessibility for a widget by inheriting
    the QAccessibleWidget class.

    \section2 The QAccessibleObject and QAccessibleWidget Convenience Classes

    When implementing an accessibility interface for widgets, one would