/****************************************************************************

**

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

** All rights reserved.

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

**

** This file is part of the QtGui module of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** 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.

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#include "qaccessible.h"

#ifndef QT_NO_ACCESSIBILITY

#include "qaccessibleplugin.h"

#include "qaccessiblewidget.h"

#include "qapplication.h"

#include "qhash.h"

#include "qmetaobject.h"

#include "qmutex.h"

#include <private/qfactoryloader_p.h>

#include "qwidget.h"

QT_BEGIN_NAMESPACE

/*!

    \class QAccessible

    \brief The QAccessible class provides enums and static functions

    relating to accessibility.

    \ingroup accessibility

    Accessible applications can be used by people who are not able to

    use applications by conventional means.

    The functions in this class are used for communication between

    accessible applications (also called AT Servers) and

    accessibility tools (AT Clients), such as screen readers and

    braille displays. Clients and servers communicate in the following way:

    \list

    \o  \e{AT Servers} notify the clients about events through calls to the

        updateAccessibility() function.

    \o  \e{AT Clients} request information about the objects in the server.

        The QAccessibleInterface class is the core interface, and encapsulates

        this information in a pure virtual API. Implementations of the interface

        are provided by Qt through the queryAccessibleInterface() API.

    \endlist

    The communication between servers and clients is initialized by

    the setRootObject() function. Function pointers can be installed

    to replace or extend the default behavior of the static functions

    in QAccessible.

    Qt supports Microsoft Active Accessibility (MSAA), Mac OS X

    Accessibility, and the Unix/X11 AT-SPI standard. Other backends

    can be supported using QAccessibleBridge.

    In addition to QAccessible's static functions, 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.

    Qt also includes two convenience classes, QAccessibleObject and

    QAccessibleWidget, that inherit from QAccessibleInterface and

    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.

    \sa QAccessibleInterface

*/

/*!

    \enum QAccessible::Action

    This enum describes the possible types of action that can occur.

    \value DefaultAction

    \value Press

    \value SetFocus

    \value Increase

    \value Decrease

    \value Accept

    \value Cancel

    \value Select

    \value ClearSelection

    \value RemoveSelection

    \value ExtendSelection

    \value AddToSelection

    \value FirstStandardAction

    \value LastStandardAction

*/

/*!

    \enum QAccessible::Method

    This enum describes the possible types of methods that can be

    invoked on an accessible object.

    \value ListSupportedMethods

    \value SetCursorPosition

    \value GetCursorPosition

    \omitvalue ForegroundColor

    \omitvalue BackgroundColor

    \sa QAccessibleInterface::invokeMethod()

*/

/*!

    \fn QSet<Method> QAccessibleInterface::supportedMethods()

    \since 4.3

    Returns a QSet of \l{QAccessible::}{Method}s that are supported by this

    accessible interface.

    \sa QAccessible::Method invokeMethod()

*/

/*!

    \enum QAccessible::StateFlag

    This enum type defines bit flags that can be combined to indicate

    the state of an accessible object. The values are:

    \value Animated         The object's appearance changes frequently.

    \value Busy             The object cannot accept input at the moment.

    \value Checked          The object's check box is checked.

    \value Collapsed        The object is collapsed, e.g. a closed listview item, or an iconified window.

    \value DefaultButton    The object represents the default button in a dialog.

    \value Expanded         The object is expandable, and currently the children are visible.

    \value ExtSelectable    The object supports extended selection.

    \value Focusable        The object can receive focus. Only objects in the active window can receive focus.

    \value Focused          The object has keyboard focus.

    \value HasPopup         The object opens a popup.

    \value HotTracked       The object's appearance is sensitive to the mouse cursor position.

    \value Invisible        The object is not visible to the user.

    \value Linked           The object is linked to another object, e.g. a hyperlink.

    \value Marqueed         The object displays scrolling contents, e.g. a log view.

    \value Mixed            The state of the object is not determined, e.g. a tri-state check box that is neither checked nor unchecked.

    \value Modal            The object blocks input from other objects.

    \value Movable          The object can be moved.

    \value MultiSelectable  The object supports multiple selected items.

    \value Normal           The normal state.

    \value Offscreen        The object is clipped by the visible area. Objects that are off screen are also invisible.

    \value Pressed          The object is pressed.

    \value Protected        The object is password protected, e.g. a line edit for entering a Password.

    \value ReadOnly         The object can usually be edited, but is explicitly set to read-only.

    \value Selectable       The object is selectable.

    \value Selected         The object is selected.

    \value SelfVoicing      The object describes itself through speech or sound.

    \value Sizeable         The object can be resized, e.g. top-level windows.

    \value Traversed        The object is linked and has been visited.

    \value Unavailable      The object is unavailable to the user, e.g. a disabled widget.

    \omitvalue Moveable

    \omitvalue HasInvokeExtension

    Implementations of QAccessibleInterface::state() return a combination

    of these flags.

*/

/*!

    \enum QAccessible::Event

    This enum type defines accessible event types.

    \value AcceleratorChanged

    \value Alert                 A system alert (e.g., a message from a QMessageBox)

    \value ContextHelpEnd        Context help (QWhatsThis) for an object is finished.

    \value ContextHelpStart      Context help (QWhatsThis) for an object is initiated.

    \value DefaultActionChanged  The default QAccessible::Action for the accessible object changed

    \value DescriptionChanged    The objects QAccessible::Description changed.

    \value DialogEnd             A dialog (QDialog) is been hidden

    \value DialogStart           A dialog (QDialog) has been set visible.

    \value DragDropEnd           A Drag & Drop operation is about to finished.

    \value DragDropStart         A Drag & Drop operation is about to be initiated.

    \value Focus                 An object has gained keyboard focus.

    \value ForegroundChanged     A window has been activated (i.e., a new window has gained focus on the desktop)

    \value HelpChanged           The QAccessible::Help text property of an object has changed

    \value LocationChanged       An objects location on the screen changed

    \value MenuCommand           A menu item is triggered.

    \value MenuEnd               A menu has been closed (Qt uses PopupMenuEnd for all menus)

    \value MenuStart             A menu has been opened on the menubar (Qt uses PopupMenuStart for all menus)

    \value NameChanged           The QAccessible::Name property of an object has changed

    \value ObjectCreated         A new object is created.

    \value ObjectDestroyed       An object is deleted.

    \value ObjectHide            An object is hidden (i.e., with QWidget::hide()). Any children the object that is hidden has do not send this event.

                                 It is not send when an object is hidden as it is being obcured by others.

    \value ObjectReorder         A layout or item view  has added, removed, or moved an object (Qt does not use this event).

    \value ObjectShow            An object is displayed (i.e., with QWidget::show()).

    \value ParentChanged         An objects parent object changed.

    \value PopupMenuEnd          A popup menu has closed.

    \value PopupMenuStart        A popupmenu has opened.

    \value ScrollingEnd          A scrollbar scroll operation has ended (the mouse has released the slider handle)

    \value ScrollingStart        A scrollbar scroll operation is about to start (i.e., the mouse has pressed on the slider handle)

    \value Selection             The selection has changed in a menu or item view.

    \value SelectionAdd          An item has been added to the selection in an item view.

    \value SelectionRemove       An item has been removed from an item view selection.

    \value SelectionWithin       Several changes to a selection has occurred in an item view.

    \value SoundPlayed           A sound has been played by an object

    \value StateChanged          The QAccessible::State of an object has changed.

    \value ValueChanged          The QAccessible::Value of an object has changed.

*/

/*!

    \enum QAccessible::Role

    This enum defines the role of an accessible object. The roles are:

    \value AlertMessage     An object that is used to alert the user.

    \value Animation        An object that displays an animation.

    \value Application      The application's main window.

    \value Assistant        An object that provids interactive help.

    \value Border           An object that represents a border.

    \value ButtonDropDown   A button that drops down a list of items.

    \value ButtonDropGrid   A button that drops down a grid.

    \value ButtonMenu       A button that drops down a menu.

    \value Canvas           An object that displays graphics that the user can interact with.

    \value Caret            An object that represents the system caret (text cursor).

    \value Cell             A cell in a table.

    \value Chart            An object that displays a graphical representation of data.

    \value CheckBox         An object that represents an option that can be checked or unchecked. Some options provide a "mixed" state, e.g. neither checked nor unchecked.

    \value Client           The client area in a window.

    \value Clock            A clock displaying time.

    \value Column           A column of cells, usually within a table.

    \value ColumnHeader     A header for a column of data.

    \value ComboBox         A list of choices that the user can select from.

    \value Cursor           An object that represents the mouse cursor.

    \value Dial             An object that represents a dial or knob.

    \value Dialog           A dialog box.

    \value Document         A document window, usually in an MDI environment.

    \value EditableText     Editable text

    \value Equation         An object that represents a mathematical equation.

    \value Graphic          A graphic or picture, e.g. an icon.

    \value Grip             A grip that the user can drag to change the size of widgets.

    \value Grouping         An object that represents a logical grouping of other objects.

    \value HelpBalloon      An object that displays help in a separate, short lived window.

    \value HotkeyField      A hotkey field that allows the user to enter a key sequence.

    \value Indicator        An indicator that represents a current value or item.

    \value LayeredPane      An object that can contain layered children, e.g. in a stack.

    \value Link             A link to something else.

    \value List             A list of items, from which the user can select one or more items.

    \value ListItem         An item in a list of items.

    \value MenuBar          A menu bar from which menus are opened by the user.

    \value MenuItem         An item in a menu or menu bar.

    \value NoRole           The object has no role. This usually indicates an invalid object.

    \value PageTab          A page tab that the user can select to switch to a different page in a dialog.

    \value PageTabList      A list of page tabs.

    \value Pane             A generic container.

    \value PopupMenu        A menu which lists options that the user can select to perform an action.

    \value ProgressBar      The object displays the progress of an operation in progress.

    \value PropertyPage     A property page where the user can change options and settings.

    \value PushButton       A button.

    \value RadioButton      An object that represents an option that is mutually exclusive with other options.

    \value Row              A row of cells, usually within a table.

    \value RowHeader        A header for a row of data.

    \value ScrollBar        A scroll bar, which allows the user to scroll the visible area.

    \value Separator        A separator that divides space into logical areas.

    \value Slider           A slider that allows the user to select a value within a given range.

    \value Sound            An object that represents a sound.

    \value SpinBox          A spin box widget that allows the user to enter a value within a given range.

    \value Splitter         A splitter distributing available space between its child widgets.

    \value StaticText       Static text, such as labels for other widgets.

    \value StatusBar        A status bar.

    \value Table            A table representing data in a grid of rows and columns.

    \value TitleBar         The title bar caption of a window.

    \value ToolBar          A tool bar, which groups widgets that the user accesses frequently.

    \value ToolTip          A tool tip which provides information about other objects.

    \value Tree             A list of items in a tree structure.

    \value TreeItem         An item in a tree structure.

    \value UserRole         The first value to be used for user defined roles.

    \value Whitespace       Blank space between other objects.

    \value Window           A top level window.

*/

/*!

    \enum QAccessible::RelationFlag

    This enum type defines bit flags that can be combined to indicate

    the relationship between two accessible objects.

    \value Unrelated        The objects are unrelated.

    \value Self             The objects are the same.

    \value Ancestor         The first object is a parent of the second object.

    \value Child            The first object is a direct child of the second object.

    \value Descendent       The first object is an indirect child of the second object.

    \value Sibling          The objects are siblings.

    \value Up               The first object is above the second object.

    \value Down             The first object is below the second object.

    \value Left             The first object is left of the second object.

    \value Right            The first object is right of the second object.

    \value Covers           The first object covers the second object.

    \value Covered          The first object is covered by the second object.

    \value FocusChild       The first object is the second object's focus child.

    \value Label            The first object is the label of the second object.

    \value Labelled         The first object is labelled by the second object.

    \value Controller       The first object controls the second object.

    \value Controlled       The first object is controlled by the second object.

    \omitvalue HierarchyMask

    \omitvalue GeometryMask

    \omitvalue LogicalMask

    Implementations of relationTo() return a combination of these flags.

    Some values are mutually exclusive.

    Implementations of navigate() can accept only one distinct value.

*/

/*!

    \enum QAccessible::Text

    This enum specifies string information that an accessible object

    returns.

    \value Name         The name of the object. This can be used both

                        as an identifier or a short description by

                        accessible clients.

    \value Description  A short text describing the object.

    \value Value        The value of the object.

    \value Help         A longer text giving information about how to use the object.

    \value Accelerator  The keyboard shortcut that executes the object's default action.

    \value UserText     The first value to be used for user defined text.

*/

/*!

    \fn QAccessibleInterface::~QAccessibleInterface()

    Destroys the object.

*/

/*!

    \fn void QAccessible::initialize()

    \internal

*/

/*!

    \fn void QAccessible::cleanup()

    \internal

*/

#if !defined(QT_NO_LIBRARY) && (!defined(QT_NO_SETTINGS) || !defined(Q_OS_WIN))

Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,

    (QAccessibleFactoryInterface_iid, QLatin1String("/accessible")))

#endif

Q_GLOBAL_STATIC(QList<QAccessible::InterfaceFactory>, qAccessibleFactories)

QAccessible::UpdateHandler QAccessible::updateHandler = 0;

QAccessible::RootObjectHandler QAccessible::rootObjectHandler = 0;

static bool accessibility_active = false;

static bool cleanupAdded = false;

static void qAccessibleCleanup()

{

    qAccessibleFactories()->clear();

}

/*!

    \typedef QAccessible::InterfaceFactory

    A function pointer type. Use a function with this prototype to install

    interface factories with installFactory().

    The function receives a QObject pointer. If the QObject

    provides a QAccessibleInterface, it sets the second parameter to

    point to the corresponding QAccessibleInterface, and returns true;

    otherwise returns false.

    Installed factories are called by queryAccessibilityInterface() until

    one provides an interface.

*/

/*!

    \typedef QAccessible::UpdateHandler

    \internal

    A function pointer type. Use a function with this prototype to install

    your own update function.

    The function is called by updateAccessibility().

*/

/*!

    \typedef QAccessible::RootObjectHandler

    \internal

    A function pointer type. Use a function with this prototype to install

    your own root object handler.

    The function is called by setRootObject().

*/

/*!

    Installs the InterfaceFactory \a factory. The last factory added

    is the first one used by queryAccessibleInterface().

*/

void QAccessible::installFactory(InterfaceFactory factory)

{

    if (!factory)

        return;

    if (!cleanupAdded) {

        qAddPostRoutine(qAccessibleCleanup);

        cleanupAdded = true;

    }

    if (qAccessibleFactories()->contains(factory))

        return;

    qAccessibleFactories()->append(factory);

}

/*!

    Removes \a factory from the list of installed InterfaceFactories.

*/

void QAccessible::removeFactory(InterfaceFactory factory)

{

    qAccessibleFactories()->removeAll(factory);

}

/*!

    \internal

    Installs the given \a handler as the function to be used by

    updateAccessibility(), and returns the previously installed

    handler.

*/

QAccessible::UpdateHandler QAccessible::installUpdateHandler(UpdateHandler handler)

{

    UpdateHandler old = updateHandler;

    updateHandler = handler;

    return old;

}

/*!

    Installs the given \a handler as the function to be used by setRootObject(),

    and returns the previously installed handler.

*/

QAccessible::RootObjectHandler QAccessible::installRootObjectHandler(RootObjectHandler handler)

{

    RootObjectHandler old = rootObjectHandler;

    rootObjectHandler = handler;

    return old;

}

/*!

    If a QAccessibleInterface implementation exists for the given \a object,

    this function returns a pointer to the implementation; otherwise it

    returns 0.

    The function calls all installed factory functions (from most

    recently installed to least recently installed) until one is found

    that provides an interface for the class of \a object. If no

    factory can provide an accessibility implementation for the class

    the function loads installed accessibility plugins, and tests if

    any of the plugins can provide the implementation.

    If no implementation for the object's class is available, the

    function tries to find an implementation for the object's parent

    class, using the above strategy.

    \warning The caller is responsible for deleting the returned

    interface after use.

*/

QAccessibleInterface *QAccessible::queryAccessibleInterface(QObject *object)

{

    accessibility_active = true;

    QAccessibleInterface *iface = 0;

    if (!object)

        return 0;

    QEvent e(QEvent::AccessibilityPrepare);

    QApplication::sendEvent(object, &e);

    const QMetaObject *mo = object->metaObject();

    while (mo) {

        const QLatin1String cn(mo->className());