×
Namespaces

Variants
Actions
(Difference between revisions)

Haptics effects in Qt

From Nokia Developer Wiki
Jump to: navigation, search
somnathbanik (Talk | contribs)
hamishwillee (Talk | contribs)
m (Text replace - "<code cpp>" to "<code cpp-qt>")
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Qt]][[Category:Qt Mobility]]
+
[[Category:Qt Mobility]][[Category:MeeGo Harmattan]][[Category:Symbian]][[Category:Qt C++ UI]][[Category:UI]]
= Introduction =
+
{{Abstract|This article shows how to provide haptic feedback to users (either through vibration or audio) using the [http://doc.qt.nokia.com/qtmobility/feedback.html Qt Feedback API].}} This could be used in games or UIs to improve the user experience.
{{Abstract| This article shows how Qt Mobility Feedback API enables a client to provide a feedback to the user actions.}}
+
{{ArticleNeedsUpdate|timestamp=20120302052433|user=[[User:Hamishwillee|&lt;br /&gt;----]]|[[:Category:Qt Quick|Qt Quick]] should be used to demonstrate this API - UI development on mobile devices using Qt C++ is deprecated.}}
Qt Mobility 1.1 introduced a new set of APIs called Feedback API. This new API provides a way to send feedback to the user (either through vibration or audio). This could be used in games or user interfaces to improve the user experience.
+
{{ArticleMetaData <!-- v1.2 -->
 +
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
 +
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 +
|devices= <!-- Devices tested against - e.g. ''devices=Nokia 6131 NFC, Nokia C7-00'') -->
 +
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Qt SDK 1.1.4]) -->
 +
|platform= <!-- Compatible platforms - e.g. Symbian^1 and later, Qt 4.6 and later -->
 +
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 +
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
 +
|signing= <!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 +
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 +
|keywords= <!-- APIs, classes and methods (e.g. QSystemScreenSaver, QList, CBase -->
 +
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 +
|translated-by= <!-- [[User:XXXX]] -->
 +
|translated-from-title= <!-- Title only -->
 +
|translated-from-id= <!-- Id of translated revision -->
 +
|review-by= <!-- After re-review: [[User:username]] -->
 +
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 +
|update-by= <!-- After significant update: [[User:username]]-->
 +
|update-timestamp= <!-- After significant update: YYYYMMDD -->
 +
|creationdate= 20101123
 +
|author= [[User:Lpvalente]]
 +
}}
  
= Some things first =
+
== Before we start ==
  
 
First of all, it's important to understand the concept of actuators. An actuator is a device responsible for providing tactile feedback. It's like a tiny motor that produces a physical effect to a command sent by our application.
 
First of all, it's important to understand the concept of actuators. An actuator is a device responsible for providing tactile feedback. It's like a tiny motor that produces a physical effect to a command sent by our application.
  
The Feedback API abstract those devices through the QFeedbackActuator class. Those devices are identified by the <tt>id()</tt> and have a <tt>name()</tt>. Please see http://doc.qt.nokia.com/qtmobility-1.1/qfeedbackactuator.html for the complete documentation.
+
The Feedback API abstract those devices through the QFeedbackActuator class. Those devices are identified by the {{Icode|id()}} and have a {{Icode|name()}}. Please see [http://doc.qt.nokia.com/qtmobility-1.1/qfeedbackactuator.html QFeedbackActuator] for the complete documentation.
  
The actuators are capable of providing different effects. For example, on the Nokia N8 the actuator named “Touch” is capable of providing feedback when the user touches the screen. The actuator named “Vibra” is the one that works when producing vibration (like the one that occurs when the phone is ringing). To know which actuators exists in the device, the API provides this method:
+
The actuators are capable of providing different effects. For example, on the Nokia N8 the actuator named "Touch" is capable of providing feedback when the user touches the screen. The actuator named "Vibra" is the one that works when producing vibration (like the one that occurs when the phone is ringing). To know which actuators exists in the device, the API provides this method:
  
 
+
<code cpp-qt>
<code cpp>
+
 
QList<QFeedbackActuator *> list = QFeedbackActuator::actuators () ;
 
QList<QFeedbackActuator *> list = QFeedbackActuator::actuators () ;
 
</code>
 
</code>
Line 19: Line 39:
 
With that list in hand you are able to query which actuators you can use.
 
With that list in hand you are able to query which actuators you can use.
  
=Making it vibrate=
+
==Making it vibrate==
  
 
Now we're going to show how to make the phone vibrate. The API provides a class named [http://doc.qt.nokia.com/qtmobility-1.2/qfeedbackhapticseffect.html QFeedbackHapticsEffect] that abstract the concept of “feedback effect”.
 
Now we're going to show how to make the phone vibrate. The API provides a class named [http://doc.qt.nokia.com/qtmobility-1.2/qfeedbackhapticseffect.html QFeedbackHapticsEffect] that abstract the concept of “feedback effect”.
  
==How it works==
+
===How it works===
  
 
The effect is composed of three parts: start, middle, and end. The start part is called “attack”, and the end part is called “fade”. The API provides methods to configure all those parts. The end result is that the total time the effect lasts is  “attack” + main part + “fade”. Let's see an example:
 
The effect is composed of three parts: start, middle, and end. The start part is called “attack”, and the end part is called “fade”. The API provides methods to configure all those parts. The end result is that the total time the effect lasts is  “attack” + main part + “fade”. Let's see an example:
  
<code cpp>
+
<code cpp-qt>
 
QfeedbackHapticsEffect effect;
 
QfeedbackHapticsEffect effect;
  
Line 36: Line 56:
 
</code>
 
</code>
  
This piece of code configures the effect to last for 1 second (1000 ms) and have an intensity of 50%. The intensity is a number between 0.0 and 1.0, with this last value meaning “full intensity”. The method <tt>start()</tt> starts playing the effect, and <tt>stop()</tt> is used to stop playing it.
+
This piece of code configures the effect to last for 1 second (1000 ms) and have an intensity of 50%. The intensity is a number between 0.0 and 1.0, with this last value meaning “full intensity”. The method {{Icode|start()}} starts playing the effect, and {{Icode|stop()}} is used to stop playing it.
  
==Hey, what about the actuators?==
+
===What about the actuators?===
  
 
The device plays the effect using one of its actuators. In the example, it uses the “default actuator”. In the N8, this happens to be the “Touch” actuator. So, how can we make the device vibrate? We need to change the actuator!
 
The device plays the effect using one of its actuators. In the example, it uses the “default actuator”. In the N8, this happens to be the “Touch” actuator. So, how can we make the device vibrate? We need to change the actuator!
  
<code cpp>
+
<code cpp-qt>
  
 
// get the actuator list
 
// get the actuator list
Line 68: Line 88:
 
And that's it.
 
And that's it.
  
==How about the other parts of the effect?==
+
===How about the other parts of the effect?===
  
Use the following methods from QFeedbackHapticsEffect to change the other two parts of the effect. By default their duration is zero milliseconds.
+
Use the following methods from QFeedbackHapticsEffect to change the other two parts of the effect. By default their duration is zero milliseconds.
  
* <tt>void setAttackIntensity (qreal intensity)</tt>
+
* {{Icode|void setAttackIntensity (qreal intensity)}}
* <tt>void setAttackTime (int msecs)</tt>
+
* {{Icode|void setAttackTime (int msecs)}}
* <tt>void setFadeIntensity (qreal intensity)</tt>
+
* {{Icode|void setFadeIntensity (qreal intensity)}}
* <tt>void setFadeTime (int msecs)</tt>
+
* {{Icode|void setFadeTime (int msecs)}}
  
=Short example=
+
==Short example==
  
 
Our example uses this user interface:
 
Our example uses this user interface:
  
[[File:Haptics_effects_in_qt_fig_1.jpg]]
+
[[File:Haptics effects in qt fig 1.jpg]]
  
 
It has two button and a plain text box.
 
It has two button and a plain text box.
Line 87: Line 107:
 
Here's our Widget.h file:
 
Here's our Widget.h file:
  
<code cpp>
+
<code cpp-qt>
 
#ifndef WIDGET_H
 
#ifndef WIDGET_H
 
#define WIDGET_H
 
#define WIDGET_H
Line 125: Line 145:
 
</code>
 
</code>
  
We need to include the files for the actuator and feedback effect. The classes of Qt Mobility are under the <tt>QtMobility</tt> namespace. We are declaring it in the file for convenience. The public slots are connected to the button events. The <tt>put()</tt> method is a convenience method to print text in the text box.
+
We need to include the files for the actuator and feedback effect. The classes of Qt Mobility are under the {{Icode|QtMobility}} namespace. We are declaring it in the file for convenience. The public slots are connected to the button events. The {{Icode|put()}} method is a convenience method to print text in the text box.
  
 
Now here is the implementation file:
 
Now here is the implementation file:
  
<code cpp>
+
<code cpp-qt>
 
#include "widget.h"
 
#include "widget.h"
 
#include "ui_widget.h"
 
#include "ui_widget.h"
Line 220: Line 240:
 
</code>
 
</code>
  
Reference document of [http://doc.qt.nokia.com/qtmobility-1.2/ Qt Mobility 1.2]]
+
 
 +
== References ==
 +
* [http://doc.qt.nokia.com/qtmobility-1.2/ Qt Mobility 1.2]

Latest revision as of 04:13, 11 October 2012

This article shows how to provide haptic feedback to users (either through vibration or audio) using the Qt Feedback API. This could be used in games or UIs to improve the user experience.

Needs-update.pngThis article needs to be updated: If you found this article useful, please fix the problems below then delete the {{ArticleNeedsUpdate}} template from the article to remove this warning.

Reasons: hamishwillee (02 Mar 2012)
Qt Quick should be used to demonstrate this API - UI development on mobile devices using Qt C++ is deprecated.

Article Metadata
Compatibility
Platform(s):
Symbian
Article
Created: lpvalente (23 Nov 2010)
Last edited: hamishwillee (11 Oct 2012)

Contents

[edit] Before we start

First of all, it's important to understand the concept of actuators. An actuator is a device responsible for providing tactile feedback. It's like a tiny motor that produces a physical effect to a command sent by our application.

The Feedback API abstract those devices through the QFeedbackActuator class. Those devices are identified by the id() and have a name(). Please see QFeedbackActuator for the complete documentation.

The actuators are capable of providing different effects. For example, on the Nokia N8 the actuator named "Touch" is capable of providing feedback when the user touches the screen. The actuator named "Vibra" is the one that works when producing vibration (like the one that occurs when the phone is ringing). To know which actuators exists in the device, the API provides this method:

QList<QFeedbackActuator *> list = QFeedbackActuator::actuators () ;

With that list in hand you are able to query which actuators you can use.

[edit] Making it vibrate

Now we're going to show how to make the phone vibrate. The API provides a class named QFeedbackHapticsEffect that abstract the concept of “feedback effect”.

[edit] How it works

The effect is composed of three parts: start, middle, and end. The start part is called “attack”, and the end part is called “fade”. The API provides methods to configure all those parts. The end result is that the total time the effect lasts is “attack” + main part + “fade”. Let's see an example:

QfeedbackHapticsEffect effect;
 
effect.setIntensity (0.5);
effect.setDuration (1000);
 
effect.start();

This piece of code configures the effect to last for 1 second (1000 ms) and have an intensity of 50%. The intensity is a number between 0.0 and 1.0, with this last value meaning “full intensity”. The method start() starts playing the effect, and stop() is used to stop playing it.

[edit] What about the actuators?

The device plays the effect using one of its actuators. In the example, it uses the “default actuator”. In the N8, this happens to be the “Touch” actuator. So, how can we make the device vibrate? We need to change the actuator!

// get the actuator list
QList<QFeedbackActuator *> list = QFeedbackActuator::actuators () ;
 
// get the Vibra
QFeedbackActuator * vibra = 0;
 
foreach (QFeedbackActuator * a, list)
{
if (a->name() == “Vibra”)
{
vibra = a;
}
}
 
// if vibra is not found, you device does not have it
if (vibra == 0)
// handle error
 
// let's change the actuator
effect.setActuator (vibra);

And that's it.

[edit] How about the other parts of the effect?

Use the following methods from QFeedbackHapticsEffect to change the other two parts of the effect. By default their duration is zero milliseconds.

  • void setAttackIntensity (qreal intensity)
  • void setAttackTime (int msecs)
  • void setFadeIntensity (qreal intensity)
  • void setFadeTime (int msecs)

[edit] Short example

Our example uses this user interface:

Haptics effects in qt fig 1.jpg

It has two button and a plain text box.

Here's our Widget.h file:

#ifndef WIDGET_H
#define WIDGET_H
 
#include <QWidget>
#include <QFeedbackActuator>
#include <QFeedbackEffect>
using namespace QtMobility;
 
namespace Ui {
class Widget;
}
 
class Widget : public QWidget
{
Q_OBJECT
 
public:
explicit Widget(QWidget *parent = 0);
~Widget();
 
void put(const QString & msg);
 
public slots:
 
void startClicked();
void stopClicked();
 
private:
Ui::Widget *ui;
QFeedbackHapticsEffect rumble;
 
 
};
 
#endif // WIDGET_H

We need to include the files for the actuator and feedback effect. The classes of Qt Mobility are under the QtMobility namespace. We are declaring it in the file for convenience. The public slots are connected to the button events. The put() method is a convenience method to print text in the text box.

Now here is the implementation file:

#include "widget.h"
#include "ui_widget.h"
 
// convinience method to print text
void Widget::put(const QString & msg)
{
ui->plainTextEdit->insertPlainText(msg);
ui->plainTextEdit->insertPlainText("\n");
}
 
 
Widget::Widget(QWidget *parent) :
QWidget(parent),
ui(new Ui::Widget)
{
ui->setupUi(this);
 
// connect signals and slots
...
 
 
// here we list which actuators are there on the phone
QList<QFeedbackActuator *> list = QFeedbackActuator::actuators();
put (QString ("num actuators: %1").arg(list.count()));
 
QFeedbackActuator* vibra = 0;
 
 
// now we pick the vibra actuator
foreach (QFeedbackActuator* a, list)
{
put (a->name());
 
if (a->name() == "Vibra")
vibra = a;
}
 
if (vibra == 0)
{
put ("vibra not found");
return;
}
 
rumble.setIntensity(1.0);
rumble.setDuration(1000);
rumble.setActuator(vibra);
}
 
Widget::~Widget()
{
delete ui;
}
 
 
void Widget::startClicked()
{
rumble.start();
}
 
void Widget::stopClicked()
{
rumble.stop();
 
}

Finally, here's the .pro file:

QT       += core gui
 
TARGET = FeedbackDemo
TEMPLATE = app
 
 
SOURCES += main.cpp\
widget.cpp
 
HEADERS += widget.h
 
FORMS += widget.ui
 
CONFIG += mobility
MOBILITY = feedback
 
symbian {
TARGET.UID3 = 0xeb02a514
}


[edit] References

This page was last modified on 11 October 2012, at 04:13.
89 page views in the last 30 days.
×