QVirtualKeyboardTrace Class
Trace 是一种用于触摸输入数据的数据模型。更多内容...
| 标题： | #include <QVirtualKeyboardTrace> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS VirtualKeyboard) target_link_libraries(mytarget PRIVATE Qt6::VirtualKeyboard) |
| qmake: | QT += virtualkeyboard |
| 自： | QtQuick.VirtualKeyboard 2.0 |
| 在 QML 中： | Trace |
| 继承自： | QObject |
属性
公共函数
| 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 |
信号
| void | canceledChanged(bool isCanceled) |
| void | channelsChanged() |
| void | finalChanged(bool isFinal) |
| void | lengthChanged(int length) |
| void | opacityChanged(qreal opacity) |
| void | traceIdChanged(int traceId) |
详细说明
Trace 为坐标数据以及与单个笔画相关的其他可选数据提供了数据模型。
trace 对象的一个典型用例如下：
- TraceInputArea 或其他输入设备通过调用InputEngine.traceBegin()方法来触发 trace 事件。
- 如果当前输入方法接受该事件，则会创建一个 trace 对象并配置所需的数据通道（如有）。
- TraceInputArea 收集 Trace 对象的数据。
- TraceInputArea 调用InputEngine.traceEnd() 方法结束 Trace，并将 Trace 对象交还给输入方法。
- 输入方法处理数据，并在不再需要时丢弃该对象。
坐标数据使用points() 函数检索。
除了基于坐标的数据外，还可以为每个数据点附加任意数据通道。
数据通道必须在添加数据点之前定义。TraceInputArea 支持的数据通道如下：
"t"收集每个数据点的时间。该时间表示自 1970/01/01 起经过的毫秒数：
例如，要配置该对象以收集每个数据点的时间：
QVirtualKeyboardTrace *trace = new QVirtualKeyboardTrace(this);
trace->setChannels(QStringList() << "t");可通过调用channelData()函数访问收集到的数据：
QVariantList timeData = trace->channelData("t");QVirtualKeyboardTrace 对象由其创建者拥有，通常情况下创建者是输入法。这意味着这些对象是在InputMethod.traceBegin() (QML) 方法中构建的。
根据定义，trace 对象最早可在InputMethod.traceEnd() (QML) 方法中被销毁。
属性文档
canceled : bool
用于指定QVirtualKeyboardTrace 是否已被取消。
不应处理那些canceled 属性设置为true的Traces中的输入数据。
访问函数：
| bool | isCanceled() const |
| void | setCanceled(bool canceled) |
通知器信号：
| void | canceledChanged(bool isCanceled) |
channels : QStringList
QQTrace 中的数据通道列表。
在添加数据之前，必须先初始化此属性。
访问函数：
| QStringList | channels() const |
| void | setChannels(const QStringList &channels) |
通知信号：
| void | channelsChanged() |
final : bool
用于确定QVirtualKeyboardTrace 是否可以接受更多数据。如果该值为true ，则不再接受任何数据。
访问函数：
| bool | isFinal() const |
| void | setFinal(bool final) |
通知信号：
| void | finalChanged(bool isFinal) |
[read-only] length : int
该属性表示QVirtualKeyboardTrace 中的点数。
访问函数：
| int | length() const |
通知信号：
| void | lengthChanged(int length) |
opacity : qreal
此属性用于定义QVirtualKeyboardTrace 的遮盖程度。
数值越小，轨迹越透明：0.0 表示完全透明，1.0 表示完全不透明。
该属性可用于在添加新轨迹时，使旧的轨迹变得更透明。
访问函数：
| qreal | opacity() const |
| void | setOpacity(qreal opacity) |
通知器信号：
| void | opacityChanged(qreal opacity) |
traceId : int
此QVirtualKeyboardTrace 的唯一标识符。
访问函数：
| int | traceId() const |
| void | setTraceId(int id) |
通知信号：
| void | traceIdChanged(int traceId) |
成员函数文档
[invokable] int QVirtualKeyboardTrace::addPoint(const QPointF &point)
将一个point 添加到QVirtualKeyboardTrace 中。
该方法返回所添加点的索引；如果无法添加该点（即final 为true），则返回-1。
注意： 若要使用setChannelData() 方法为该点关联附加数据，则必须使用该 返回的索引。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
[invokable] QVariantList QVirtualKeyboardTrace::channelData(const QString &channel, int pos = 0, int count = -1) const
从指定的channel 中返回数据。如果未提供其他参数，该方法将返回所有数据。
如果提供了pos 参数，该方法将从该位置开始返回数据。count 参数用于限制返回的项目数量。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
另请参阅 setChannelData()。
[invokable] QVariantList QVirtualKeyboardTrace::points(int pos = 0, int count = -1) const
返回点列表。如果未提供任何参数，该方法将返回所有数据。
如果提供了pos 参数，该方法将返回从该位置开始的点。count 参数用于限制返回的点数。
返回的列表包含QPointF 类型的点。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QVirtualKeyboardTrace::setChannelData(const QString &channel, int index, const QVariant &data)
为给定数据channel 中位于index 的点设置data 。
如果未针对每个数据点调用此方法，通道数据将被填充为空值。但是，数据不能在任意索引处添加，即必须与点数据同步添加。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
另请参阅 channelData()。
[invokable, since 6.1] void QVirtualKeyboardTrace::startHideTimer(int delayMs)
启动一个定时器，用于在delayMs 之后将不透明度设置为零。如果在delayMs 内再次调用该函数，则定时器将重新启动。
借助此函数，输入法可在销毁跟踪对象之前将其从屏幕上隐藏，例如，以此表示该跟踪已处理完毕。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
该函数在 Qt 6.1 中引入。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
