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 | |
42 | QT_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 | */ |
104 | QFeedbackActuator::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 | */ |
120 | QFeedbackActuator::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 | */ |
133 | int 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 | */ |
146 | bool 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 | */ |
159 | QString 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 | */ |
172 | QFeedbackActuator::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 | */ |
180 | bool 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 | */ |
193 | bool 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 | */ |
204 | void 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 | */ |
225 | QList<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 | */ |
235 | bool QFeedbackActuator::operator==(const QFeedbackActuator &other) const |
236 | { |
237 | return m_id == other.m_id; |
238 | } |
239 | |
240 | QT_END_NAMESPACE |
241 | |