Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qquickaccessibleattached_p.h
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3// Qt-Security score:significant reason:default
4
5#ifndef QQUICKACCESSIBLEATTACHED_H
6#define QQUICKACCESSIBLEATTACHED_H
7
8//
9// W A R N I N G
10// -------------
11//
12// This file is not part of the Qt API. It exists purely as an
13// implementation detail. This header file may change from version to
14// version without notice, or even be removed.
15//
16// We mean it.
17//
18
19#include <QtQuick/qquickitem.h>
20
21#include <QtCore/qobject.h>
22#include <QtCore/qstring.h>
23
24#if QT_CONFIG(accessibility)
25
26#include <QtGui/qaccessible.h>
27#include <private/qtquickglobal_p.h>
28#include <QtQml/qqml.h>
29
30QT_BEGIN_NAMESPACE
31
32
33#define STATE_PROPERTY(P)
34 Q_PROPERTY(bool P READ P WRITE set_ ## P NOTIFY P ## Changed FINAL)
35 bool P() const { return m_proxying && !m_stateExplicitlySet.P ? m_proxying->P() : m_state.P ; }
36 void set_ ## P(bool arg)
37 {
38 if (m_proxying)
39 m_proxying->set_##P(arg);
40 m_stateExplicitlySet.P = true;
41 if (m_state.P == arg)
42 return;
43 m_state.P = arg;
44 Q_EMIT P ## Changed(arg);
45 QAccessible::State changedState;
46 changedState.P = true;
47 QAccessibleStateChangeEvent ev(parent(), changedState);
48 QAccessible::updateAccessibility(&ev);
49 }
50 Q_SIGNAL void P ## Changed(bool arg);
51
52class Q_QUICK_EXPORT QQuickAccessibleAttached : public QObject
53{
54 Q_OBJECT
55 Q_PROPERTY(QAccessible::Role role READ role WRITE setRole NOTIFY roleChanged FINAL)
56 Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged FINAL)
57 Q_PROPERTY(QString description READ description WRITE setDescription NOTIFY descriptionChanged FINAL)
58 Q_PROPERTY(QString id READ id WRITE setId NOTIFY idChanged FINAL)
59 Q_PROPERTY(bool ignored READ ignored WRITE setIgnored NOTIFY ignoredChanged FINAL)
60 Q_PROPERTY(QQuickItem *labelledBy READ labelledBy WRITE setLabelledBy NOTIFY labelledByChanged FINAL)
61 Q_PROPERTY(QQuickItem *labelFor READ labelFor WRITE setLabelFor NOTIFY labelForChanged FINAL)
62
63 QML_NAMED_ELEMENT(Accessible)
64 QML_ADDED_IN_VERSION(2, 0)
65 QML_UNCREATABLE("Accessible is only available via attached properties.")
66 QML_ATTACHED(QQuickAccessibleAttached)
67 QML_EXTENDED_NAMESPACE(QAccessible)
68
69public:
70 STATE_PROPERTY(checkable)
71 STATE_PROPERTY(checked)
72 STATE_PROPERTY(editable)
73 STATE_PROPERTY(focusable)
74 STATE_PROPERTY(focused)
75 STATE_PROPERTY(multiLine)
76 STATE_PROPERTY(readOnly)
77 STATE_PROPERTY(selected)
78 STATE_PROPERTY(selectable)
79 STATE_PROPERTY(pressed)
80 STATE_PROPERTY(checkStateMixed)
81 STATE_PROPERTY(defaultButton)
82 STATE_PROPERTY(passwordEdit)
83 STATE_PROPERTY(selectableText)
84 STATE_PROPERTY(searchEdit)
85
86 QQuickAccessibleAttached(QObject *parent);
87 ~QQuickAccessibleAttached();
88
89 QAccessible::Role role() const { return m_role; }
90 void setRole(QAccessible::Role role);
91 QString name() const {
92 if (m_state.passwordEdit)
93 return QString();
94 if (!m_nameExplicitlySet && m_proxying && m_proxying->wasNameExplicitlySet())
95 return m_proxying->name();
96 return m_name;
97 }
98
99 bool wasNameExplicitlySet() const;
100 void setName(const QString &name) {
101 m_nameExplicitlySet = true;
102 if (name != m_name) {
103 m_name = name;
104 Q_EMIT nameChanged();
105 QAccessibleEvent ev(parent(), QAccessible::NameChanged);
106 QAccessible::updateAccessibility(&ev);
107 }
108 }
109 void setNameImplicitly(const QString &name);
110
111 QString description() const {
112 return !m_descriptionExplicitlySet && m_proxying ? m_proxying->description() : m_description;
113 }
114 void setDescription(const QString &description)
115 {
116 if (!m_descriptionExplicitlySet && m_proxying) {
117 disconnect(m_proxying, &QQuickAccessibleAttached::descriptionChanged, this, &QQuickAccessibleAttached::descriptionChanged);
118 }
119 m_descriptionExplicitlySet = true;
120 if (m_description != description) {
121 m_description = description;
122 Q_EMIT descriptionChanged();
123 QAccessibleEvent ev(parent(), QAccessible::DescriptionChanged);
124 QAccessible::updateAccessibility(&ev);
125 }
126 }
127 void setDescriptionImplicitly(const QString &desc);
128
129 QString id() const { return m_id; }
130 void setId(const QString &id)
131 {
132 if (m_id != id) {
133 m_id = id;
134 Q_EMIT idChanged();
135 QAccessibleEvent ev(parent(), QAccessible::IdentifierChanged);
136 QAccessible::updateAccessibility(&ev);
137 }
138 }
139
140 QQuickItem *labelledBy() const
141 {
142 return findRelation(QAccessible::Labelled);
143 }
144
145 void setLabelledBy(QQuickItem *labelledBy)
146 {
147 setLabelledByInternal(labelledBy);
148
149 QQuickAccessibleAttached *label = qobject_cast<QQuickAccessibleAttached *>(
150 qmlAttachedPropertiesObject<QQuickAccessibleAttached>(labelledBy));
151
152 label->setLabelForInternal(qobject_cast<QQuickItem *>(parent()));
153 }
154 void setLabelledByInternal(QQuickItem *labelledBy)
155 {
156 m_relations.append({ labelledBy, QAccessible::Labelled });
157 Q_EMIT labelledByChanged();
158 }
159
160 QQuickItem *labelFor() const
161 {
162 return findRelation(QAccessible::Label);
163 }
164
165 void setLabelFor(QQuickItem *labelFor)
166 {
167 setLabelForInternal(labelFor);
168
169 QQuickAccessibleAttached *labelled = qobject_cast<QQuickAccessibleAttached *>(
170 qmlAttachedPropertiesObject<QQuickAccessibleAttached>(labelFor));
171 labelled->setLabelledBy(qobject_cast<QQuickItem *>(parent()));
172 }
173
174 void setLabelForInternal(QQuickItem *labelFor)
175 {
176 m_relations.append({ labelFor, QAccessible::Label });
177 Q_EMIT labelForChanged();
178 }
179
180 // Factory function
181 static QQuickAccessibleAttached *qmlAttachedProperties(QObject *obj);
182
183 static QQuickAccessibleAttached *attachedProperties(const QObject *obj)
184 {
185 return qobject_cast<QQuickAccessibleAttached*>(qmlAttachedPropertiesObject<QQuickAccessibleAttached>(obj, false));
186 }
187
188 // Property getter
189 static QVariant property(const QObject *object, const char *propertyName)
190 {
191 if (QObject *attachedObject = QQuickAccessibleAttached::attachedProperties(object))
192 return attachedObject->property(propertyName);
193 return QVariant();
194 }
195
196 static bool setProperty(QObject *object, const char *propertyName, const QVariant &value)
197 {
198 QObject *obj = qmlAttachedPropertiesObject<QQuickAccessibleAttached>(object, true);
199 if (!obj) {
200 qWarning("cannot set property Accessible.%s of QObject %s", propertyName, object->metaObject()->className());
201 return false;
202 }
203 return obj->setProperty(propertyName, value);
204 }
205
206 static QObject *findAccessible(QObject *object, QAccessible::Role role = QAccessible::NoRole)
207 {
208 while (object) {
209 QQuickAccessibleAttached *att = QQuickAccessibleAttached::attachedProperties(object);
210 if (att && (role == QAccessible::NoRole || att->role() == role)) {
211 break;
212 }
213 if (auto action = object->property("action").value<QObject *>(); action) {
214 QQuickAccessibleAttached *att = QQuickAccessibleAttached::attachedProperties(action);
215 if (att && (role == QAccessible::NoRole || att->role() == role)) {
216 object = action;
217 break;
218 }
219 }
220 object = object->parent();
221 }
222 return object;
223 }
224
225 QAccessible::State state() const { return m_state; }
226 bool ignored() const;
227 bool doAction(const QString &actionName);
228 void availableActions(QStringList *actions) const;
229
230 Q_REVISION(6, 2) Q_INVOKABLE static QString stripHtml(const QString &html);
231 void setProxying(QQuickAccessibleAttached *proxying);
232
233 Q_REVISION(6, 8) Q_INVOKABLE void announce(const QString &message, QAccessible::AnnouncementPoliteness politeness = QAccessible::AnnouncementPoliteness::Polite);
234
235public Q_SLOTS:
236 void valueChanged() {
237 QAccessibleValueChangeEvent ev(parent(), parent()->property("value"));
238 QAccessible::updateAccessibility(&ev);
239 }
240 void cursorPositionChanged() {
241 QAccessibleTextCursorEvent ev(parent(), parent()->property("cursorPosition").toInt());
242 QAccessible::updateAccessibility(&ev);
243 }
244
245 void setIgnored(bool ignored);
246
247Q_SIGNALS:
248 void roleChanged();
249 void nameChanged();
250 void descriptionChanged();
251 void idChanged();
252 void ignoredChanged();
253 void labelledByChanged();
254 void labelForChanged();
255 void pressAction();
256 void toggleAction();
257 void increaseAction();
258 void decreaseAction();
259 void scrollUpAction();
260 void scrollDownAction();
261 void scrollLeftAction();
262 void scrollRightAction();
263 void previousPageAction();
264 void nextPageAction();
265
266private:
267 QQuickItem *findRelation(QAccessible::Relation relation) const;
268
269 QAccessible::Role m_role;
270 QAccessible::State m_state;
271 QAccessible::State m_stateExplicitlySet;
272 QString m_name;
273 bool m_nameExplicitlySet = false;
274 QString m_description;
275 bool m_descriptionExplicitlySet = false;
276 QQuickAccessibleAttached* m_proxying = nullptr;
277 QString m_id;
278 QList<std::pair<QQuickItem *, QAccessible::Relation>> m_relations;
279
280 static QMetaMethod sigPress;
281 static QMetaMethod sigToggle;
282 static QMetaMethod sigIncrease;
283 static QMetaMethod sigDecrease;
284 static QMetaMethod sigScrollUp;
285 static QMetaMethod sigScrollDown;
286 static QMetaMethod sigScrollLeft;
287 static QMetaMethod sigScrollRight;
288 static QMetaMethod sigPreviousPage;
289 static QMetaMethod sigNextPage;
290
291public:
292 using QObject::property;
293};
294
295
296QT_END_NAMESPACE
297
298#endif // accessibility
299
300#endif