/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

\page qtfeedback-index.html
\title Qt Feedback

\brief An API enabling a client to provide tactile and audio feedback to user actions.

\ingroup mobility


The C++ Feedback API enables a client to control and provide tactile and audio feedback
to the user. The feedback is in response to user actions. For example, touching an
onscreen button. Control of the feedback involves control of the vibration of
the device, when a vibrator is used, or the piezo feedback from the screen.


\tableofcontents



\section1 Overview

The Feedback API allows application developers to implement feedback and programmatic vibration
in their applications.  The API provides abstractions for various types of
feedback, and allows custom implementations of these types of feedback.

The QFeedbackEffect class provides a simple interface to allow developers to
start, stop or pause the playback of an effect.  It is an abstract class which
is implemented by QFeedbackHapticsEffect and QFeedbackFileEffect.  In addition,
it allows the instantaneous playback of feedback effects which match the system
theme.

A QFeedbackHapticsEffect is a custom effect which allows a program to play a
haptic effect on an actuator.  Such an effect might have a duration, intensity,
and envelope of playback (including attack time and intensity, and fade time
and intensity), as well as a period if it is a periodic (repeating) effect.

A QFeedbackFileEffect is a haptic tune or audio file saved in a file which may be played
back.  These effects must be created by third-party applications, and a plugin
which supports the specific file format must be installed.  In particular, note that
audio effects are generally limited to simple formats, to reduce latency.  You can
check what formats are supported by the system by calling QFeedbackFileEffect::supportedMimeTypes().

For the vast majority of use cases, the QFeedbackEffect, QFeedbackHapticsEffect
and QFeedbackFileEffect classes are the only classes which developers will use
in their programs.  There are some special cases, however, where they may wish
to implement their own feedback plugin.  The QtFeedback API allows
third party developers to implement QFeedbackInterface in a plugin which may be
loaded by the plugin loading mechanism to play feedback effects.

Note that in any application, only the highest priority plugin for each of the
three types of feedback will be used to provide the feedback effects, except
for file feedback plugins (where only the highest priority plugin for each
supported mime-type is used).  The interface classes which must be implemented
by a plugin to provide effects to clients are:
\list
    \li \l{QFeedbackHapticsInterface} for \l{QFeedbackHapticsEffect}
    \li \l{QFeedbackFileInterface} for \l{QFeedbackFileEffect}
    \li \l{QFeedbackThemeInterface} for the built-in theme effects (\l{QFeedbackEffect::ThemeEffect}).
\endlist

Generally, the device platform will provide an implementation of each of the
three different interfaces, which will be the default plugins used for the
various \l {QFeedbackEffect}s.

\section2 Platform Issues

\note Platforms might have user settings that enable/disables the vibration.

\section1 Using Effects

\section2 Theme Effects

The most common use of the API is to play system theme effects for user
interface interaction notifications, for example, button clicks. These
system theme effects can be played instantaneously, but cannot be paused or
stopped.  They are played via the static QFeedbackEffect::playThemeEffect()
function:
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Play the system theme button click effect

There are many different theme effects defined, to cover a variety of
interactions and notifications, to allow an application to maintain greater
consistency with the platform user experience.
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Play the system theme bounce effect

\section2 Custom Effects

The next most common use of the API is to define a custom effect which can be
used to notify the user of application-specific events or to increase the
immersiveness of an application.  A custom effect may be either periodic or
non-periodic.

The following diagram shows the graph of intensity over time of a non-periodic
effect which was started at time \c t and ended at time \c q, with an
\l{QFeedbackHapticsEffect::intensity()}{intensity} of \c{I}, an
\l{QFeedbackHapticsEffect::attackIntensity()}{attack intensity} of \c{AI}, a
\l{QFeedbackHapticsEffect::fadeIntensity()}{fade intensity} of \c{FI}, an
\l{QFeedbackHapticsEffect::attackTime()}{attack time} of \c{AT}, and a
\l{QFeedbackHapticsEffect::fadeTime()}{fade time} of \c{FT}, with a total
\l{QFeedbackEffect::duration()}{duration} of \c{Duration} milliseconds:

\image non-periodic-effect.png

The following diagram shows the graph of intensity over time of a periodic
effect which was started at time \c t and ended at time \c q, with an
\l{QFeedbackHapticsEffect::intensity()}{intensity} of \c{I}, an
\l{QFeedbackHapticsEffect::attackIntensity()}{attack intensity} of \c{AI}, a
\l{QFeedbackHapticsEffect::fadeIntensity()}{fade intensity} of \c{FI}, an
\l{QFeedbackHapticsEffect::attackTime()}{attack time} of \c{AT}, and a
\l{QFeedbackHapticsEffect::fadeTime()}{fade time} of \c{FT}, with a
\l{QFeedbackHapticsEffect::period()}{period} of \c{Period} milliseconds and a total
\l{QFeedbackEffect::duration()}{duration} of \c{Duration} milliseconds:

\image periodic-effect.png

A custom haptic effect may be defined in the following manner:
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Define a custom haptic effect
\note No periodicity was defined for the effect, although that can be done
by calling QFeedbackHapticsEffect::setPeriod() if required.

Once the effect has been defined, it may be played via the API offered in the
QFeedbackEffect base class:
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Start playing a custom haptic effect

Custom haptic effects are stateful, and so they may be paused:
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Pause a custom haptic effect

Or stopped:
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Stop playing a custom haptic effect

Certain operations cannot be performed on an effect if it is in a certain
state.  The current state of the effect may be queried via the base-class API:
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Query the state of a custom haptic effect

All custom effects are played using a specific
\l{QFeedbackActuator}{device actuator}.  By default, the effect is played via
the actuator which the current haptic effect provider plugin considers to be
the system default actuator, and so most application developers will not need
to change which actuator is used.  In some cases, however, it may be desirable
to set which actuator the effect is played on; doing so requires prior
knowledge of either the name or the id of the actuator on which the developer
wishes the effect to be played:
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Set the actuator which should play the custom effect

Finally, there is software available which allows "haptic tunes" to be saved to
file, for later playback.  If the haptic file effect provider plugin on the
system understands that file format, the file can be played on device:
\snippet doc/src/snippets/qtfeedbackdocsample/qtfeedbackdocsample.cpp Play a haptic effect from a file
In addition, small audio effects can be played as feedback.

If you wish to see a simple example application which demonstrates some of
the above code in use, please see the \l{hapticsquare}{Haptic Square} example
application.

\section1 Main Classes
\list
    \li \l{QFeedbackEffect}
    \li \l{QFeedbackHapticsEffect}
    \li \l{QFeedbackFileEffect}
    \li \l{QFeedbackActuator}
    \li \l{QFeedbackInterface}
\endlist

\section1 Examples
\list
    \li \l{hapticsquare}{Haptic Square}
    \li \l{hapticsplayer}{Haptics Player}
\endlist


*/

/*!
    \page feedback-api.html

    \title Qt Feedback C++ Classes

    \brief An API enabling a client to provide tactile and audio feedback to user actions.

    \section1 Overview

    The C++ Feedback API enables a client to control and provide tactile and audio feedback
    to the user. The feedback is in response to user actions. For example, touching an
    onscreen button. Control of the feedback involves control of the vibration of
    the device, when a vibrator is used, or the piezo feedback from the screen.

    \section1 Feedback C++ Classes

    \annotatedlist feedback
*/