1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \page qt4-accessibility.html

    44     \title Cross-Platform Accessibility Support in Qt 4

    45 

    46     \contentspage {What's New in Qt 4}{Home}

    47     \previouspage The New Qt Designer

    48     \nextpage The Qt 4 Database GUI Layer

    49 

    50     Qt 4 allows developers to write cross-platform applications that

    51     are usable by visually impaired users as well as by users with

    52     other disabilities. Qt accessibility will make applications

    53     accessible to more users and opens the governmental market, where

    54     accessibility is often a requirement.

    55 

    56     \section1 General Overview

    57 

    58     The accessibility classes have been extended in

    59     various ways since Qt 3. We added new functions and new enum

    60     values, and revised the API to make it more consistent with the

    61     rest of Qt. We also added two properties to QWidget,

    62     \l{QWidget::accessibleName}{accessibleName} and

    63     \l{QWidget::accessibleDescription}{accessibleDescription}, that

    64     can be set in \e{Qt Designer} to provide basic help texts without

    65     having to write any code.

    66 

    67     Qt's accessibility architecture is as follows. Qt offers one

    68     generic interface, QAccessibleInterface, that can be used to

    69     wrap all widgets and objects (e.g., QPushButton). This single

    70     interface provides all the metadata necessary for the assistive

    71     technologies. Qt provides implementations of this interface for

    72     its built-in widgets as plugins.

    73 

    74     A more detailed overview of the accessibility support in Qt can

    75     be found on the \l Accessibility page.

    76 

    77     \section1 Enabling Accessibility Support

    78 

    79     By default, Qt applications are run with accessibility support

    80     enabled on Windows and Mac OS X. On Unix/X11 platforms, applications

    81     must be launched in an environment with the \c QT_ACCESSIBILITY

    82     variable set to 1. For example, this is set in the following way with

    83     the bash shell:

    84 

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

    86 

    87     Accessibility features are built into Qt by default when the libraries

    88     are configured and built.

    89 

    90     \section1 Creating New Accessible Interfaces

    91 

    92     When you develop custom widgets, you can create custom subclasses

    93     of QAccessibleInterface and distribute them as plugins (using

    94     QAccessiblePlugin) or compile them into the application.

    95     Likewise, Qt's predefined accessibility support can be built as

    96     plugin (the default) or directly into the Qt library. The main

    97     advantage of using plugins is that the accessibility classes are

    98     only loaded into memory if they are actually used; they don't

    99     slow down the common case where no assistive technology is being

   100     used.

   101 

   102     In addition to QAccessibleInterface, Qt includes two convenience

   103     classes, QAccessibleObject and QAccessibleWidget, that

   104     provide the lowest common denominator of metadata (e.g., widget

   105     geometry, window title, basic help text). You can use them as

   106     base classes when wrapping your custom QObject or QWidget

   107     subclasses.

   108 

   109     Another new feature in Qt 4 is that Qt can now support other

   110     backends in addition to the predefined ones. This is done by

   111     subclassing QAccessibleBridge.

   112 

   113     \omit

   114     \section1 Software Layering

   115 

   116         Qt Application

   117             | links to

   118         Qt Accessibility Module

   119             | Plugin (in-process)

   120         Qt ATK Bridge

   121             | links to

   122         ATK

   123             | Plugin (in-process)

   124         at-spi

   125             | CORBA

   126         assistive technologies

   127 

   128     Windows:

   129 

   130         Qt Application

   131             | links to

   132         Qt Accessibility Module

   133             | COM (?)

   134         MSAA

   135             | ?

   136         assistive technologies

   137 

   138     Mac:

   139 

   140         ?

   141     \endomit

   142 

   143     \section1 Example Code

   144 

   145     The first example illustrates how to provide accessibility

   146     information for a custom widget. We can use QAccessibleWidget as

   147     a base class and reimplement various functions:

   148 

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

   150 

   151     Here's how we would implement the

   152     \l{QAccessibleInterface::doAction()}{doAction()} function to call

   153     a function named click() on the wrapped MyWidget object when the

   154     user invokes the object's default action or "presses" it.

   155 

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

   157 

   158     To export the widget interface as a plugin, we must subclass

   159     QAccessibleFactory:

   160 

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

   162 */