Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \group accessibility
++ \brief Functions ensuring communication between accessible applications and accessibility tools.
++ \title Accessibility Classes
++ */
++
++ /*!
++ \page accessible.html
++ \title Accessibility
++ \brief How to make your applications accessible to those with disabilities.
++ \ingroup explanations-accessibility
++
++ \nextpage Accessibility for QWidget Applications
++
++ \section1 Introduction
++
++ Accessibility in software development aims to make software available to people of
++ all abilities. This includes people with
++ \list
++ \li impaired vision
++ \li motor difficulties
++ \li cognitive impairments or learning disabilities
++ \li deafness or impaired hearing
++ \endlist
++
++ Qt aims to support you in writing accessible software. Let's have a look at common
++ themes in this context and how Qt can help you in making your software accessible.
++
++ \section1 Scalable UI
++
++ Allow your application’s user interface to work in different sizes,
++ resolutions, and form factors. Also, allow the user to customize fonts
++ and font sizes.
++
++ Qt supports you by providing a sophisticated layout system that dynamically scales your user
++ interface. Qt widgets and controls, by default, also use fonts and font sizes configured
++ in the operating system.
++
++ \section1 Keyboard Navigation
++
++ Do not rely solely on a computer mouse or touch as input but also allow navigation
++ by a keyboard. Define keyboard shortcuts for often used functionality.
++
++ Qt enables keyboard focus and navigation for Qt Widgets and Qt Quick and makes
++ it easy to configure global or local keyboard shortcuts.
++ \l{Qt Virtual Keyboard} allows you to show an on-screen keyboard.
++
++ \section1 Colors & Color Contrast
++
++ Provide enough contrast in your UI and consider the most common
++ cases of color blindness. Support different color schemes in your application,
++ or respect colors and themes as configured in the operating system.
++ Do not depend on colors only to provide information.
++
++ Qt widgets and controls do adhere to the system color palette by default.
++ For embedded software, \l{Styling Qt Quick Controls}{styles} allow you
++ to create high-contrast themes.
++
++ \section1 Sound & Speech
++
++ In addition to allowing visual interaction with your application, consider sound
++ notifications or speech input and output. Do not exclusively rely on sound
++ notifications though.
++
++ \l{Qt Multimedia} allows you to play sounds, and \l{Qt TextToSpeech} allows you to read out
++ texts with a synthesized voice.
++
++ \section1 Assistive Tools
++
++ Allow your application to be used via assistive tools like screen readers and braille
++ displays.
++
++ Qt does use platform-specific APIs to expose the semantic
++ structure of your GUI to such tools. The ready-made widgets and controls also provide
++ enough metadata to be usable, and custom widgets and controls can expose and enhance
++ this data, too. See \l{Accessibility for QWidget Applications} and
++ \l{Accessibility for Qt Quick Applications} for more details.
++ */
++
++
++ /*!
++ \page accessible-qwidget.html
++ \title Accessibility for QWidget Applications
++ \brief How to make your applications accessible to those with disabilities.
++ \previouspage Accessibility
++ \nextpage Accessibility for Qt Quick Applications
++
++ \section1 Introduction
++
++ We will focus on the Qt accessibility interface \l {QAccessibleInterface}
++ and how to make applications accessible.
++
++ \section2 Accessibility in QWidget based applications
++
++ When we communicate with the assistive technologies, we need to
++ describe Qt's user interface in a way that they can understand. Qt
++ applications use QAccessibleInterface to expose information about the
++ individual UI elements. Currently, Qt provides support for its widgets
++ and widget parts, e.g., slider handles, but the interface could
++ also be implemented for any QObject if necessary. QAccessible
++ contains enums that describe the UI. We will examine the enums
++ in the course of this document.
++
++ The structure of the UI is represented as a tree of
++ QAccessibleInterface subclasses. This is often a mirror of the
++ hierarchy of QWidgets that make up the UI of the application.
++
++ Servers notify clients through \l{QAccessible::}{updateAccessibility()}
++ about changes in objects by sending events, and the clients
++ register to receive the events. The available events are defined
++ by the QAccessible::Event enum. The clients may then query for
++ the object that generated the event through
++ \l QAccessible::queryAccessibleInterface().
++
++ The members and enums in QAccessible are used to describe
++ accessible objects:
++
++ \list
++ \li \l{QAccessible::}{Role}: Describes the role the object
++ fills in the user interface, e.g., if it is a
++ window, a text edit, or a cell in a table.
++ \li \l{QAccessible::}{Relation}: Describes the relationship
++ between objects in the object hierarchy.
++ \li \l{QAccessible::}{State}: The objects can be in a number
++ of different states. Examples of states are whether
++ the object is disabled, if it has focus,
++ or if it provides a pop-up menu.
++ \endlist
++
++ The clients also have some possibilities to get the content of
++ objects, e.g., a button's text; the object provides strings
++ defined by the QAccessible::Text enum, that give information
++ about content.
++
++
++ \section2 The Accessible Object Tree
++
++ As mentioned, a tree structure is built from the accessible
++ objects of an application. By navigating through the tree, the
++ clients can access all elements in the UI. Object relations give
++ clients information about the UI. For instance, a slider handle is
++ a child of the slider to which it belongs. QAccessible::Relation
++ describes the various relationships the clients can ask objects
++ for.
++
++ Note that there are no direct mapping between the Qt QObject tree
++ and the accessible object tree. For instance, scroll bar handles
++ are accessible objects but are not widgets or objects in Qt.
++
++ AT-Clients have access to the accessibility object tree through
++ the root object in the tree, which is the QApplication. They can
++ navigate the tree with the QAccessibleInterface::parent(), QAccessibleInterface::childCount()
++ and QAccessibleInterface::child() functions.
++
++ Qt provides accessible interfaces for its widgets and for Qt Quick Controls.
++ Interfaces for any QObject subclass can be requested through
++ QAccessible::queryInterface(). A default implementation is
++ provided if a more specialized interface is not defined. An
++ AT-Client cannot acquire an interface for accessible objects that
++ do not have an equivalent QObject, e.g., scroll bar handles, but
++ they appear as normal objects through interfaces of parent
++ accessible objects, e.g., you can query their relationships with
++ QAccessibleInterface::relations().
++
++ To illustrate, we present an image of an accessible object tree.
++ Beneath the tree is a table with examples of object relationships.
++
++ \image accessibleobjecttree.png
++ {Tree diagram showing accessible object hierarchy with QApplication
++ as root and QSlider with PageLeft, Position, and PageRight children}
++
++ The labels in top-down order are: the QAccessibleInterface class
++ name, the widget for which an interface is provided, and the
++ \l{QAccessible::}{Role} of the object. The Position, PageLeft and
++ PageRight correspond to the slider handle, the slider groove left
++ and the slider groove right, respectively. These accessible objects
++ do not have an equivalent QObject.
++
++ \table 40%
++ \header
++ \li Source Object
++ \li Target Object
++ \li Relation
++ \row
++ \li Slider
++ \li Indicator
++ \li Controller
++ \row
++ \li Indicator
++ \li Slider
++ \li Controlled
++ \row
++ \li Slider
++ \li Application
++ \li Ancestor
++ \row
++ \li Application
++ \li Slider
++ \li Child
++ \row
++ \li PushButton
++ \li Indicator
++ \li Sibling
++ \endtable
++
++ \section2 The Static QAccessible Functions
++
++ The accessibility is managed by QAccessible's static functions,
++ which we will examine shortly. They produce QAccessible
++ interfaces, build the object tree, and initiate the connection
++ with MSAA or the other platform specific technologies. If you are
++ only interested in learning how to make your application
++ accessible, you can safely skip over this section to
++ \l{Implementing Accessibility}.
++
++ The communication between clients and the server is initiated when
++ \l{QAccessible::}{setRootObject()} is called. This is done when
++ the QApplication instance is instantiated and you should not have
++ to do this yourself.
++
++ When a QObject calls \l{QAccessible::}{updateAccessibility()},
++ clients that are listening to events are notified of the
++ change. The function is used to post events to the assistive
++ technology, and accessible \l{QAccessible::Event}{events} are
++ posted by \l{QAccessible::}{updateAccessibility()}.
++
++ \l{QAccessible::}{queryAccessibleInterface()} returns accessible
++ interfaces for \l{QObject}s. All widgets in Qt provide interfaces;
++ if you need interfaces to control the behavior of other \l{QObject}
++ subclasses, you must implement the interfaces yourself, although
++ the QAccessibleObject convenience class implements parts of the
++ functionality for you.
++
++ The factory that produces accessibility interfaces for QObjects is
++ a function of type QAccessible::InterfaceFactory. It is possible
++ to have several factories installed. The last factory installed
++ will be the first to be asked for interfaces.
++ \l{QAccessible::}{queryAccessibleInterface()} uses the factories
++ to create interfaces for \l{QObject}s. Normally, you need not be
++ concerned about factories because you can implement plugins that
++ produce interfaces. We will give examples of both approaches
++ later.
++
++ \section1 Implementing Accessibility
++
++ To provide accessibility support for a widget or other user
++ interface element, you need to implement the QAccessibleInterface
++ and distribute it in a QAccessiblePlugin. It is also possible to
++ compile the interface into the application and provide a
++ QAccessible::InterfaceFactory for it. The factory can be used if
++ you link statically or do not want the added complexity of
++ plugins. This can be an advantage if you, for instance, are
++ delivering a 3-rd party library.
++
++ All widgets and other user interface elements should have
++ interfaces and plugins. If you want your application to support
++ accessibility, you will need to consider the following:
++
++ \list
++ \li Qt already implements accessibility for its own widgets.
++ We therefore recommend that you use Qt widgets where possible.
++ \li A QAccessibleInterface needs to be implemented for each element
++ that you want to make available to accessibility clients.
++ \li You need to send accessibility events from the custom
++ user interface elements that you implement.
++ \endlist
++
++ In general, it is recommended that you are somewhat familiar with
++ MSAA, which Qt's accessibility support originally was built for.
++ You should also study the enum values of QAccessible, which
++ describe the roles, actions, relationships, and events that you
++ need to consider.
++
++ Note that you can examine how Qt's widgets implement their
++ accessibility. One major problem with the MSAA standard is that
++ interfaces are often implemented in an inconsistent way. This
++ makes life difficult for clients and often leads to guesswork on
++ object functionality.
++
++ It is possible to implement interfaces by inheriting
++ QAccessibleInterface and implementing its pure virtual functions.
++ In practice, however, it is usually preferable to inherit
++ QAccessibleObject or QAccessibleWidget, which implement part of
++ the functionality for you. In the next section, we will see an
++ example of implementing accessibility for a widget by inheriting
++ the QAccessibleWidget class.
++
++ \section2 The QAccessibleObject and QAccessibleWidget Convenience Classes
++
++ When implementing an accessibility interface for widgets, one would
++ as a rule inherit QAccessibleWidget, which is a convenience class
++ for widgets. Another available convenience class, which is
++ inherited by QAccessibleWidget, is the QAccessibleObject, which
++ implements part of the interface for QObjects.
++
++ The QAccessibleWidget provides the following functionality:
++
++ \list
++ \li It handles the navigation of the tree and
++ hit testing of the objects.
++ \li It handles events, roles, and actions that are common for all
++ \l{QWidget}s.
++ \li It handles action and methods that can be performed on
++ all widgets.
++ \li It calculates bounding rectangles with
++ \l{QAccessibleInterface::}{rect()}.
++ \li It gives \l{QAccessibleInterface::}{text()} strings that are
++ appropriate for a generic widget.
++ \li It sets the \l{QAccessible::State}{states} that
++ are common for all widgets.
++ \endlist
++
++ \section2 QAccessibleWidget Example
++
++ Instead of creating a custom widget and implementing an interface
++ for it, we will show how accessibility is implemented for one of
++ Qt's standard widgets: QSlider. The accessible interface,
++ QAccessibleSlider, inherits from QAccessibleAbstractSlider, which
++ in turn inherits QAccessibleWidget. You do not need to examine the
++ QAccessibleAbstractSlider class to read this section. If you want
++ to take a look, the code for all of Qt's accessible interfaces are
++ found in qtbase/src/widgets/accessible. Here is the
++ QAccessibleSlider's constructor:
++
++ \snippet snippets/accessibilityslidersnippet.cpp 0
++
++ The slider is a complex control that functions as a
++ \l{QAccessible::}{Controller} for its accessible children.
++ This relationship must be known by the interface (for
++ \l{QAccessibleInterface::}{parent()}, \l{QAccessibleInterface::}{child()} and
++ \l{QAccessibleInterface::}{relations()}). This can be done
++ using a controlling signal, which is a mechanism provided by
++ QAccessibleWidget. We do this in the constructor:
++
++ The choice of signal shown is not important; the same principles
++ apply to all signals that are declared in this way. Note that we
++ use QLatin1String to ensure that the signal name is correctly
++ specified.
++
++ When an accessible object is changed in a way that users need
++ to know about, it notifies clients of the change by sending them
++ an event via the accessible interface. This is how QSlider calls
++ \l{QAccessible::}{updateAccessibility()} to indicate that
++ its value has changed:
++
++ \snippet snippets/qabstractsliderisnippet.cpp 0
++ \dots
++ \snippet snippets/qabstractsliderisnippet.cpp 1
++ \dots
++ \snippet snippets/qabstractsliderisnippet.cpp 2
++
++ Note that the call is made after the value of the slider has
++ changed because clients may query the new value immediately after
++ receiving the event.
++
++ The interface must be able to calculate bounding rectangles of
++ itself and any children that do not provide an interface of their
++ own. The \c QAccessibleSlider has three such children identified by
++ the private enum, \c SliderElements, which has the following values:
++ \c PageLeft (the rectangle on the left hand side of the slider
++ handle), \c PageRight (the rectangle on the right hand side of the
++ handle), and \c Position (the slider handle). Here is the
++ implementation of \l{QAccessibleInterface::}{rect()}:
++
++ \snippet snippets/accessibilityslidersnippet.cpp 1
++ \dots
++ \snippet snippets/accessibilityslidersnippet.cpp 2
++ \dots
++
++ The first part of the function, which we have omitted, uses the
++ current \l{QStyle}{style} to calculate the slider handle's
++ bounding rectangle; it is stored in \c srect. Notice that child 0,
++ covered in the default case in the above code, is the slider itself,
++ so we can simply return the QSlider bounding rectangle obtained
++ from the superclass, which is effectively the value obtained from
++ QAccessibleWidget::rect().
++
++ \snippet snippets/accessibilityslidersnippet.cpp 3
++
++ Before the rectangle is returned it must be mapped to screen
++ coordinates.
++
++ The QAccessibleSlider must reimplement
++ QAccessibleInterface::childCount() since it manages children
++ without interfaces.
++
++ The \l{QAccessibleInterface::}{text()} function returns the
++ QAccessible::Text strings for the slider:
++
++ \snippet snippets/accessibilityslidersnippet.cpp 4
++
++ The \c slider() function returns a pointer to the interface's
++ QSlider. Some values are left for the superclass's implementation.
++ Not all values are appropriate for all accessible objects, as you
++ can see for QAccessible::Value case. You should just return an
++ empty string for those values where no relevant text can be
++ provided.
++
++ The implementation of the \l{QAccessibleInterface::}{role()}
++ function is straightforward:
++
++ \snippet snippets/accessibilityslidersnippet.cpp 5
++
++ The role function should be reimplemented by all objects and
++ describes the role of themselves and the children that do not
++ provide accessible interfaces of their own.
++
++ Next, the accessible interface needs to return the
++ \l{QAccessible::State}{states} that the slider can be in. We look
++ at parts of the \c state() implementation to show how just a few
++ of the states are handled:
++
++ \snippet snippets/accessibilityslidersnippet.cpp 6
++ \dots
++ \snippet snippets/accessibilityslidersnippet.cpp 7
++
++ The superclass implementation of
++ \l{QAccessibleInterface::}{state()}, uses the
++ QAccessibleInterface::state() implementation. We simply need to
++ disable the buttons if the slider is at its minimum or maximum.
++
++ We have now exposed the information we have about the slider to
++ the clients. For the clients to be able to alter the slider---for
++ example, to change its value---we must provide information about
++ the actions that can be performed and perform them upon request.
++ We discuss this in the next section.
++
++ \section2 Handling Action Requests from Clients
++
++ Applications can expose actions, which can be invoked by the
++ client.
++ In order to support actions in an object, inherit the
++ \l {QAccessibleActionInterface}.
++
++ Interactive elements should expose functionality triggered
++ by mouse interaction, for example.
++ A button should, for example, implement a click action.
++
++ Setting the focus is another action that should be implemented
++ for widgets that accept receive the focus.
++
++ You need to re-implement \l{QAccessibleActionInterface::}{actionNames()}
++ to return a list of all actions that the object supports.
++ This list should not be localized.
++
++ There are two functions that give information about the actions
++ that must return localized strings:
++ \l{QAccessibleActionInterface::}{localizedActionName()} and
++ \l{QAccessibleActionInterface::}{localizedActionDescription()}.
++ These functions can be used by the client to present the actions to the user.
++ In general, the name should be concise and only consist of a single word, such as "press".
++
++ There is a list of standard action names and localizations available
++ that should be used when the action fits. This makes it easier for
++ clients to understand the semantics, and Qt will try to expose them
++ correctly on the different platforms.
++
++ Of course the action also needs a way to be triggered.
++ \l{QAccessibleActionInterface::}{doAction()} should
++ invoke the action as advertised by name and description.
++
++ To see examples on how to implement actions and methods, you
++ could examine the implementations for Qt's standard widgets such as
++ QAccessiblePushButton.
++
++ \section2 Implementing Accessible Plugins
++
++ In this section we will explain the procedure of implementing
++ accessible plugins for your interfaces. A plugin is a class stored
++ in a shared library that can be loaded at run-time. It is
++ convenient to distribute interfaces as plugins since they will only
++ be loaded when required.
++
++ Creating an accessible plugin is achieved by inheriting QAccessiblePlugin,
++ defining the supported class names in the plugin's JSON description and
++ reimplementing \l{QAccessiblePlugin::}{create()} from QAccessiblePlugin.
++ The \c .pro file must be altered to use the
++ plugin template, and the library containing the plugin must be
++ placed on a path where Qt searches for accessible plugins.
++
++ We will go through the implementation of \c SliderPlugin, which is
++ an accessible plugin that produces the QAccessibleSlider interface
++ from the \l{QAccessibleWidget Example}. We start with the \c key()
++ function:
++
++ \snippet snippets/accessibilitypluginsnippet.cpp 0
++
++ We simply need to return the class name of the single interface
++ our plugin can create an accessible interface for. A plugin
++ can support any number of classes; just add more class names
++ to the string list. We move on to the \c create() function:
++
++ \snippet snippets/accessibilitypluginsnippet.cpp 1
++
++ We check whether the interface requested is for QSlider; if it is,
++ we create and return an interface for it. Note that \c object will
++ always be an instance of \c classname. You must return 0 if you do
++ not support the class. \l{QAccessible::}{updateAccessibility()}
++ checks with the available accessibility plugins until it finds one
++ that does not return 0.
++
++ Finally, you need to include macros in the cpp file:
++
++ \snippet snippets/accessibilitypluginsnippet.cpp 2
++
++ The Q_PLUGIN_METADATA macro exports the plugin in the \c
++ SliderPlugin class into the \c acc_sliderplugin library. The first
++ argument is the plugins IID and the second is an optional json file
++ which holds metadata information for the plugin. For more
++ information on plugins, you can consult the plugins \l{How to
++ Create Qt Plugins}{overview document}.
++
++ It does not matter if you need the plugin to be statically or
++ dynamically linked with the application.
++
++ \section2 Implementing Interface Factories
++
++ If you do not want to provide plugins for your accessibility
++ interfaces, you can use an interface factory
++ (QAccessible::InterfaceFactory), which is the recommended way to
++ provide accessible interfaces in a statically-linked application.
++
++ A factory is a function pointer for a function that takes the same
++ parameters as \l{QAccessiblePlugin}'s
++ \l{QAccessiblePlugin::}{create()} - a QString and a QObject. It
++ also works the same way. You install the factory with the
++ \l{QAccessible::}{installFactory()} function. We give an example
++ of how to create a factory for the \c QAccessibleSlider interface:
++
++ \snippet snippets/accessibilityfactorysnippet.cpp 0
++ \dots
++ \snippet snippets/accessibilityfactorysnippet.cpp 1
++
++ \omit
++
++ \section1 Implementing Bridges for Other Assistive Technologies
++
++ An accessibility bridge provides the means for an assistive
++ technology to talk to Qt. On Windows and Mac, the built-in bridges
++ will be used. On UNIX, however, there are no built-in standard
++ assistive technology, and it might therefore be necessary to
++ implement an accessible bridge.
++
++ A bridge is implemented by inheriting QAccessibleBridge for the
++ technology to support. The class defines the interface that Qt
++ needs an assistive technology to support:
++
++ \list
++ \li A root object. This is the root in the accessible
++ object tree and is of type QAccessibleInterface.
++ \li Receive events from accessible objects.
++ \endlist
++
++ The root object is set with the
++ \l{QAccessibleBridge::}{setRootObject()}. In the case of Qt, this
++ will always be an interface for the QApplication instance of the
++ application.
++
++ Event notification is sent through
++ \l{QAccessibleBridge::}{notifyAccessibilityUpdate()}. This
++ function is called by \l{QAccessible::}{updateAccessibility()}. Even
++ though the bridge needs only to implement these two functions, it
++ must be able to communicate the entire QAccessibleInterface to the
++ underlying technology. How this is achieved is, naturally, up to
++ the individual bridge and none of Qt's concern.
++
++ As with accessible interfaces, you distribute accessible bridges
++ in plugins. Accessible bridge plugins are subclasses of the
++ QAccessibleBridgePlugin class; the class defines the functions
++ \l{QAccessibleBridgePlugin::}{create()} and
++ \l{QAccessibleBridgePlugin::}{keys()}, which must me
++ reimplemented. If Qt finds a built-in bridge to use, it will
++ ignore any available plugins.
++
++ \endomit
++
++ \section1 Related Classes
++
++ \annotatedlist accessibility
++ */
++
++ /*!
++ \group accessible-qtquick.html
++ \noautolist
++ \title Accessibility for Qt Quick Applications
++ \brief How to make your applications accessible to those with disabilities.
++ \startpage Accessibility
++ \previouspage Accessibility for QWidget Applications
++
++ \section1 Introduction
++
++ This page explains how to add accessibility metadata to Qt Quick
++ applications. Qt Quick applications and many of its QML types already have
++ built-in accessibility features. For example, the \l{Button Controls} have
++ keyboard accessibility, which makes it possible to tab between the controls
++ and activate them using the Return or Enter key. So, by using existing
++ controls, you are already off to a good start in making your Qt Quick
++ application accessible. In some cases, however, you may need to clarify the
++ job of a QML item.
++
++ Similar to making
++ {web applications accessible}, you assign properties to UI elements, in this
++ case, to QML items. These properties expose metadata to accessibility
++ tools, which, together with carefully chosen high-contrast color themes and
++ other visual cues, aid the user in interacting with your Qt Quick
++ application.
++
++ In general, accessibility tools are interested in three different categories
++ of metadata:
++
++ \list
++ \li \e{Properties}: The accessibility client reads metadata about
++ accessible objects. In some cases, the accessibility client can also
++ modify these properties, such as text in a line edit.
++ \li \e{Actions}: The accessibility client invokes actions, such as pressing a button.
++ \li \e{Relationships and Navigation}: The accessibility client traverses
++ from one accessible object to another, using the relationships between
++ objects.
++ \endlist
++
++ For Qt Quick applications, the most important type to be aware of is the
++ \l{Accessible} QML type, which adds accessibility metadata to QML items.
++
++ \section1 Adding Accessibility Metadata to QML Items
++
++ To add accessibility metadata to QML items, either to existing types
++ provided by Qt or to custom types defined in C++, use the
++ \l Accessible QML type. The most important properties of the
++ \l Accessible QML type are \l {Accessible::}{name},
++ \l {Accessible::}{description}, and \l {Accessible::}{role}.
++
++ Here's an example of adding accessibility metadata to a \c Text type,
++ which, in this case, represents a mathematical equation:
++
++ \qml
++ Text {
++ id: myMathEquation
++ text: "y = 8x - 9"
++ font.family: "Helvetica"
++
++ Accessible.role: Accessible.Equation
++ Accessible.name: myMathEquation.text
++ Accessible.description: qsTr("Linear equation")
++ Accessible.onPressAction: {
++ // Highlight the x variable
++ ...
++ }
++ }
++ \endqml
++
++ The \l{Accessible::}{role} is set to \c Equation to indicate what the
++ \c Text type represents. \l {Accessible::}{name} is the most important
++ property, which is bound to the text of the button. To provide extra
++ information about a QML item, use the \l {Accessible::}{description}
++ property. The signal handler, \l{Accessible.pressAction}, which can be
++ invoked by accessibility tools to trigger the button, needs to have the
++ same effect as tapping or clicking the text.
++
++ Whereas textual content is inherently accessible, multimedia content is not.
++ So it's important to provide necessary accessibility metadata to
++ multimedia content such as images, videos, and audio. Here's an example of
++ providing accessibility metadata to an image, which represents a pie chart:
++
++ \qml
++ Image {
++ source: "pie-chart-683.png"
++ Accessible.role: Accessible.Chart
++ Accessible.name: qsTr("Pie chart")
++ Accessible.description: qsTr("Pie chart that shows the distribution
++ of sales from three store locations: Durban representing 60 percent,
++ Johannesburg 20 percent, and Cape Town 20 percent")
++ Accessible.onPressAction: {
++ // Expand the image
++ ...
++ }
++ }
++ \endqml
++
++ For more information, see \l Accessible for the list of properties you can
++ add to QML items.
++
++ \section1 Related Classes and Interfaces
++
++ \list
++ \li \l QAccessible
++ \li \l QAccessibleInterface
++ \endlist
++ */