src/quick/items/qquickaccessibleattached.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 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 QtDeclarative module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qquickaccessibleattached_p.h"
  43
  44 #ifndef QT_NO_ACCESSIBILITY
  45
  46 #include "private/qquickitem_p.h"
  47
  48 QT_BEGIN_NAMESPACE
  49
  50 /*!
  51     \qmlclass Accessible QQuickAccessibleAttached
  52     \inqmlmodule QtQuick 2
  53     \ingroup qml-basic-interaction-elements
  54     \brief Attached property to enable accessibility of QML items.
  55
  56     Items the user interacts with or that give information to the user
  57     need to expose their information in a semantic way.
  58     Then assistive tools can make use of that information to enable
  59     users to interact with the application in various ways.
  60
  61     This enables Qt Quick applications to be used with screen-readers for example.
  62
  63     The most important properties to set are \l name and \l role.
  64
  65     \sa Accessibility
  66 */
  67
  68 /*!
  69     \qmlproperty string QtQuick2::Accessible::name
  70
  71     This property sets an accessible name.
  72     For a button for example, this should have a binding to its text.
  73     In general this property should be set to a simple and concise
  74     but human readable name. Do not include the type of control
  75     you want to represent but just the name.
  76 */
  77
  78 /*!
  79     \qmlproperty string QtQuick2::Accessible::description
  80
  81     This property sets an accessible description.
  82     Similar to the name it describes the item. The description
  83     can be a little more verbose and tell what the item does,
  84     for example the functionallity of the button it describes.
  85 */
  86
  87 /*!
  88     \qmlproperty enumeration QtQuick2::Accessible::role
  89
  90     This flags sets the semantic type of the widget.
  91     A button for example would have "Button" as type.
  92     The value must be one of \l QAccessible::Role .
  93     Example:
  94     \qml
  95     Item {
  96         id: myButton
  97         Text {
  98             id: label
  99             // ...
 100         }
 101         Accessible.name: label.text
 102         Accessible.role: Accessible.Button
 103     }
 104     \endqml
 105
 106     Some roles have special semantics.
 107     In order to implement check boxes for example a "checked" property is expected.
 108
 109     \table
 110     \header
 111         \o \bold {Role}
 112         \o \bold {Expected property}
 113         \o
 114
 115     \row
 116        \o CheckBox
 117        \o checked
 118        \o The check state of the check box.
 119     \row
 120        \o RadioButton
 121        \o checked
 122        \o The selected state of the radio button.
 123     \row
 124        \o Button
 125        \o checkable
 126        \o Whether the button is checkable.
 127     \row
 128        \o Button
 129        \o checked
 130        \o Whether the button is checked (only if checkable is true).
 131
 132     \endtable
 133
 134 */
 135
 136 QQuickAccessibleAttached::QQuickAccessibleAttached(QObject *parent)
 137     : QObject(parent)
 138 {
 139     Q_ASSERT(parent);
 140     QQuickItem *item = qobject_cast<QQuickItem*>(parent);
 141     if (!item)
 142         return;
 143
 144     // Enable accessibility for items with accessible content. This also
 145     // enables accessibility for the ancestors of souch items.
 146     item->d_func()->setAccessibleFlagAndListener();
 147     QAccessible::updateAccessibility(item, 0, QAccessible::ObjectCreated);
 148 }
 149
 150 QQuickAccessibleAttached::~QQuickAccessibleAttached()
 151 {
 152 }
 153
 154 QQuickAccessibleAttached *QQuickAccessibleAttached::qmlAttachedProperties(QObject *obj)
 155 {
 156     return new QQuickAccessibleAttached(obj);
 157 }
 158
 159 QT_END_NAMESPACE
 160
 161 #endif