1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2016 The Qt Company Ltd. |
4 | ** Contact: https://www.qt.io/licensing/ |
5 | ** |
6 | ** This file is part of the Qt Virtual Keyboard module of the Qt Toolkit. |
7 | ** |
8 | ** $QT_BEGIN_LICENSE:GPL$ |
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 https://www.qt.io/terms-conditions. For further |
15 | ** information use the contact form at https://www.qt.io/contact-us. |
16 | ** |
17 | ** GNU General Public License Usage |
18 | ** Alternatively, this file may be used under the terms of the GNU |
19 | ** General Public License version 3 or (at your option) any later version |
20 | ** approved by the KDE Free Qt Foundation. The licenses are as published by |
21 | ** the Free Software Foundation and appearing in the file LICENSE.GPL3 |
22 | ** included in the packaging of this file. Please review the following |
23 | ** information to ensure the GNU General Public License requirements will |
24 | ** be met: https://www.gnu.org/licenses/gpl-3.0.html. |
25 | ** |
26 | ** $QT_END_LICENSE$ |
27 | ** |
28 | ****************************************************************************/ |
29 | |
30 | #include <QtVirtualKeyboard/qvirtualkeyboardtrace.h> |
31 | #include <QtCore/private/qobject_p.h> |
32 | |
33 | QT_BEGIN_NAMESPACE |
34 | |
35 | class QVirtualKeyboardTracePrivate : public QObjectPrivate |
36 | { |
37 | public: |
38 | QVirtualKeyboardTracePrivate() : |
39 | QObjectPrivate(), |
40 | traceId(0), |
41 | final(false), |
42 | canceled(false), |
43 | opacity(1.0) |
44 | { } |
45 | |
46 | int traceId; |
47 | QVariantList points; |
48 | QMap<QString, QVariantList> channels; |
49 | bool final; |
50 | bool canceled; |
51 | qreal opacity; |
52 | }; |
53 | |
54 | /*! |
55 | \class QVirtualKeyboardTrace |
56 | \inmodule QtVirtualKeyboard |
57 | \since QtQuick.VirtualKeyboard 2.0 |
58 | \brief Trace is a data model for touch input data. |
59 | |
60 | Trace provides the data model for coordinate data and other |
61 | optional data associated with a single stroke. |
62 | |
63 | A typical use case for the trace object is as follows: |
64 | \list |
65 | \li TraceInputArea or other input device initiates |
66 | the trace event by calling \l {InputEngine::traceBegin()} |
67 | {InputEngine.traceBegin()} method. |
68 | \li If the current input method accepts the event it creates |
69 | a trace object and configures the required data channels |
70 | (if any). |
71 | \li TraceInputArea collects the data for the Trace object. |
72 | \li TraceInputArea calls the \l {InputEngine::traceEnd()} |
73 | {InputEngine.traceEnd()} method to finish the trace and |
74 | passing the trace object back to input method. |
75 | \li The input method processes the data and discards the object |
76 | when it is no longer needed. |
77 | \endlist |
78 | |
79 | The coordinate data is retrieved using the points() function. |
80 | |
81 | In addition to coordinate based data, it is possible |
82 | to attach an arbitrary data channel for each data point. |
83 | |
84 | The data channels must be defined before the points are added. |
85 | The data channels supported by the TraceInputArea are listed below: |
86 | |
87 | \list |
88 | \li \c "t" Collects time for each data point. The time is |
89 | the number of milliseconds since 1970/01/01: |
90 | \endlist |
91 | |
92 | For example, to configure the object to collect the times for |
93 | each point: |
94 | |
95 | \code |
96 | QVirtualKeyboardTrace *trace = new QVirtualKeyboardTrace(this); |
97 | trace->setChannels(QStringList() << "t"); |
98 | \endcode |
99 | |
100 | The collected data can be accessed using the channelData() function: |
101 | |
102 | \code |
103 | QVariantList timeData = trace->channelData("t"); |
104 | \endcode |
105 | |
106 | QVirtualKeyboardTrace objects are owned by their creator, which is the input method in |
107 | normal case. This means the objects are constructed in the |
108 | \l {InputMethod::traceBegin()}{InputMethod.traceBegin()} (QML) method. |
109 | |
110 | By definition, the trace object can be destroyed at earliest in the |
111 | \l {InputMethod::traceEnd()}{InputMethod.traceEnd()} (QML) method. |
112 | */ |
113 | |
114 | /*! |
115 | \qmltype Trace |
116 | \instantiates QVirtualKeyboardTrace |
117 | \inqmlmodule QtQuick.VirtualKeyboard |
118 | \ingroup qtvirtualkeyboard-qml |
119 | \since QtQuick.VirtualKeyboard 2.0 |
120 | \brief Trace is a data model for touch input data. |
121 | |
122 | Trace provides the data model for coordinate data and other |
123 | optional data associated with a single stroke. |
124 | |
125 | A typical use case for the trace object is as follows: |
126 | \list |
127 | \li TraceInputArea or other input device initiates |
128 | the trace event by calling \l {InputEngine::traceBegin()} |
129 | {InputEngine.traceBegin()} method. |
130 | \li If the current input method accepts the event it creates |
131 | a trace object and configures the required data channels |
132 | (if any). |
133 | \li TraceInputArea collects the data for the trace object. |
134 | \li TraceInputArea calls the \l {InputEngine::traceEnd()} |
135 | {InputEngine.traceEnd()} method to finish the trace and |
136 | passing the trace object back to input method. |
137 | \li The input method processes the data and discards the object |
138 | when it is no longer needed. |
139 | \endlist |
140 | |
141 | The coordinate data is retrieved using the points() function. |
142 | |
143 | In addition to coordinate based data, it is possible |
144 | to attach an arbitrary data channel for each data point. |
145 | |
146 | The data channels must be defined before the points are added. |
147 | The data channels supported by the TraceInputArea are listed below: |
148 | |
149 | \list |
150 | \li \c "t" Collects time for each data point. The time is |
151 | the number of milliseconds since 1970/01/01: |
152 | \endlist |
153 | |
154 | For example, to configure the object to collect the times for |
155 | each point: |
156 | |
157 | \code |
158 | QVirtualKeyboardTrace *trace = new QVirtualKeyboardTrace(this); |
159 | trace->setChannels(QStringList() << "t"); |
160 | \endcode |
161 | |
162 | The collected data can be accessed using the channelData() function: |
163 | |
164 | \code |
165 | QVariantList timeData = trace->channelData("t"); |
166 | \endcode |
167 | |
168 | Trace objects are owned by their creator, which is the input method in |
169 | normal case. This means the objects are constructed in the |
170 | \l {InputMethod::traceBegin()}{InputMethod.traceBegin()} (QML) method. |
171 | |
172 | By definition, the trace object can be destroyed at earliest in the |
173 | \l {InputMethod::traceEnd()}{InputMethod.traceEnd()} (QML) method. |
174 | */ |
175 | |
176 | /*! \internal */ |
177 | QVirtualKeyboardTrace::QVirtualKeyboardTrace(QObject *parent) : |
178 | QObject(*new QVirtualKeyboardTracePrivate(), parent) |
179 | { |
180 | } |
181 | |
182 | /*! \internal */ |
183 | QVirtualKeyboardTrace::~QVirtualKeyboardTrace() |
184 | { |
185 | } |
186 | |
187 | int QVirtualKeyboardTrace::traceId() const |
188 | { |
189 | Q_D(const QVirtualKeyboardTrace); |
190 | return d->traceId; |
191 | } |
192 | |
193 | void QVirtualKeyboardTrace::setTraceId(int id) |
194 | { |
195 | Q_D(QVirtualKeyboardTrace); |
196 | if (d->traceId != id) { |
197 | d->traceId = id; |
198 | emit traceIdChanged(traceId: id); |
199 | } |
200 | } |
201 | |
202 | QStringList QVirtualKeyboardTrace::channels() const |
203 | { |
204 | Q_D(const QVirtualKeyboardTrace); |
205 | return d->channels.keys(); |
206 | } |
207 | |
208 | void QVirtualKeyboardTrace::setChannels(const QStringList &channels) |
209 | { |
210 | Q_D(QVirtualKeyboardTrace); |
211 | Q_ASSERT(d->points.isEmpty()); |
212 | if (d->points.isEmpty()) { |
213 | d->channels.clear(); |
214 | for (QStringList::ConstIterator i = channels.constBegin(); |
215 | i != channels.constEnd(); i++) { |
216 | d->channels[*i] = QVariantList(); |
217 | } |
218 | emit channelsChanged(); |
219 | } |
220 | } |
221 | |
222 | int QVirtualKeyboardTrace::length() const |
223 | { |
224 | Q_D(const QVirtualKeyboardTrace); |
225 | return d->points.size(); |
226 | } |
227 | |
228 | /*! \qmlmethod var Trace::points(int pos, int count) |
229 | |
230 | Returns list of points. If no parameters are given, the |
231 | function returns all the points. |
232 | |
233 | If the \a pos parameter is given, the function returns points starting |
234 | at the position. The \a count parameter limits how many points are |
235 | returned. |
236 | |
237 | The returned list contains \c point types. |
238 | */ |
239 | |
240 | /*! Returns list of points. If no parameters are given, the |
241 | method returns all the data. |
242 | |
243 | If the \a pos parameter is given, the method returns points starting |
244 | at the position. The \a count parameter limits how many points are |
245 | returned. |
246 | |
247 | The returned list contains QPointF types. |
248 | */ |
249 | |
250 | QVariantList QVirtualKeyboardTrace::points(int pos, int count) const |
251 | { |
252 | Q_D(const QVirtualKeyboardTrace); |
253 | return d->points.mid(pos, alength: count); |
254 | } |
255 | |
256 | /*! \qmlmethod int Trace::addPoint(point point) |
257 | |
258 | Adds a \a point to the Trace. |
259 | |
260 | The method returns index of the point added, or -1 if |
261 | the points cannot be added (i.e. the \l final is true). |
262 | |
263 | \note The returned index is required to associate additional |
264 | data with the point using the setChannelData() function. |
265 | */ |
266 | |
267 | /*! Adds a \a point to the QVirtualKeyboardTrace. |
268 | |
269 | The method returns index of the point added, or -1 if |
270 | the points cannot be added (i.e. the \l final is true). |
271 | |
272 | \note The returned index is required to associate additional |
273 | data with the point using the setChannelData() method. |
274 | */ |
275 | |
276 | int QVirtualKeyboardTrace::addPoint(const QPointF &point) |
277 | { |
278 | Q_D(QVirtualKeyboardTrace); |
279 | int index; |
280 | if (!d->final) { |
281 | index = d->points.size(); |
282 | d->points.append(t: point); |
283 | emit lengthChanged(length: d->points.size()); |
284 | } else { |
285 | index = -1; |
286 | } |
287 | return index; |
288 | } |
289 | |
290 | /*! \qmlmethod void Trace::setChannelData(int index, string channel, var data) |
291 | |
292 | Sets \a data for the point at \a index in the given data \a channel. |
293 | |
294 | If this method is not called for each data point, the channel data |
295 | will be padded with empty values. However, the data cannot be added at |
296 | arbitrary index, i.e., it must be added in synchronously with the point data. |
297 | */ |
298 | |
299 | /*! Sets \a data for the point at \a index in the given data \a channel. |
300 | |
301 | If this method is not called for each data point, the channel data |
302 | will be padded with empty values. However, the data cannot be added at |
303 | arbitrary index, i.e., it must be added in synchronously with the point data. |
304 | */ |
305 | |
306 | void QVirtualKeyboardTrace::setChannelData(const QString &channel, int index, const QVariant &data) |
307 | { |
308 | Q_D(QVirtualKeyboardTrace); |
309 | if (!d->final && (index + 1) == d->points.size() && d->channels.contains(akey: channel)) { |
310 | QVariantList &channelData = d->channels[channel]; |
311 | while (index > channelData.size()) |
312 | channelData.append(t: QVariant()); |
313 | if (index == channelData.size()) |
314 | channelData.append(t: data); |
315 | } |
316 | } |
317 | |
318 | /*! \qmlmethod var Trace::channelData(string channel, int pos, int count) |
319 | |
320 | Returns data from the specified \a channel. If no other parameters |
321 | are given, the function returns all the data. |
322 | |
323 | If the \a pos parameter is given, the function returns data starting |
324 | at the position. The \a count parameter limits how many items are |
325 | returned. |
326 | */ |
327 | |
328 | /*! Returns data from the specified \a channel. If no other parameters |
329 | are given, the method returns all the data. |
330 | |
331 | If the \a pos parameter is given, the method returns data starting |
332 | at the position. The \a count parameter limits how many items are |
333 | returned. |
334 | */ |
335 | |
336 | QVariantList QVirtualKeyboardTrace::channelData(const QString &channel, int pos, int count) const |
337 | { |
338 | Q_D(const QVirtualKeyboardTrace); |
339 | return d->channels.value(akey: channel).mid(pos, alength: count); |
340 | } |
341 | |
342 | bool QVirtualKeyboardTrace::isFinal() const |
343 | { |
344 | Q_D(const QVirtualKeyboardTrace); |
345 | return d->final; |
346 | } |
347 | |
348 | void QVirtualKeyboardTrace::setFinal(bool final) |
349 | { |
350 | Q_D(QVirtualKeyboardTrace); |
351 | if (d->final != final) { |
352 | d->final = final; |
353 | emit finalChanged(isFinal: final); |
354 | } |
355 | } |
356 | |
357 | bool QVirtualKeyboardTrace::isCanceled() const |
358 | { |
359 | Q_D(const QVirtualKeyboardTrace); |
360 | return d->canceled; |
361 | } |
362 | |
363 | void QVirtualKeyboardTrace::setCanceled(bool canceled) |
364 | { |
365 | Q_D(QVirtualKeyboardTrace); |
366 | if (d->canceled != canceled) { |
367 | d->canceled = canceled; |
368 | emit canceledChanged(isCanceled: canceled); |
369 | } |
370 | } |
371 | |
372 | qreal QVirtualKeyboardTrace::opacity() const |
373 | { |
374 | Q_D(const QVirtualKeyboardTrace); |
375 | return d->opacity; |
376 | } |
377 | |
378 | void QVirtualKeyboardTrace::setOpacity(qreal opacity) |
379 | { |
380 | Q_D(QVirtualKeyboardTrace); |
381 | if (d->opacity != opacity) { |
382 | d->opacity = opacity; |
383 | emit opacityChanged(opacity); |
384 | } |
385 | } |
386 | |
387 | /*! \qmlproperty int Trace::traceId |
388 | |
389 | Unique id of this Trace. |
390 | */ |
391 | |
392 | /*! \property QVirtualKeyboardTrace::traceId |
393 | \brief unique id of this QVirtualKeyboardTrace. |
394 | */ |
395 | |
396 | /*! \qmlproperty list<strings> Trace::channels |
397 | |
398 | List of additional data channels in the Trace. |
399 | This property must be initialized before the data |
400 | is added. |
401 | */ |
402 | |
403 | /*! \property QVirtualKeyboardTrace::channels |
404 | \brief list of data channels in the QQTrace. |
405 | |
406 | This property must be initialized before the data |
407 | is added. |
408 | */ |
409 | |
410 | /*! \qmlproperty int QVirtualKeyboardTrace::length |
411 | |
412 | The number of points in the QVirtualKeyboardTrace. |
413 | */ |
414 | |
415 | /*! \property QVirtualKeyboardTrace::length |
416 | \brief the number of of points in the QVirtualKeyboardTrace. |
417 | */ |
418 | |
419 | /*! \qmlproperty bool Trace::final |
420 | |
421 | This property defines whether the Trace can accept more data. |
422 | If the value is \c true, no more data is accepted. |
423 | */ |
424 | |
425 | /*! \property QVirtualKeyboardTrace::final |
426 | \brief defines whether the QVirtualKeyboardTrace can accept more data. |
427 | If the value is \c true, no more data is accepted. |
428 | */ |
429 | |
430 | /*! \qmlproperty bool Trace::canceled |
431 | |
432 | This property defines whether the Trace is canceled. |
433 | The input data should not be processed from the Traces |
434 | whose \c canceled property set to true. |
435 | */ |
436 | |
437 | /*! \property QVirtualKeyboardTrace::canceled |
438 | \brief defines whether the QVirtualKeyboardTrace is canceled. |
439 | |
440 | The input data should not be processed from the Traces |
441 | whose \c canceled property set to true. |
442 | */ |
443 | |
444 | /*! \qmlproperty qreal Trace::opacity |
445 | \since QtQuick.VirtualKeyboard 2.4 |
446 | |
447 | This property defines how opaque the Trace is. |
448 | |
449 | A lower value results in a more transparent trace: \c 0.0 is fully |
450 | transparent, and \c 1.0 is fully opaque. |
451 | |
452 | This property is useful for making older traces more transparent as new |
453 | ones are added. |
454 | */ |
455 | |
456 | /*! \property QVirtualKeyboardTrace::opacity |
457 | |
458 | This property defines how opaque the QVirtualKeyboardTrace is. |
459 | |
460 | A lower value results in a more transparent trace: \c 0.0 is fully |
461 | transparent, and \c 1.0 is fully opaque. |
462 | |
463 | This property is useful for making older traces more transparent as new |
464 | ones are added. |
465 | */ |
466 | |
467 | QT_END_NAMESPACE |
468 | |