Input feedback

Input feedback support for MeeGo Touch applications

MeeGo Touch provides an easy way to integrate immediate feedback into graphical applications. The concept is based on the Qt's signal/slot architecture and the standard theme principles of Linux systems and it is therefore easy to understand and deploy.

A mobile device can support several means for feedback, for example audio speaker, vibra or piezo actuators. Input feedback helps the user to use the graphical controls on the touch screen by providing feedback which is similar to physical buttons. MeeGo Touch offers low latency input feedback which is important for the usability of the product.

Short technical background

The feedbacks are identified by name. For instance, if a user touches a button on the screen, "press" feedback is played or if a selected check box is pressed, "press-off" feedback is played. These feedbacks are played by a daemon (meegofeedbackd) that is invisible for the developers. Different types of feedback methods can be provided by different hardwares:

• Vibra: Based on Immersion TouchSense®
• Audio: Based on PulseAudio

MFeedback class provides an interface to send playback requests from a MeeGo Touch application to the feedback daemon. In practice, when a feedback related 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 of the 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.

Feedbacks in themes

Read the feedbacks part of theme directory structure documentation to see how the feedback files are located in themes.

Typically, a feedback directory can contain two files: vibra.ivt and audio.wav.

Some principles are followed in the theme logic:

• When an event happens (e.g. pressing an MButton), both a vibra and an audio feedback are played at the same time if available.
• If a feedback directory does not contain any file for a hardware (e.g. vibra.ivt), a fallback mechanism tries to find an other effect going back on the theme inheritance tree.
• Using a non-existing name (e.g. "press-loud") triggers fallback mechanism to look for a generic feedback name before the first (and only the first) dash (e.g "press-loud-something" -> "press").
• A zero sized sample file means no feedback, the fallback mechanism stops at such point.

The feedbacks can be played on three different volume levels. This is a global setting of the feedback daemon, but the feedbacks should be prepared for. The Pulseaudio (audio) backend of the daemon sets the appropriate playback volume from a config file so nothing needs to be done in Pulseaudio case. The vibra backend checks the vibra.ivt for three timeline effects named "low", "medium" and "high" referring to low, medium and high volume levels. If there are no correctly named timeline effects in the effect file, the first effect is used (its type does not matter in this case).

Stylesheets

Recommended to read the styling part of the MeeGo Touch documentation before this section, because only the feedback specific syntax is described here.

A css file is associated with an application to describe the style of the widgets. For an application named "example" and a theme named "base", it is located in /usr/share/themes/base/meegotouch/example/style/example.css. The widgets in the applications can be styled on class (means e.g. every button in an application) or object/instance level (means one specific button in the application). Here is a minimal explanation about this concept for readers without deeper developer knowledge:

• The widgets in an application are instances of their class definitions. E.g. Buttons are instances of MButton classes.
• To distinguish two instances of the same class (e.g an Ok and Cancel button on the screen), the different instances can be named. This name is not visible on the screen and does not have any predefined format, but gives the potential to differentiate the instances (e.g. buttons) for styling.
• As a natural demand, there are use cases when the instances of different classes should be themed with the same rules. E.g. Buttons and text input fields (MTextEdit) have a common style property on a particular window, for instance text color. In these cases, the instances can be named with the same name and style with a simple rule referring to the name, but not to the class type.

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:

MButtonStyle {
}

Object instances can be referred by their name. The style data of a button named "SendButton" (an instance of an MButton):

MButtonStyle#SendButton {
}

If multiple instances of several classes (MButton, MTextEdit) are named with the same name "CommonElements", they can be styled with:

#CommonElements {
}

Specifying a feedback "huge-feedback" for the "press" event of an MButton widget instance with the object name "SignInButton":

MButtonStyle#SignInButton {
  press-feedback: huge-feedback;
}

As shown above, the styling rules are written between the curly brackets.

MFeedback

MFeedback class is a thin convenience class to have input feedbacks very easily.

Using an MFeedback instance to play a "press" feedback:

MFeedback* feedback = new MFeedback("press");

Play the input feedback by hand:

feedback->play();

Connect a signal to the feedback:

connect(button, SIGNAL(pressed()), feedback, SLOT(play()));

Using static MFeedback::play(const QString&) to play a "press" feedback:

MFeedback::play("press");

Behind the scenes the feedback event is forwarded to the feedback daemon and the audio/vibra feedback gets played as soon as possible.

Minimal application that plays "press" feedback without using any widgets

The following application simply plays a feedback called "press".

app.pro:

TEMPLATE = app
CONFIG += meegotouch
SOURCES += main.cpp

main.cpp:

#include <MApplication>
#include <MFeedback>

int main(int argc, char* argv[])
{
  MApplication app(argc, argv);

  // Process some initial events in the event queue
  app.processEvents();
  // Request the press feedback
  MFeedback::play("press");
  // Be sure that the request is processed
  app.processEvents();
}

Simple application that uses MButton widget to play feedbacks

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:

TEMPLATE = app
CONFIG += meegotouch
SOURCES += main.cpp

main.cpp:

#include <MApplication>
#include <MApplicationWindow>
#include <MApplicationPage>
#include <MButton>

int main(int argc, char* argv[])
{
  // Create an application with a button
  MApplication app(argc, argv);
  MApplicationPage* page = new MApplicationPage();
  MApplicationWindow* window = new MApplicationWindow();
  MButton* button = new MButton("Hello World");

  // Show the UI
  page->setCentralWidget(button);
  window->show();
  page->appear(window);

  // Enter the main loop
  app.exec();

  // Clean up
  delete window;
}

Advanced example with plain Qt widgets

The following application creates a window and places a "Hello world!" button in the window. The default input feedback support will be switched off by forcing the usage of the motif style, but the press feedback is connected to the pressed signal of the button manually. If any argument is passed to the application the feedback is not connected to the signal.

app.pro:

TEMPLATE = app
CONFIG += meegotouch
SOURCES += main.cpp

main.cpp:

#include <QApplication>
#include <QMotifStyle>
#include <QPushButton>

#include <MComponentData>
#include <MFeedback>

int main(int argc, char* argv[])
{
  // Create an application with a button
  QApplication app(argc, argv);
  QPushButton* button = new QPushButton("Hello World");
  // An MComponentData instance is needed for the MeeGo related Qt extensions.
  MComponentData mTData(argc, argv);

  // Force the motif style to switch off the automatic input feedback support
  QApplication::setStyle(new QMotifStyle);
  // Show the UI
  button->show();

  // Get the press feedback
  MFeedback* feedback = new MFeedback("press");
  // Switch off the press feedback if arguments are passed
  if (argc == 1)
    // Connect the press event to the "press" feedback
    button->connect(button, SIGNAL(pressed()), feedback, SLOT(play()));

  // Enter the main loop
  app.exec();

  // Clean up
  delete feedback;
}

Styling use case 1: Override a default feedback for an application

Let's say that an application 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

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 "press-on" feedback. The app.css file should be placed in the usr/share/themes/base/meegotouch/app/style directory.

app.css:

MButtonStyle#NormalButton {
  press-feedback: press-on;
}

app.pro:

TEMPLATE = app
CONFIG += meegotouch
SOURCES += main.cpp

main.cpp:

#include <MApplication>
#include <MApplicationWindow>
#include <MApplicationPage>
#include <MButton>

int main(int argc, char* argv[])
{
  // Create an application with a button
  MApplication app(argc, argv);
  MApplicationPage* page = new MApplicationPage();
  MApplicationWindow* window = new MApplicationWindow();
  MButton* button = new MButton("Hello World");

  button->setStyleName("NormalButton");

  // Show the UI
  page->setCentralWidget(button);
  window->show();
  page->appear(window);

  // Enter the main loop
  app.exec();

  // Clean up
  delete window;
}