qaccessible.cpp

奇趣公司比较新的qt/emd版本

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

#ifndef QT_NO_LIBRARY
Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,
    (QAccessibleFactoryInterface_iid, QCoreApplication::libraryPaths(), 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());
        for (int i = qAccessibleFactories()->count(); i > 0; --i) {
            InterfaceFactory factory = qAccessibleFactories()->at(i - 1);
            iface = factory(cn, object);
            if (iface)
                return iface;
        }
#ifndef QT_NO_LIBRARY
        QAccessibleFactoryInterface *factory = qobject_cast<QAccessibleFactoryInterface*>(loader()->instance(cn));
        if (factory) {
            iface = factory->create(cn, object);
            if (iface)
                return iface;
        }
#endif
        mo = mo->superClass();
    }

    QWidget *widget = qobject_cast<QWidget*>(object);
    if (widget)
        return new QAccessibleWidget(widget);
    else if (object == qApp)
        return new QAccessibleApplication();

    return 0;
}

/*!
    Returns true if an accessibility implementation has been requested
    during the runtime of the application; otherwise returns false.

    Use this function to prevent potentially expensive notifications via
    updateAccessibility().
*/
bool QAccessible::isActive()
{
    return accessibility_active;
}

/*!
  \fn void QAccessible::setRootObject(QObject *object)

  Sets the root accessible object of this application to \a object.
  All other accessible objects in the application can be reached by the
  client using object navigation.

  You should never need to call this function. Qt sets the QApplication
  object as the root object immediately before the event loop is entered
  in QApplication::exec().

  Use QAccessible::installRootObjectHandler() to redirect the function
  call to a customized handler function.

  \sa queryAccessibleInterface()
*/

/*!
  \fn void QAccessible::updateAccessibility(QObject *object, int child, Event reason)

  Notifies accessibility clients about a change in \a object's
  accessibility information.

  \a reason specifies the cause of the change, for example,
  \c ValueChange when the position of a slider has been changed. \a
  child is the (1-based) index of the child element that has changed.
  When \a child is 0, the object itself has changed.
  
  Call this function whenever the state of your accessible object or
  one of its sub-elements has been changed either programmatically
  (e.g. by calling QLabel::setText()) or by user interaction.
  
  If there are no accessibility tools listening to this event, the
  performance penalty for calling this function is small, but if determining
  the parameters of the call is expensive you can test isActive() to
  avoid unnecessary computations.
*/


/*!
    \class QAccessibleInterface
    \brief The QAccessibleInterface class defines an interface that exposes information
    about accessible objects.

    \ingroup accessibility

    Accessibility tools (also called AT Clients), such as screen readers
    or braille displays, require high-level information about
    accessible objects in an application. Accessible objects provide
    specialized input and output methods, making it possible for users
    to use accessibility tools with enabled applications (AT Servers).

    Every element that the user needs to interact with or react to is
    an accessible object, and should provide this information. These
    are mainly visual objects, such as widgets and widget elements, but
    can also be content, such as sounds.

    The AT client uses three basic concepts to acquire information
    about any accessible object in an application:
    \list
    \i \e Properties The client can read information about
    accessible objects. In some cases the client can also modify these
    properties; such as text in a line edit.
    \i \e Actions The client can invoke actions like pressing a button
    or .
    \i \e{Relationships and Navigation} The client can traverse from one
    accessible object to another, using the relationships between objects.
    \endlist

    The QAccessibleInterface defines the API for these three concepts.

    \section1 Relationships and Navigation

    The functions childCount() and indexOfChild() return the number of
    children of an accessible object and the index a child object has
    in its parent. The childAt() function returns the index of a child
    at a given position.

    The relationTo() function provides information about how two
    different objects relate to each other, and navigate() allows
    traversing from one object to another object with a given
    relationship.

    \section1 Properties

    The central property of an accessible objects is what role() it
    has. Different objects can have the same role, e.g. both the "Add
    line" element in a scroll bar and the \c OK button in a dialog have
    the same role, "button". The role implies what kind of
    interaction the user can perform with the user interface element.

    An object's state() property is a combination of different state
    flags and can describe both how the object's state differs from a
    "normal" state, e.g. it might be unavailable, and also how it
    behaves, e.g. it might be selectable.

    The text() property provides textual information about the object.
    An object usually has a name, but can provide extended information
    such as a description, help text, or information about any
    keyboard accelerators it provides. Some objects allow changing the
    text() property through the setText() function, but this
    information is in most cases read-only.

    The rect() property provides information about the geometry of an
    accessible object. This information is usually only available for
    visual objects.

    \section1 Actions and Selection

    To enable the user to interact with an accessible object the
    object must expose information about the actions that it can
    perform. userActionCount() returns the number of actions supported by
    an accessible object, and actionText() returns textual information
    about those actions. doAction() invokes an action.

    Objects that support selections can define actions to change the selection.

    \section2 Objects and children

    A QAccessibleInterface provides information about the accessible
    object, and can also provide information for the children of that
    object if those children don't provide a QAccessibleInterface
    implementation themselves. This is practical if the object has
    many similar children (e.g. items in a list view), or if the
    children are an integral part of the object itself, for example, the
    different sections in a scroll bar.

    If an accessible object provides information about its children
    through one QAccessibleInterface, the children are referenced
    using indexes. The index is 1-based for the children, i.e. 0
    refers to the object itself, 1 to the first child, 2 to the second
    child, and so on.

    All functions in QAccessibleInterface that take a child index
    relate to the object itself if the index is 0, or to the child
    specified. If a child provides its own interface implementation
    (which can be retrieved through navigation) asking the parent for
    information about that child will usually not succeed.

    \sa QAccessible
*/

/*!
    \fn bool QAccessibleInterface::isValid() const

    Returns true if all the data necessary to use this interface
    implementation is valid (e.g. all pointers are non-null);
    otherwise returns false.

    \sa object()
*/

/*!
    \fn QObject *QAccessibleInterface::object() const

    Returns a pointer to the QObject this interface implementation provides
    information for.

    \sa isValid()