/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

\page feedback.html
\title Feedback

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

\ingroup mobility

The 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.

This is part of the QtMobility Project.

\tableofcontents

\section1 Namespace

The QtMobility APIs are placed into the \i{QtMobility} namespace. This is done
to facilitate the future migration of QtMobility APIs into Qt. See the
\l {Quickstart guide} for an example on how the
namespace impacts on application development.

\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 QtMobility Feedback 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
    \o \l{QFeedbackHapticsInterface} for \l{QFeedbackHapticsEffect}
    \o \l{QFeedbackFileInterface} for \l{QFeedbackFileEffect}
    \o \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 On Symbian, vibration feature needs to be enabled in the user profile for the API to work.
\note On Maemo5, periodic vibration does not support attack or fade.

\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
    \o \l{QFeedbackEffect}
    \o \l{QFeedbackHapticsEffect}
    \o \l{QFeedbackFileEffect}
    \o \l{QFeedbackActuator}
    \o \l{QFeedbackInterface}
\endlist

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

\section1 QML Elements

For details on the QML support provided for the Feedback API see the documentation for the \l {Feedback QML Plugin}.



*/

