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
33QT_BEGIN_NAMESPACE
34
35class QVirtualKeyboardTracePrivate : public QObjectPrivate
36{
37public:
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 */
177QVirtualKeyboardTrace::QVirtualKeyboardTrace(QObject *parent) :
178 QObject(*new QVirtualKeyboardTracePrivate(), parent)
179{
180}
181
182/*! \internal */
183QVirtualKeyboardTrace::~QVirtualKeyboardTrace()
184{
185}
186
187int QVirtualKeyboardTrace::traceId() const
188{
189 Q_D(const QVirtualKeyboardTrace);
190 return d->traceId;
191}
192
193void 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
202QStringList QVirtualKeyboardTrace::channels() const
203{
204 Q_D(const QVirtualKeyboardTrace);
205 return d->channels.keys();
206}
207
208void 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
222int 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
250QVariantList 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
276int 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
306void 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
336QVariantList 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
342bool QVirtualKeyboardTrace::isFinal() const
343{
344 Q_D(const QVirtualKeyboardTrace);
345 return d->final;
346}
347
348void 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
357bool QVirtualKeyboardTrace::isCanceled() const
358{
359 Q_D(const QVirtualKeyboardTrace);
360 return d->canceled;
361}
362
363void 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
372qreal QVirtualKeyboardTrace::opacity() const
373{
374 Q_D(const QVirtualKeyboardTrace);
375 return d->opacity;
376}
377
378void 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
467QT_END_NAMESPACE
468

source code of qtvirtualkeyboard/src/virtualkeyboard/qvirtualkeyboardtrace.cpp