Changes: Deprecated MFeedbackPlayer class

RevBy: Daniel d'Andrada
Details:
The goal is to allow hiding of MFeedbackPlayer class from the public API.
All necessary functionality regarding to input feedbacks should come from
class MFeedback. Please note the deprecation of MApplication::feedbackPlayer()
and MComponentData::feedbackPlayer() as well.

Updated unit test for MFeedback
 - Added test against MFeedback::play(const QString&)

Adapted implementation for MFeedbackPlayer deprecation

Updated input feedback documentation

13 files changed, 134 insertions, 48 deletions

diff --git a/doc/src/input_feedback.dox b/doc/src/input_feedback.dox
index cdd6ba93..6f49376b 100644
--- a/doc/src/input_feedback.dox
+++ b/doc/src/input_feedback.dox
@@ -13,7 +13,7 @@ The feedbacks are identified by name. For instance, if a user touches a button o
 - Vibra: Based on Immersion TouchSense®
 - Audio: Based on PulseAudio
 
-MFeedbackPlayer class provides an interface to send playback requests from MeeGo Touch level to the feedback daemon. In practice, when a feedback related Qt signal is emitted, it should be translated into a feedback name and sent to the feedback daemon via the feedback player. The MFeedbackPlayer only forwards the feedback name to the feedback daemon, it does not know anything about the source Qt signal which triggered that event and the feedback name is not validated at MeeGo Touch level. The feedback daemon receives the feedback name, validates it in the context of the current theme and the application name and plays the corresponding vibra/audio feedback if there is any. If multiple feedbacks (e.g audio and vibra) are available for the same name, they are played simultaneously.
+MFeedback class provides an interface to send playback requests from MeeGo Touch level to the feedback daemon. In practice, when a feedback related Qt signal is emitted, it should be translated into a feedback name and sent to the feedback daemon via MFeedback class. The MFeedback class only forwards the feedback name to the feedback daemon, it does not know anything about the source Qt signal which triggered that event and the feedback name is not validated at MeeGo Touch level. The feedback daemon receives the feedback name, validates it in the context of the current theme and the application name and plays the corresponding vibra/audio feedback if there is any. If multiple feedbacks (e.g audio and vibra) are available for the same name, they are played simultaneously.
 
 \subsection feedbacks_in_themes Feedbacks in themes
 
@@ -42,14 +42,14 @@ A css file is associated with an application to describe the style of the widget
 Let's see some real-life examples for the principles above. If a style is specific to every instance of a class then it should be written in the following form:
 
 \code
-MButton {
+MButtonStyle {
 }
 \endcode
 
 Object instances can be referred by their name. The style data of a button named "SendButton" (an instance of an MButton):
 
 \code
-MButton#SendButton {
+MButtonStyle#SendButton {
 }
 \endcode
 
@@ -63,24 +63,46 @@ If multiple instances of several classes (MButton, MTextEdit) are named with the
 Specifying a feedback "huge-feedback" for the "press" event of an MButton widget instance with the object name "SignInButton":
 
 \code
-MButton#SignInButton {
+MButtonStyle#SignInButton {
   press-feedback: huge-feedback;
 }
 \endcode
 
 As shown above, the styling rules are written between the curly brackets.
 
-\section mfeedbackplayer MFeedbackPlayer
+\section mfeedback MFeedback
+
+MFeedback class is a thin convenience class to make working with feedbacks very easy.
+
+\subsection mfeedback_instance Using an MFeedback instance to play a "press" feedback:
+
+\code
+MFeedback* feedback = new MFeedback("press");
+\endcode
+
+Play the input feedback by hand:
+
+\code
+feedback->play();
+\endcode
+
+Connect a signal to the feedback:
 
-MFeedbackPlayer class instance should not be explicitly created by an application since it is built-in in the MApplication class. To get the MFeedbackPlayer instance, a static function MApplication::feedbackPlayer() should be called:
+\code
+connect(button, SIGNAL(pressed()), feedback, SLOT(play()));
+\endcode
+
+\subsection mfeedback_staic Using static MFeedback::play(const QString&) to play a "press" feedback:
 
 \code
-MFeedbackPlayer* MApplication::feedbackPlayer();
+MFeedback::play("press");
 \endcode
 
-\subsection simple_demo MFeedbackPlayer simple demo application
+Behind the scenes the feedback event is forwarded to the feedback daemon and the audio/vibra feedback gets played as soon as possible.
 
-A minimalistic application, requesting a "press" feedback from the MFeedbackPlayer without any widgets:
+\subsection minimal_application Minimal application that plays "press" feedback without using any widgets
+
+The following application simply plays a feedback called "press".
 
 app.pro:
 
@@ -94,7 +116,7 @@ main.cpp:
 
 \code
 #include <MApplication>
-#include <MFeedbackPlayer>
+#include <MFeedback>
 
 int main(int argc, char* argv[])
 {
@@ -103,37 +125,15 @@ int main(int argc, char* argv[])
   // Process some initial events in the event queue
   app.processEvents();
   // Request the press feedback
-  MApplication::feedbackPlayer()->play("press");
+  MFeedback::play("press");
   // Be sure that the request is processed
   app.processEvents();
 }
 \endcode
 
-\section mfeedback MFeedback
-
-MFeedback class is a thin convenience class to make working with feedbacks very easy. An MFeedback instance that can play a "press" feedback:
-
-\code
-MFeedback* feedback = new MFeedback("press");
-\endcode
-
-Play the input feedback by hand:
-
-\code
-feedback->play();
-\endcode
-
-Connect a signal to the feedback:
-
-\code
-connect(button, SIGNAL(press()), feedback, SLOT(play()));
-\endcode
-
-Behind the scenes, MFeedbackPlayer forwards the feedback events to the feedback daemon and the audio/vibra feedback gets played as soon as possible.
-
-\subsection simplest_application Simplest application with feedbacks
+\subsection simple_application Simple application that uses MButton widget to play feedbacks
 
-The following demo application creates a window and places a button (MButton) there. The default press and release feedbacks are used automatically. Feedback named "press" is played when button is pressed and feedback named "release" is played when the button is released. These "press" and "release" feedback files are loaded from the current theme.
+The following application creates a window and places a button (MButton) in that window. The default press and release feedbacks are used automatically. Feedback named "press" is played when button is pressed and feedback named "release" is played when the button is released. These "press" and "release" feedback files are loaded from the current theme.
 
 app.pro:
 
@@ -174,7 +174,7 @@ int main(int argc, char* argv[])
 
 \subsection advanced_example Advanced example
 
-The following demo application creates a window and places a button in the window (ExampleButton). The default press and the release feedbacks for the button are ignored and instead the button emits a newPress signal when tapping on the button.  This signal is used to play a feedback named "press-on".
+The following application creates a window and places a button in the window (ExampleButton). The default press and the release feedbacks for the button are ignored and instead the button emits a newPress signal when tapping on the button.  This signal is used to play a feedback named "press-on".
 
 app.pro:
 
@@ -251,14 +251,14 @@ protected:
 };
 \endcode
 
-\section feedback_use_case1 Use case 1: Override a default feedback for an application
+\section feedback_use_case1 Styling use case 1: Override a default feedback for an application
 
 Let's say that an application's name is "app" and we want to change the "press" feedback to an application specific custom feedback regardless of the selected theme. To achieve this the following should be done:
 
 - The new feedback files should be placed in the base theme directory structure because every theme is derived from this theme. This leads to the fact that the custom feedback will be the same regardless of the selected theme. This is true because an application specific feedback always overrides the general theme specific feedback.
 - The base theme can be extended/overriden in the application specific part. Thus the correct place for the new files is at /usr/share/themes/base/meegotouch/app/feedbacks/press
 
-\section feedback_use_case2 Use case 2: Use an MButton widget and override the default feedback
+\section feedback_use_case2 Styling use case 2: Use an MButton widget and override the default feedback
 
 The application created in this section places a normal MButton named "NormalButton" in a window and the style sheet overrides the default "press" feedback of the press feedback into "release" feedback. The app.css file should be placed in the usr/share/themes/base/meegotouch/app/style directory.
 
diff --git a/doc/src/news.dox b/doc/src/news.dox
index 7280596a..d03c0ea9 100644
--- a/doc/src/news.dox
+++ b/doc/src/news.dox
@@ -1,5 +1,11 @@
 /*! \page news What's New in MeeGo Touch
 
+\section v02043 0.20.43
+
+\subsection Deprecated
+- MFeedbackPlayer, use class MFeedback instead.
+- MApplication::feedbackPlayer() and MComponentData::feedbackPlayer(), use class MFeedback instead.
+
 \section v02042 0.20.42
 
 \subsection New
diff --git a/plainqt/style/qtmaemo6style.cpp b/plainqt/style/qtmaemo6style.cpp
index 116ee2d0..51bfeb3e 100755
--- a/plainqt/style/qtmaemo6style.cpp
+++ b/plainqt/style/qtmaemo6style.cpp
@@ -87,7 +87,7 @@
 #include <mtexteditstyle.h>
 #include <mcontentitemstyle.h>
 #include <mapplicationmenustyle.h>
-#include <mfeedbackplayer.h>
+#include <mfeedback.h>
 //#include <mwidgetfadeinanimationstyle.h>
 //#include <mwidgetfadeoutanimationstyle.h>
 #include <mdeviceprofile.h>
@@ -2596,11 +2596,11 @@ const MFeedback * QtMaemo6Style::feedback(const QString& feedbackName, const QWi
         const MWidgetStyle *style = static_cast<const MWidgetStyle *>(
             QtMaemo6StylePrivate::mStyle(opt.state, meegoClassString, ""));
 
-        if ( feedbackName == MFeedbackPlayer::Press )
+        if ( feedbackName == MFeedback::Press )
             return &(style->pressFeedback());
-        if ( feedbackName == MFeedbackPlayer::Release )
+        if ( feedbackName == MFeedback::Release )
             return &(style->releaseFeedback());
-        if ( feedbackName == MFeedbackPlayer::Cancel )
+        if ( feedbackName == MFeedback::Cancel )
             return &(style->cancelFeedback());
     }
 
diff --git a/plainqt/style/qtmaemo6styleeventfilter.cpp b/plainqt/style/qtmaemo6styleeventfilter.cpp
index 311044ea..23ad721f 100644
--- a/plainqt/style/qtmaemo6styleeventfilter.cpp
+++ b/plainqt/style/qtmaemo6styleeventfilter.cpp
@@ -44,7 +44,7 @@
 #include <QDesktopWidget>
 
 #include <MComponentData>
-#include <mfeedbackplayer.h>
+#include <mfeedback.h>
 #include <mdeviceprofile.h>
 #include <MTheme>
 #include <mbuttonstyle.h>
@@ -168,7 +168,7 @@ bool QtMaemo6StyleEventFilter::eventFilter(QObject *obj, QEvent *event)
     case QEvent::MouseButtonPress: {
         // now send press feedback
         if(QtMaemo6Style* style = qobject_cast<QtMaemo6Style*>(widget->style())) {
-            const MFeedback *  feedback = style->feedback(MFeedbackPlayer::Press, widget);
+            const MFeedback *  feedback = style->feedback(MFeedback::Press, widget);
             if ( feedback ) feedback->play();
         }
 
@@ -185,7 +185,7 @@ bool QtMaemo6StyleEventFilter::eventFilter(QObject *obj, QEvent *event)
     case QEvent::MouseButtonRelease: {
         // now send release feedback
         if(QtMaemo6Style* style = qobject_cast<QtMaemo6Style*>(widget->style())) {
-            const MFeedback *  feedback = style->feedback(MFeedbackPlayer::Release, widget);
+            const MFeedback *  feedback = style->feedback(MFeedback::Release, widget);
             if ( feedback ) feedback->play();
         }
     }
diff --git a/src/corelib/core/mapplication.h b/src/corelib/core/mapplication.h
index 0d2554c5..216c648a 100644
--- a/src/corelib/core/mapplication.h
+++ b/src/corelib/core/mapplication.h
@@ -170,6 +170,8 @@ public:
     static QString binaryName();
 
     //! Returns object which provide interface for nonvisual feedback or NULL
+    //
+    // \deprecated Please use class MFeedback to play input feedbacks. Since 0.20.43
     static MFeedbackPlayer *feedbackPlayer();
 
     //! Returns whether automatic loading of MInputContext is enabled
diff --git a/src/corelib/core/mcomponentdata.h b/src/corelib/core/mcomponentdata.h
index 8a3afc10..7546d2d3 100644
--- a/src/corelib/core/mcomponentdata.h
+++ b/src/corelib/core/mcomponentdata.h
@@ -172,6 +172,8 @@ public:
     static QString serviceName();
 
     //! Returns object which provide interface for nonvisual feedback or NULL
+    //
+    // \deprecated Please use class MFeedback to play input feedbacks. Since 0.20.43
     static MFeedbackPlayer *feedbackPlayer();
 
     //! Returns whether automatic loading of MInputContext is enabled
diff --git a/src/corelib/feedback/mfeedback.cpp b/src/corelib/feedback/mfeedback.cpp
index 9a08e782..5b0e8eb7 100644
--- a/src/corelib/feedback/mfeedback.cpp
+++ b/src/corelib/feedback/mfeedback.cpp
@@ -20,6 +20,10 @@
 #include "mfeedback.h"
 #include "mfeedback_p.h"
 
+const QString MFeedback::Press = "press";
+const QString MFeedback::Release = "release";
+const QString MFeedback::Cancel = "cancel";
+
 MFeedback::MFeedback(const MFeedback &feedback)
     : QObject(0), d_ptr(new MFeedbackPrivate)
 {
@@ -69,3 +73,8 @@ void MFeedback::play() const
     Q_D(const MFeedback);
     d->play();
 }
+
+void MFeedback::play(const QString &feedbackName)
+{
+    MFeedbackPrivate::play(feedbackName);
+}
diff --git a/src/corelib/feedback/mfeedback.h b/src/corelib/feedback/mfeedback.h
index 5fb6e49f..f24c1b9b 100644
--- a/src/corelib/feedback/mfeedback.h
+++ b/src/corelib/feedback/mfeedback.h
@@ -84,6 +84,27 @@ public:
     ~MFeedback();
 
     /*!
+     * Press feedback. Used when the user presses on an object.
+     * It is also used when the user presses off an object,
+     * but slides the finger onto one.
+     */
+    static const QString Press;
+
+    /*!
+     * Release feedback. Used when finger is released on the object.
+     * Indicates that an action was done.
+     */
+    static const QString Release;
+
+    /*!
+     * Cancel feedback. Used when finger slides off the object, onto an
+     * inactive area.
+     *
+     * Also used in cases where a Tap turns into another stroke.
+     */
+    static const QString Cancel;
+
+    /*!
      * \brief Sets the name of the feedback.
      *
      * \param name Name of the feedback
@@ -97,6 +118,13 @@ public:
      */
     QString name() const;
 
+    /*!
+     * \brief Plays a feedback.
+     *
+     * \param feedbackName Name of the feedback to be played
+     */
+    static void play(const QString &feedbackName);
+
 public Q_SLOTS:
     /*!
      * \brief Plays the feedback.
diff --git a/src/corelib/feedback/mfeedback_p.cpp b/src/corelib/feedback/mfeedback_p.cpp
index ec82e972..c86a54c6 100644
--- a/src/corelib/feedback/mfeedback_p.cpp
+++ b/src/corelib/feedback/mfeedback_p.cpp
@@ -33,3 +33,8 @@ void MFeedbackPrivate::play() const
         feedbackPlayer->play(name);
     }
 }
+
+void MFeedbackPrivate::play(const QString &feedbackName)
+{
+    MApplication::feedbackPlayer()->play(feedbackName);
+}
diff --git a/src/corelib/feedback/mfeedback_p.h b/src/corelib/feedback/mfeedback_p.h
index e46e2fad..10715b8f 100644
--- a/src/corelib/feedback/mfeedback_p.h
+++ b/src/corelib/feedback/mfeedback_p.h
@@ -31,6 +31,8 @@ public:
 
     void play() const;
 
+    static void play(const QString &feedbackName);
+
     QString name;
     MFeedbackPlayer *feedbackPlayer;
 };
diff --git a/src/corelib/feedback/mfeedbackplayer.h b/src/corelib/feedback/mfeedbackplayer.h
index b25f894c..d4171ad3 100644
--- a/src/corelib/feedback/mfeedbackplayer.h
+++ b/src/corelib/feedback/mfeedbackplayer.h
@@ -42,6 +42,8 @@ class MFeedbackPlayerPrivate;
  * MFeedbackPlayer also ensures that the instantaneous feedback given is going
  * to comply with the system's current "look and feel" (more especifically, to the
  * "feel" part) and will also be in harmony with the context/situation at hand.
+ *
+ * \deprecated Please use class MFeedback to play input feedbacks. Since 0.20.43
  */
 class M_EXPORT MFeedbackPlayer : public QObject
 {
@@ -72,12 +74,16 @@ public:
      * Press feedback. Used when the user presses on an object.
      * It is also used when the user presses off an object,
      * but slides the finger onto one.
+     *
+     * \deprecated Please use MFeedback::Press instead. Since 0.20.43
      */
     static const QString Press;
 
     /*!
      * Release feedback. Used when finger is released on the object.
      * Indicates that an action was done.
+     *
+     * \deprecated Please use MFeedback::Release instead. Since 0.20.43
      */
     static const QString Release;
 
@@ -86,11 +92,15 @@ public:
      * inactive area.
      *
      * Also used in cases where a Tap turns into another stroke.
+     *
+     * \deprecated Please use MFeedback::Cancel instead. Since 0.20.43
      */
     static const QString Cancel;
 
     /*!
      * Error feedback.
+     *
+     * \deprecated Since 0.20.43
      */
     static const QString Error;
 
@@ -98,6 +108,8 @@ public:
      * Plays a feedback, given its name.
      *
      * \param feedbackName Name of the desired feedback.
+     *
+     * \deprecated Please use MFeedback::play(const QString&) instead. Since 0.20.43
      */
     void play(const QString &feedbackName);
 
diff --git a/tests/ut_mfeedback/ut_mfeedback.cpp b/tests/ut_mfeedback/ut_mfeedback.cpp
index dccaa5a7..c00576e2 100644
--- a/tests/ut_mfeedback/ut_mfeedback.cpp
+++ b/tests/ut_mfeedback/ut_mfeedback.cpp
@@ -61,11 +61,13 @@ void Ut_MFeedback::name()
 }
 
 /*
- * Check that MFeedback playing works as expected.
+ * Check that MFeedback::play() works as expected.
  */
 void Ut_MFeedback::play()
 {
-    MFeedbackPlayer *testPlayer;
+    MFeedbackPlayer *testPlayer = MApplication::feedbackPlayer();
+    testPlayer->playedFeedbacks.clear();
+
     MFeedback feedback1("press-foo");
     MFeedback feedback2;
     MFeedback feedback3("release-foo");
@@ -78,7 +80,6 @@ void Ut_MFeedback::play()
     feedback4.play();
 
     // See that the feedbacks actually got played
-    testPlayer = MApplication::feedbackPlayer();
     QCOMPARE(testPlayer->playedFeedbacks.size(), static_cast<int>(4));
     QCOMPARE(testPlayer->playedFeedbacks.at(0), QString("press-foo"));
     QCOMPARE(testPlayer->playedFeedbacks.at(1), QString());
@@ -86,5 +87,23 @@ void Ut_MFeedback::play()
     QCOMPARE(testPlayer->playedFeedbacks.at(3), QString("cancel-foo"));
 }
 
+/*
+ * Check that MFeedback::play(const QString&) works as expected.
+ */
+void Ut_MFeedback::playWithName()
+{
+    MFeedbackPlayer *testPlayer = MApplication::feedbackPlayer();
+    testPlayer->playedFeedbacks.clear();
+
+    // Play the feedbacks
+    MFeedback::play("press-bar");
+    MFeedback::play("cancel-everything");
+
+    // See that the feedbacks actually got played
+    QCOMPARE(testPlayer->playedFeedbacks.size(), static_cast<int>(2));
+    QCOMPARE(testPlayer->playedFeedbacks.at(0), QString("press-bar"));
+    QCOMPARE(testPlayer->playedFeedbacks.at(1), QString("cancel-everything"));
+}
+
 QTEST_MAIN(Ut_MFeedback)
 
diff --git a/tests/ut_mfeedback/ut_mfeedback.h b/tests/ut_mfeedback/ut_mfeedback.h
index 874a47f7..29eafcf2 100644
--- a/tests/ut_mfeedback/ut_mfeedback.h
+++ b/tests/ut_mfeedback/ut_mfeedback.h
@@ -35,6 +35,7 @@ private slots:
 
     void name();
     void play();
+    void playWithName();
 
 private:
 };