1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: http://www.qt.io/licensing/
5**
6** This file is part of the QtFeedback module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL3$
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 The Qt Company. For licensing terms
14** and conditions see http://www.qt.io/terms-conditions. For further
15** information use the contact form at http://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPLv3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or later as published by the Free
28** Software Foundation and appearing in the file LICENSE.GPL included in
29** the packaging of this file. Please review the following information to
30** ensure the GNU General Public License version 2.0 requirements will be
31** met: http://www.gnu.org/licenses/gpl-2.0.html.
32**
33** $QT_END_LICENSE$
34**
35****************************************************************************/
36
37#include "qfeedbackactuator.h"
38#include "qfeedbackplugininterfaces.h"
39
40#include <QtCore/QVariant>
41
42QT_BEGIN_NAMESPACE
43
44/*!
45 \class QFeedbackActuator
46 \brief The QFeedbackActuator class describes actuators for tactile feedback.
47 \inmodule QtFeedback
48
49 An actuator knows how to play a \l{QFeedbackEffect}{tactile
50 effect}. The class gives access to a specified actuator.
51
52 An actuator can be used to play \l{QFeedbackHapticsEffect}s using
53 \l{QFeedbackHapticsEffect::}{setActuator()}. Usually, you will not
54 have to set an actuator directly on a QFeedbackHapticsEffect.
55 QFeedbackHapticsEffect and QFeedbackFileEffect uses an appropriate
56 actuator by default. However, you can query which actuators
57 are available with actuators().
58
59 \code
60 QFeedbackActuator actuator; // default system actuator
61 QList<QFeedbackActuator> actuators = QFeedbackActuator::actuators();
62 foreach (const QFeedbackActuator& temp, actuators) {
63 if (temp.name() == "ExampleActuatorName") {
64 actuator = temp;
65 }
66 }
67 \endcode
68
69 The QFeedbackActuator class gives access to information about the
70 actuator it represents. You can query if the actuator \l{isEnabled()}{is enabled}
71 and if it \l{isValid()}{is valid }. Whether an actuator is ready to play an
72 effect can be queried by checking the actuator's state(). The
73 \l{QFeedbackActuator::}{State} enum describes the states and
74 actuator can have. You can also get a human readable name for the actuator with the
75 name() function.
76
77 \sa QFeedbackHapticsEffect, QFeedbackFileEffect, QFeedbackEffect
78*/
79
80/*!
81 \enum QFeedbackActuator::Capability
82
83 \value Envelope Capability defining the wave type with attack/fade times and levels.
84 \value Period Capability defining that the device can play periodic effects.
85*/
86
87/*!
88 \enum QFeedbackActuator::State
89
90 \value Busy The actuator is busy.
91 \value Ready The actuator is ready to play an effect.
92 \value Unknown The actuator is in an unknown state.
93*/
94
95
96/*!
97 Constructs a QFeedbackActuator, passing \a parent to the QObject constructor.
98
99 The object will represent the default actuator on the system.
100 If there are no actuators attached to the system, isValid() will return false.
101
102 \sa isValid()
103*/
104QFeedbackActuator::QFeedbackActuator(QObject *parent) : QObject(parent), m_id(-1)
105{
106 QList<QFeedbackActuator*> list = actuators();
107 if (!list.isEmpty()) {
108 QFeedbackActuator* defaultActuator = list.first();
109 m_id = defaultActuator->id();
110 }
111}
112
113/*!
114 Constructs a QFeedbackActuator with id \a id, passing \a parent to the QObject constructor.
115
116 This is used by plugins to represents their actuators.
117
118 \sa isValid()
119*/
120QFeedbackActuator::QFeedbackActuator(QObject *parent, int id) : QObject(parent), m_id(id)
121{
122}
123
124/*!
125 \property QFeedbackActuator::id
126 \brief id of the feedback actuator.
127*/
128
129/*!
130 Returns the id of the actuator.
131 \since 1.1
132*/
133int QFeedbackActuator::id() const
134{
135 return m_id;
136}
137
138/*!
139 \property QFeedbackActuator::valid
140 \brief validity of the feedback actuator
141*/
142
143/*!
144 Returns true if the actuator is valid.
145*/
146bool QFeedbackActuator::isValid() const
147{
148 return m_id >= 0;
149}
150
151/*!
152 \property QFeedbackActuator::name
153 \brief name of the feedback actuator
154*/
155
156/*!
157 Returns the name of the actuator.
158*/
159QString QFeedbackActuator::name() const
160{
161 return QFeedbackHapticsInterface::instance()->actuatorProperty(*this, QFeedbackHapticsInterface::Name).toString();
162}
163
164/*!
165 \property QFeedbackActuator::state
166 \brief state of the feedback actuator
167*/
168
169/*!
170 Returns the state of the actuator.
171*/
172QFeedbackActuator::State QFeedbackActuator::state() const
173{
174 return QFeedbackActuator::State(QFeedbackHapticsInterface::instance()->actuatorProperty(*this, QFeedbackHapticsInterface::State).toInt());
175}
176
177/*!
178 Returns if the actuator supports the supplied \a capability.
179*/
180bool QFeedbackActuator::isCapabilitySupported(Capability capability) const
181{
182 return QFeedbackHapticsInterface::instance()->isActuatorCapabilitySupported(*this, capability);
183}
184
185/*!
186 \property QFeedbackActuator::enabled
187 \brief whether the feedback actuator is enabled
188*/
189
190/*!
191 Returns true if you can use this actuator to start effects.
192*/
193bool QFeedbackActuator::isEnabled() const
194{
195 return QFeedbackHapticsInterface::instance()->actuatorProperty(*this, QFeedbackHapticsInterface::Enabled).toBool();
196}
197
198/*!
199 Allows you to enable or disable an actuator. If \a enabled is true, the actuator will be enabled,
200 and otherwise it will be disabled.
201
202 \note Some systems may not allow you to change whether an actuator is enabled.
203*/
204void QFeedbackActuator::setEnabled(bool enabled)
205{
206 if (isEnabled() != enabled) {
207 QFeedbackHapticsInterface::instance()->setActuatorProperty(*this, QFeedbackHapticsInterface::Enabled, enabled);
208 emit enabledChanged();
209 }
210}
211
212/*!
213 \fn void QFeedbackActuator::enabledChanged()
214
215 This signal is emitted when the actuator is requested to enable or disable itself.
216
217 \sa isEnabled()
218*/
219
220/*!
221 \fn QFeedbackActuator::actuators()
222
223 Returns the list of actuators available on the system.
224*/
225QList<QFeedbackActuator*> QFeedbackActuator::actuators()
226{
227 return QFeedbackHapticsInterface::instance()->actuators();
228}
229
230/*!
231 \fn QFeedbackActuator::operator==(const QFeedbackActuator &other) const
232
233 Returns true if this actuator is equal to \a other.
234*/
235bool QFeedbackActuator::operator==(const QFeedbackActuator &other) const
236{
237 return m_id == other.m_id;
238}
239
240QT_END_NAMESPACE
241

source code of qtfeedback/src/feedback/qfeedbackactuator.cpp