Change copyrights from Nokia to Digia
[qt:qtfeedback.git] / doc / src / examples / hapticsplayer.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia.  For licensing terms and
14 ** conditions see http://qt.digia.com/licensing.  For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \example hapticsplayer
30     \title Haptics Player
31
32     \tableofcontents
33
34     \section1 Overview
35
36     This example shows how to use various haptic effects in an application via
37     the \l{Feedback}{Qt Feedback API}.
38
39     It provides an example of how to use the QtMobility libraries to:
40     \list
41     \li play "system theme" haptic effects corresponding to certain predefined events
42     \li play a dynamic custom effect, single or repeating
43     \li play a custom effect which is stored in a file
44     \endlist
45
46     \section2 Use Case
47
48     This example is more feature complete than the \l{hapticsquare}{Haptic Square} example,
49     but is intended more as a way to test the haptics provider plugins which
50     are available on a system, than as an example for application developers.
51
52     It is useful for people who wish to learn how to use the API to create and
53     play custom effects dynamically, or to allow users of an application to
54     select which haptic effect to play when a particular event occurs.  It is also useful
55     to test how effects are implemented on specific devices.
56
57     It is a more complex example than the \l{hapticsquare}{Haptic Square} example, so it is
58     suggested that developers look at that example first.
59
60     \section2 Interface
61     The application is designed to work on desktop and mobile platforms with
62     minimal differences in code between the platforms.  The interface consists
63     of three tabs which allow the user to select and play different custom,
64     system theme, and file effects, respectively.  The custom effect tab also
65     allows the user to modify the custom effect dynamically, and see the effect
66     of attack and fade, intensity and duration, and periodicity, on the user
67     experience.
68
69     \section2 Known Issues
70     The example will not work correctly on platforms which do not have a
71     QFeedbackHapticInterface (haptic effect provider) plugin loaded.  On such
72     platforms, the example will do nothing.
73 */