/****************************************************************************
**
** Copyright (C) 2004-2007 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License version 2.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 GNU
** General Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/
**
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.0, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** In addition, as a special exception, Trolltech, as the sole copyright
** holder for Qt Designer, grants users of the Qt/Eclipse Integration
** plug-in the right for the Qt/Eclipse Integration to link to
** functionality provided by Qt Designer and its related libraries.
**
** Trolltech reserves all rights not expressly granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \page qt4-accessibility.html
    \title Cross-Platform Accessibility Support in Qt 4

    \contentspage {What's New in Qt 4}{Home}
    \previouspage The New Qt Designer
    \nextpage The Qt 4 Database GUI Layer

    Qt 4 allows developers to write cross-platform applications that
    are usable by visually impaired users as well as by users with
    other disabilities. Qt accessibility will make applications
    accessible to more users and opens the governmental market, where
    accessibility is often a requirement.

    \section1 General Overview

    Qt 3 already supports Microsoft Active Accessibility (MSAA) and
    Mac OS X Accessibility. Qt 4 closes the gap in Trolltech's
    accessibility offering by introducing support for AT-SPI on
    Unix/X11 systems.

    The accessibility classes themselves have been extended in
    various ways since Qt 3. We added new functions and new enum
    values, and revised the API to make it more consistent with the
    rest of Qt. We also added two properties to QWidget,
    \l{QWidget::accessibleName}{accessibleName} and
    \l{QWidget::accessibleDescription}{accessibleDescription}, that
    can be set in \e{Qt Designer} to provide basic help texts without
    having to write any code.

    Qt's accessibility architecture is as follows. 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.

    In addition to QAccessibleInterface, Qt includes two convenience
    classes, QAccessibleObject and QAccessibleWidget, that
    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.

    Another new feature in Qt 4 is that Qt can now support other
    backends in addition to the predefined ones. This is done by
    subclassing QAccessibleBridge.

    \omit
    \section1 Software Layering

        Qt Application
            | links to
        Qt Accessibility Module
            | Plugin (in-process)
        Qt ATK Bridge
            | links to
        ATK
            | Plugin (in-process)
        at-spi
            | CORBA
        assistive technologies

    Windows:

        Qt Application
            | links to
        Qt Accessibility Module
            | COM (?)
        MSAA
            | ?
        assistive technologies

    Mac:

        ?
    \endomit

    \section1 Example Code

    The first example illustrates how to provide accessibility
    information for a custom widget. We can use QAccessibleWidget as
    a base class and reimplement various functions:

    \code
        class MyWidgetInterface : public QAccessibleWidget
        {
        public:
            MyWidgetInterface(QWidget *widget, Role role);

            QString text(Text text, int child) const;
            State state(int child) const;
            QString actionText(int action, Text text, int child) const;
            bool doAction(int action, int child, const QVariantList &params);
            ...
        };
    \endcode

    Here's how we would implement the
    \l{QAccessibleInterface::doAction()}{doAction()} function to call
    a function named click() on the wrapped MyWidget object when the
    user invokes the object's default action or "presses" it.

    \code
        bool MyWidgetInterface::doAction(int action, int child,
                                         const QVariantList &params)
        {
            if (child || !widget()->isEnabled())
                return false;

            switch (action) {
            case DefaultAction:
            case Press:
                {
                    MyWidget *widget = qobject_cast<MyWidget *>(object());
                    if (widget)
                        widget->click();
                }
                return true;
            }
            return QAccessibleWidget::doAction(action, child, params);
        }
    \endcode

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

    \code
        QStringList MyFactory::keys() const
        {
            return QStringList() << "MyWidget" << "MyOtherWidget";
        }

        QAccessibleInterface *MyFactory::create(const QString &className,
                                                QObject *object)
        {
            if (classname == "MyWidget")
                return new MyWidgetInterface(object);
            if (classname == "MyOtherWidget")
                return new MyOtherWidgetInterface(object);
            return 0;
        }

        Q_EXPORT_PLUGIN2(MyFactory)
    \endcode
*/
