- Qt 6.12
- Qt Virtual Keyboard
- C++ Classes
- QVirtualKeyboardTrace
- Qt Virtual Keyboard | Commercial or GPLv3

# QVirtualKeyboardTrace Class

Trace is a data model for touch input data. More...

Header: | `#include <QVirtualKeyboardTrace>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS VirtualKeyboard)` `target_link_libraries(mytarget PRIVATE Qt6::VirtualKeyboard)`
qmake: | `QT += virtualkeyboard`
Since: | QtQuick.VirtualKeyboard 2.0
In QML: | Trace
Inherits: | QObject

- List of all members, including inherited members

## Properties

canceled : bool channels : QStringList final : bool | length : int opacity : qreal traceId : int

## Public Functions

int | addPoint(const QPointF &point)
QVariantList | channelData(const QString &channel, int pos = 0, int count = -1) const
QStringList | channels() const
bool | isCanceled() const
bool | isFinal() const
int | length() const
qreal | opacity() const
QVariantList | points(int pos = 0, int count = -1) const
void | setCanceled(bool canceled)
void | setChannelData(const QString &channel, int index, const QVariant &data)
void | setChannels(const QStringList &channels)
void | setFinal(bool final)
void | setOpacity(qreal opacity)
void | setTraceId(int id)
`(since 6.1)` void | startHideTimer(int delayMs)
int | traceId() const

## Signals

void | canceledChanged(bool isCanceled)
void | channelsChanged()
void | finalChanged(bool isFinal)
void | lengthChanged(int length)
void | opacityChanged(qreal opacity)
void | traceIdChanged(int traceId)

## Detailed Description

Trace provides the data model for coordinate data and other optional data associated with a single stroke.

A typical use case for the trace object is as follows:

- TraceInputArea or other input device initiates the trace event by calling InputEngine.traceBegin() method.
- If the current input method accepts the event it creates a trace object and configures the required data channels (if any).
- TraceInputArea collects the data for the Trace object.
- TraceInputArea calls the InputEngine.traceEnd() method to finish the trace and passing the trace object back to input method.
- The input method processes the data and discards the object when it is no longer needed.

The coordinate data is retrieved using the points() function.

In addition to coordinate based data, it is possible to attach an arbitrary data channel for each data point.

The data channels must be defined before the points are added. The data channels supported by the TraceInputArea are listed below:

- `"t"` Collects time for each data point. The time is the number of milliseconds since 1970/01/01:

For example, to configure the object to collect the times for each point:

     QVirtualKeyboardTrace *trace = new QVirtualKeyboardTrace(this);
     trace->setChannels(QStringList() << "t");

The collected data can be accessed using the channelData() function:

     QVariantList timeData = trace->channelData("t");

QVirtualKeyboardTrace objects are owned by their creator, which is the input method in normal case. This means the objects are constructed in the InputMethod.traceBegin() (QML) method.

By definition, the trace object can be destroyed at earliest in the InputMethod.traceEnd() (QML) method.

## Property Documentation

### canceled : bool

defines whether the QVirtualKeyboardTrace is canceled.

The input data should not be processed from the Traces whose `canceled` property set to true.

Access functions:

bool | isCanceled() const
void | setCanceled(bool canceled)

Notifier signal:

void | canceledChanged(bool isCanceled)

### channels : QStringList

list of data channels in the QQTrace.

This property must be initialized before the data is added.

Access functions:

QStringList | channels() const
void | setChannels(const QStringList &channels)

Notifier signal:

void | channelsChanged()

### final : bool

defines whether the QVirtualKeyboardTrace can accept more data. If the value is `true`, no more data is accepted.

Access functions:

bool | isFinal() const
void | setFinal(bool final)

Notifier signal:

void | finalChanged(bool isFinal)

### `[read-only]` length : int

This property holds the number of of points in the QVirtualKeyboardTrace.

Access functions:

int | length() const

Notifier signal:

void | lengthChanged(int length)

### opacity : qreal

This property defines how opaque the QVirtualKeyboardTrace is.

A lower value results in a more transparent trace: `0.0` is fully transparent, and `1.0` is fully opaque.

This property is useful for making older traces more transparent as new ones are added.

Access functions:

qreal | opacity() const
void | setOpacity(qreal opacity)

Notifier signal:

void | opacityChanged(qreal opacity)

### traceId : int

unique id of this QVirtualKeyboardTrace.

Access functions:

int | traceId() const
void | setTraceId(int id)

Notifier signal:

void | traceIdChanged(int traceId)

## Member Function Documentation

### `[invokable]` int QVirtualKeyboardTrace::addPoint(const QPointF &point)

Adds a point to the QVirtualKeyboardTrace.

The method returns index of the point added, or -1 if the points cannot be added (i.e. the final is true).

Note: The returned index is required to associate additional data with the point using the setChannelData() method.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` QVariantList QVirtualKeyboardTrace::channelData(const QString &channel, int pos = 0, int count = -1) const

Returns data from the specified channel. If no other parameters are given, the method returns all the data.

If the pos parameter is given, the method returns data starting at the position. The count parameter limits how many items are returned.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also setChannelData().

### `[invokable]` QVariantList QVirtualKeyboardTrace::points(int pos = 0, int count = -1) const

Returns list of points. If no parameters are given, the method returns all the data.

If the pos parameter is given, the method returns points starting at the position. The count parameter limits how many points are returned.

The returned list contains QPointF types.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` void QVirtualKeyboardTrace::setChannelData(const QString &channel, int index, const QVariant &data)

Sets data for the point at index in the given data channel.

If this method is not called for each data point, the channel data will be padded with empty values. However, the data cannot be added at arbitrary index, i.e., it must be added in synchronously with the point data.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also channelData().

### `[invokable, since 6.1]` void QVirtualKeyboardTrace::startHideTimer(int delayMs)

Starts a timer to set opacity to zero after delayMs. If called again within delayMs, the timer is restarted.

With this function the input method can hide the trace from screen before destroying the trace object, for example, to indicate that the trace has been processed.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

This function was introduced in Qt 6.1.