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
4#include "qquickaccessibleattached_p.h"
5
6#if QT_CONFIG(accessibility)
7
8#include <QtQml/qqmlinfo.h>
9
10#include "private/qquickitem_p.h"
11
12QT_BEGIN_NAMESPACE
13
14/*!
15 \qmltype Accessible
16 \nativetype QQuickAccessibleAttached
17 \brief Enables accessibility of QML items.
18
19 \inqmlmodule QtQuick
20 \ingroup qtquick-visual-utility
21 \ingroup accessibility
22
23 This class is part of the \l {Accessibility for Qt Quick Applications}.
24
25 Items the user interacts with or that give information to the user
26 need to expose their information to the accessibility framework.
27 Then assistive tools can make use of that information to enable
28 users to interact with the application in various ways.
29 This enables Qt Quick applications to be used with screen-readers for example.
30
31 The most important properties are \l name, \l description and \l role.
32
33 Example implementation of a simple button:
34 \qml
35 Rectangle {
36 id: myButton
37 Text {
38 id: label
39 text: "next"
40 }
41 Accessible.role: Accessible.Button
42 Accessible.name: label.text
43 Accessible.description: "shows the next page"
44 Accessible.onPressAction: {
45 // do a button click
46 }
47 }
48 \endqml
49 The \l role is set to \c Button to indicate the type of control.
50 \l {Accessible::}{name} is the most important information and bound to the text on the button.
51 The name is a short and consise description of the control and should reflect the visual label.
52 In this case it is not clear what the button does with the name only, so \l description contains
53 an explanation.
54 There is also a signal handler \l {Accessible::pressAction}{Accessible.pressAction} which can be invoked by assistive tools to trigger
55 the button. This signal handler needs to have the same effect as tapping or clicking the button would have.
56
57 \sa Accessibility
58*/
59
60/*!
61 \qmlproperty string QtQuick::Accessible::name
62
63 This property sets an accessible name.
64 For a button for example, this should have a binding to its text.
65 In general this property should be set to a simple and concise
66 but human readable name. Do not include the type of control
67 you want to represent but just the name.
68*/
69
70/*!
71 \qmlproperty string QtQuick::Accessible::description
72
73 This property sets an accessible description.
74 Similar to the name it describes the item. The description
75 can be a little more verbose and tell what the item does,
76 for example the functionality of the button it describes.
77*/
78
79/*!
80 \qmlproperty enumeration QtQuick::Accessible::role
81
82 This flags sets the semantic type of the widget.
83 A button for example would have "Button" as type.
84 The value must be one of \l QAccessible::Role.
85
86 Some roles have special semantics.
87 In order to implement check boxes for example a "checked" property is expected.
88
89 \table
90 \header
91 \li \b {Role}
92 \li \b {Properties and signals}
93 \li \b {Explanation}
94 \row
95 \li All interactive elements
96 \li \l focusable and \l focused
97 \li All elements that the user can interact with should have focusable set to \c true and
98 set \c focus to \c true when they have the focus. This is important even for applications
99 that run on touch-only devices since screen readers often implement a virtual focus that
100 can be moved from item to item.
101 \row
102 \li Button, CheckBox, RadioButton
103 \li \l {Accessible::pressAction}{Accessible.pressAction}
104 \li A button should have a signal handler with the name \c onPressAction.
105 This signal may be emitted by an assistive tool such as a screen-reader.
106 The implementation needs to behave the same as a mouse click or tap on the button.
107 \row
108 \li CheckBox, RadioButton
109 \li \l checkable, \l checked, \l {Accessible::toggleAction}{Accessible.toggleAction}
110
111 \li The check state of the check box. Updated on Press, Check and Uncheck actions.
112 \row
113 \li Slider, SpinBox, Dial, ScrollBar
114 \li \c value, \c minimumValue, \c maximumValue, \c stepSize
115 \li These properties reflect the state and possible values for the elements.
116 \row
117 \li Slider, SpinBox, Dial, ScrollBar
118 \li \l {Accessible::increaseAction}{Accessible.increaseAction}, \l {Accessible::decreaseAction}{Accessible.decreaseAction}
119 \li Actions to increase and decrease the value of the element.
120 \endtable
121*/
122
123/*!
124 \qmlproperty string QtQuick::Accessible::id
125
126 This property sets an identifier for the object.
127 It can be used to provide stable identifiers to UI tests.
128 By default, the identifier is set to the ID of the QML object.
129 If the ID is not set the default of \l QAccessible::Identifier is used.
130*/
131
132/*! \qmlproperty bool QtQuick::Accessible::focusable
133 \brief This property holds whether this item is focusable.
134
135 By default, this property is \c false except for items where the role is one of
136 \c CheckBox, \c RadioButton, \c Button, \c MenuItem, \c PageTab, \c EditableText, \c SpinBox, \c ComboBox,
137 \c Terminal or \c ScrollBar.
138 \sa focused
139*/
140/*! \qmlproperty bool QtQuick::Accessible::focused
141 \brief This property holds whether this item currently has the active focus.
142
143 By default, this property is \c false, but it will return \c true for items that
144 have \l QQuickItem::hasActiveFocus() returning \c true.
145 \sa focusable
146*/
147/*! \qmlproperty bool QtQuick::Accessible::checkable
148 \brief This property holds whether this item is checkable (like a check box or some buttons).
149
150 By default this property is \c false.
151 \sa checked
152*/
153/*! \qmlproperty bool QtQuick::Accessible::checked
154 \brief This property holds whether this item is currently checked.
155
156 By default this property is \c false.
157 \sa checkable
158*/
159/*! \qmlproperty bool QtQuick::Accessible::editable
160 \brief This property holds whether this item has editable text.
161
162 By default this property is \c false.
163*/
164/*! \qmlproperty bool QtQuick::Accessible::searchEdit
165 \brief This property holds whether this item is input for a search query.
166 This property will only affect editable text.
167
168 By default this property is \c false.
169*/
170/*! \qmlproperty bool QtQuick::Accessible::ignored
171 \brief This property holds whether this item should be ignored by the accessibility framework.
172
173 Sometimes an item is part of a group of items that should be treated as one. For example two labels might be
174 visually placed next to each other, but separate items. For accessibility purposes they should be treated as one
175 and thus they are represented by a third invisible item with the right geometry.
176
177 For example a speed display adds "m/s" as a smaller label:
178 \qml
179 Row {
180 Label {
181 id: speedLabel
182 text: "Speed: 5"
183 Accessible.ignored: true
184 }
185 Label {
186 text: qsTr("m/s")
187 Accessible.ignored: true
188 }
189 Accessible.role: Accessible.StaticText
190 Accessible.name: speedLabel.text + " meters per second"
191 }
192 \endqml
193
194 \since 5.4
195 By default this property is \c false.
196*/
197/*! \qmlproperty bool QtQuick::Accessible::multiLine
198 \brief This property holds whether this item has multiple text lines.
199
200 By default this property is \c false.
201*/
202/*! \qmlproperty bool QtQuick::Accessible::readOnly
203 \brief This property indicates that a text field is read only.
204
205 It is relevant when the role is \l QAccessible::EditableText and set to be read-only.
206 By default this property is \c false.
207*/
208/*! \qmlproperty bool QtQuick::Accessible::selected
209 \brief This property holds whether this item is selected.
210
211 By default this property is \c false.
212 \sa selectable
213*/
214/*! \qmlproperty bool QtQuick::Accessible::selectable
215 \brief This property holds whether this item can be selected.
216
217 By default this property is \c false.
218 \sa selected
219*/
220/*! \qmlproperty bool QtQuick::Accessible::pressed
221 \brief This property holds whether this item is pressed (for example a button during a mouse click).
222
223 By default this property is \c false.
224*/
225/*! \qmlproperty bool QtQuick::Accessible::checkStateMixed
226 \brief This property holds whether this item is in the partially checked state.
227
228 By default this property is \c false.
229 \sa checked, checkable
230*/
231/*! \qmlproperty bool QtQuick::Accessible::defaultButton
232 \brief This property holds whether this item is the default button of a dialog.
233
234 By default this property is \c false.
235*/
236/*! \qmlproperty bool QtQuick::Accessible::passwordEdit
237 \brief This property holds whether this item is a password text edit.
238
239 By default this property is \c false.
240*/
241/*! \qmlproperty bool QtQuick::Accessible::selectableText
242 \brief This property holds whether this item contains selectable text.
243
244 By default this property is \c false.
245*/
246/*! \qmlproperty Item QtQuick::Accessible::labelledBy
247 \brief This property holds the item that is used as a label for this item.
248
249 Setting this property automatically sets up the labelFor relation of the other object.
250
251 By default this property is \c undefined.
252
253 \since 6.10
254 */
255/*! \qmlproperty Item QtQuick::Accessible::labelFor
256 \brief This property holds the item that this item is a label for.
257
258 Setting this property automatically sets up the labelledBy relation of the other object.
259
260 By default this property is \c undefined.
261
262 \since 6.10
263 */
264
265/*!
266 \qmlsignal QtQuick::Accessible::pressAction()
267
268 This signal is emitted when a press action is received from an assistive tool such as a screen-reader.
269*/
270/*!
271 \qmlsignal QtQuick::Accessible::toggleAction()
272
273 This signal is emitted when a toggle action is received from an assistive tool such as a screen-reader.
274*/
275/*!
276 \qmlsignal QtQuick::Accessible::increaseAction()
277
278 This signal is emitted when a increase action is received from an assistive tool such as a screen-reader.
279*/
280/*!
281 \qmlsignal QtQuick::Accessible::decreaseAction()
282
283 This signal is emitted when a decrease action is received from an assistive tool such as a screen-reader.
284*/
285/*!
286 \qmlsignal QtQuick::Accessible::scrollUpAction()
287
288 This signal is emitted when a scroll up action is received from an assistive tool such as a screen-reader.
289*/
290/*!
291 \qmlsignal QtQuick::Accessible::scrollDownAction()
292
293 This signal is emitted when a scroll down action is received from an assistive tool such as a screen-reader.
294*/
295/*!
296 \qmlsignal QtQuick::Accessible::scrollLeftAction()
297
298 This signal is emitted when a scroll left action is received from an assistive tool such as a screen-reader.
299*/
300/*!
301 \qmlsignal QtQuick::Accessible::scrollRightAction()
302
303 This signal is emitted when a scroll right action is received from an assistive tool such as a screen-reader.
304*/
305/*!
306 \qmlsignal QtQuick::Accessible::previousPageAction()
307
308 This signal is emitted when a previous page action is received from an assistive tool such as a screen-reader.
309*/
310/*!
311 \qmlsignal QtQuick::Accessible::nextPageAction()
312
313 This signal is emitted when a next page action is received from an assistive tool such as a screen-reader.
314*/
315
316QMetaMethod QQuickAccessibleAttached::sigPress;
317QMetaMethod QQuickAccessibleAttached::sigToggle;
318QMetaMethod QQuickAccessibleAttached::sigIncrease;
319QMetaMethod QQuickAccessibleAttached::sigDecrease;
320QMetaMethod QQuickAccessibleAttached::sigScrollUp;
321QMetaMethod QQuickAccessibleAttached::sigScrollDown;
322QMetaMethod QQuickAccessibleAttached::sigScrollLeft;
323QMetaMethod QQuickAccessibleAttached::sigScrollRight;
324QMetaMethod QQuickAccessibleAttached::sigPreviousPage;
325QMetaMethod QQuickAccessibleAttached::sigNextPage;
326
327QQuickAccessibleAttached::QQuickAccessibleAttached(QObject *parent)
328 : QObject(parent), m_role(QAccessible::NoRole)
329{
330 Q_ASSERT(parent);
331 // Enable accessibility for items with accessible content. This also
332 // enables accessibility for the ancestors of such items.
333 auto item = qobject_cast<QQuickItem *>(o: parent);
334 if (item) {
335 item->d_func()->setAccessible();
336 } else {
337 const QLatin1StringView className(QQmlData::ensurePropertyCache(object: parent)->firstCppMetaObject()->className());
338 if (className != QLatin1StringView("QQuickAction")) {
339 qmlWarning(me: parent) << "Accessible attached property must be attached to an object deriving from Item or Action";
340 return;
341 }
342 }
343 QAccessibleEvent ev(parent, QAccessible::ObjectCreated);
344 QAccessible::updateAccessibility(event: &ev);
345
346 if (const QMetaObject *pmo = parent->metaObject()) {
347 auto connectPropertyChangeSignal = [parent, pmo, this](
348 const char *propertyName, const char *signalName, int slotIndex)
349 {
350 // basically does this:
351 // if the parent has the property \a propertyName with the associated \a signalName:
352 // connect(parent, signalName, this, slotIndex)
353
354 // Note that we explicitly want to only connect to standard property/signal naming
355 // convention: "value" & "valueChanged"
356 // (e.g. avoid a compound property with e.g. a signal notifier named "updated()")
357 int idxProperty = pmo->indexOfProperty(name: propertyName);
358 if (idxProperty != -1) {
359 const QMetaProperty property = pmo->property(index: idxProperty);
360 const QMetaMethod signal = property.notifySignal();
361 if (signal.name() == signalName)
362 QMetaObject::connect(sender: parent, signal_index: signal.methodIndex(), receiver: this, method_index: slotIndex);
363 }
364 return;
365 };
366 const QMetaObject &smo = staticMetaObject;
367
368 QAccessibleInterface *iface = ev.accessibleInterface();
369 if (iface && iface->valueInterface()) {
370 static const int valueChangedIndex = smo.indexOfSlot(slot: "valueChanged()");
371 connectPropertyChangeSignal("value", "valueChanged", valueChangedIndex);
372 }
373
374 if (iface && iface->textInterface()) {
375 static const int cursorPositionChangedIndex =
376 smo.indexOfSlot(slot: "cursorPositionChanged()");
377 connectPropertyChangeSignal("cursorPosition", "cursorPositionChanged",
378 cursorPositionChangedIndex);
379 }
380 }
381
382 if (!sigPress.isValid()) {
383 sigPress = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::pressAction);
384 sigToggle = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::toggleAction);
385 sigIncrease = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::increaseAction);
386 sigDecrease = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::decreaseAction);
387 sigScrollUp = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::scrollUpAction);
388 sigScrollDown = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::scrollDownAction);
389 sigScrollLeft = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::scrollLeftAction);
390 sigScrollRight = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::scrollRightAction);
391 sigPreviousPage = QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::previousPageAction);
392 sigNextPage= QMetaMethod::fromSignal(signal: &QQuickAccessibleAttached::nextPageAction);
393 }
394}
395
396QQuickAccessibleAttached::~QQuickAccessibleAttached()
397{
398}
399
400void QQuickAccessibleAttached::setRole(QAccessible::Role role)
401{
402 if (role != m_role) {
403 m_role = role;
404 Q_EMIT roleChanged();
405 // There is no way to signify role changes at the moment.
406 // QAccessible::updateAccessibility(parent(), 0, QAccessible::);
407
408 switch (role) {
409 case QAccessible::CheckBox:
410 case QAccessible::RadioButton:
411 if (!m_stateExplicitlySet.focusable)
412 m_state.focusable = true;
413 if (!m_stateExplicitlySet.checkable)
414 m_state.checkable = true;
415 break;
416 case QAccessible::Button:
417 case QAccessible::MenuItem:
418 case QAccessible::PageTab:
419 case QAccessible::SpinBox:
420 case QAccessible::ComboBox:
421 case QAccessible::Terminal:
422 case QAccessible::ScrollBar:
423 if (!m_stateExplicitlySet.focusable)
424 m_state.focusable = true;
425 break;
426 case QAccessible::EditableText:
427 if (!m_stateExplicitlySet.editable)
428 m_state.editable = true;
429 if (!m_stateExplicitlySet.focusable)
430 m_state.focusable = true;
431 break;
432 case QAccessible::StaticText:
433 if (!m_stateExplicitlySet.readOnly)
434 m_state.readOnly = true;
435 if (!m_stateExplicitlySet.focusable)
436 m_state.focusable = true;
437 break;
438 default:
439 break;
440 }
441 }
442}
443
444bool QQuickAccessibleAttached::wasNameExplicitlySet() const
445{
446 return m_nameExplicitlySet;
447}
448
449// Allows types to attach an accessible name to an item as a convenience,
450// so long as the user hasn't done so themselves.
451void QQuickAccessibleAttached::setNameImplicitly(const QString &name)
452{
453 setName(name);
454 m_nameExplicitlySet = false;
455}
456
457void QQuickAccessibleAttached::setDescriptionImplicitly(const QString &desc)
458{
459 if (m_descriptionExplicitlySet)
460 return;
461 setDescription(desc);
462 m_descriptionExplicitlySet = false;
463}
464
465QQuickAccessibleAttached *QQuickAccessibleAttached::qmlAttachedProperties(QObject *obj)
466{
467 return new QQuickAccessibleAttached(obj);
468}
469
470bool QQuickAccessibleAttached::ignored() const
471{
472 auto item = qobject_cast<QQuickItem *>(o: parent());
473 return item ? !item->d_func()->isAccessible : false;
474}
475
476void QQuickAccessibleAttached::setIgnored(bool ignored)
477{
478 auto item = qobject_cast<QQuickItem *>(o: parent());
479 if (item && this->ignored() != ignored) {
480 item->d_func()->isAccessible = !ignored;
481 QAccessibleEvent event(item,
482 ignored ? QAccessible::ObjectDestroyed : QAccessible::ObjectCreated);
483 QAccessible::updateAccessibility(event: &event);
484 emit ignoredChanged();
485 }
486}
487
488bool QQuickAccessibleAttached::doAction(const QString &actionName)
489{
490 QMetaMethod *sig = nullptr;
491 if (actionName == QAccessibleActionInterface::pressAction())
492 sig = &sigPress;
493 else if (actionName == QAccessibleActionInterface::toggleAction())
494 sig = &sigToggle;
495 else if (actionName == QAccessibleActionInterface::increaseAction())
496 sig = &sigIncrease;
497 else if (actionName == QAccessibleActionInterface::decreaseAction())
498 sig = &sigDecrease;
499 else if (actionName == QAccessibleActionInterface::scrollUpAction())
500 sig = &sigScrollUp;
501 else if (actionName == QAccessibleActionInterface::scrollDownAction())
502 sig = &sigScrollDown;
503 else if (actionName == QAccessibleActionInterface::scrollLeftAction())
504 sig = &sigScrollLeft;
505 else if (actionName == QAccessibleActionInterface::scrollRightAction())
506 sig = &sigScrollRight;
507 else if (actionName == QAccessibleActionInterface::previousPageAction())
508 sig = &sigPreviousPage;
509 else if (actionName == QAccessibleActionInterface::nextPageAction())
510 sig = &sigNextPage;
511 if (sig && isSignalConnected(signal: *sig)) {
512 bool ret = false;
513 if (m_proxying)
514 ret = sig->invoke(obj: m_proxying);
515 if (!ret)
516 ret = sig->invoke(obj: this);
517 return ret;
518 }
519 return false;
520}
521
522void QQuickAccessibleAttached::availableActions(QStringList *actions) const
523{
524 if (isSignalConnected(signal: sigPress))
525 actions->append(t: QAccessibleActionInterface::pressAction());
526 if (isSignalConnected(signal: sigToggle))
527 actions->append(t: QAccessibleActionInterface::toggleAction());
528 if (isSignalConnected(signal: sigIncrease))
529 actions->append(t: QAccessibleActionInterface::increaseAction());
530 if (isSignalConnected(signal: sigDecrease))
531 actions->append(t: QAccessibleActionInterface::decreaseAction());
532 if (isSignalConnected(signal: sigScrollUp))
533 actions->append(t: QAccessibleActionInterface::scrollUpAction());
534 if (isSignalConnected(signal: sigScrollDown))
535 actions->append(t: QAccessibleActionInterface::scrollDownAction());
536 if (isSignalConnected(signal: sigScrollLeft))
537 actions->append(t: QAccessibleActionInterface::scrollLeftAction());
538 if (isSignalConnected(signal: sigScrollRight))
539 actions->append(t: QAccessibleActionInterface::scrollRightAction());
540 if (isSignalConnected(signal: sigPreviousPage))
541 actions->append(t: QAccessibleActionInterface::previousPageAction());
542 if (isSignalConnected(signal: sigNextPage))
543 actions->append(t: QAccessibleActionInterface::nextPageAction());
544}
545
546QString QQuickAccessibleAttached::stripHtml(const QString &html)
547{
548#ifndef QT_NO_TEXTHTMLPARSER
549 QTextDocument doc;
550 doc.setHtml(html);
551 return doc.toPlainText();
552#else
553 return html;
554#endif
555}
556
557void QQuickAccessibleAttached::setProxying(QQuickAccessibleAttached *proxying)
558{
559 if (proxying == m_proxying)
560 return;
561
562 const QMetaObject &mo = staticMetaObject;
563 if (m_proxying) {
564 // We disconnect all signals from the proxy into this object
565 auto mo = m_proxying->metaObject();
566 auto propertyCache = QQmlData::ensurePropertyCache(object: m_proxying);
567 for (int signalIndex = propertyCache->signalOffset();
568 signalIndex < propertyCache->signalCount(); ++signalIndex) {
569 const QMetaMethod m = mo->method(index: propertyCache->signal(index: signalIndex)->coreIndex());
570 Q_ASSERT(m.methodType() == QMetaMethod::Signal);
571 if (m.methodType() != QMetaMethod::Signal)
572 continue;
573
574 disconnect(sender: m_proxying, signal: m, receiver: this, member: m);
575 }
576 }
577
578 m_proxying = proxying;
579
580 if (m_proxying) {
581 // We connect all signals from the proxy into this object
582 auto propertyCache = QQmlData::ensurePropertyCache(object: m_proxying);
583 auto mo = m_proxying->metaObject();
584 for (int signalIndex = propertyCache->signalOffset();
585 signalIndex < propertyCache->signalCount(); ++signalIndex) {
586 const QMetaMethod m = mo->method(index: propertyCache->signal(index: signalIndex)->coreIndex());
587 Q_ASSERT(m.methodType() == QMetaMethod::Signal);
588 connect(sender: proxying, signal: m, receiver: this, method: m);
589 }
590 }
591
592 // We check all properties
593 for (int prop = mo.propertyOffset(); prop < mo.propertyCount(); ++prop) {
594 const QMetaProperty p = mo.property(index: prop);
595 if (!p.hasNotifySignal()) {
596 continue;
597 }
598
599 const QMetaMethod signal = p.notifySignal();
600 if (signal.parameterCount() == 0)
601 signal.invoke(obj: this);
602 else
603 signal.invoke(obj: this, Q_ARG(bool, p.read(this).toBool()));
604 }
605}
606
607/*!
608 * \qmlmethod void QtQuick::Accessible::announce(string message, AnnouncementPoliteness politeness)
609 *
610 * \since 6.8
611 * Issues an announcement event with a \a message with politeness \a politeness.
612 *
613 * \sa QAccessibleAnnouncementEvent
614 */
615void QQuickAccessibleAttached::announce(const QString &message, QAccessible::AnnouncementPoliteness politeness)
616{
617 QAccessibleAnnouncementEvent event(parent(), message);
618 event.setPoliteness(politeness);
619 QAccessible::updateAccessibility(event: &event);
620}
621
622QQuickItem *QQuickAccessibleAttached::findRelation(QAccessible::Relation relation) const
623{
624 const auto it = std::find_if(first: m_relations.cbegin(), last: m_relations.cend(),
625 pred: [relation](const auto &rel) {
626 return rel.second == relation;
627 });
628
629 return it != m_relations.cend() ? it->first : nullptr;
630}
631
632QT_END_NAMESPACE
633
634#include "moc_qquickaccessibleattached_p.cpp"
635
636#endif
637

source code of qtdeclarative/src/quick/items/qquickaccessibleattached.cpp