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 QtQuick.VirtualKeyboard.Styles 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) |
详细描述
轨迹为坐标数据和其他与单个描边相关的可选数据提供了数据模型。
跟踪对象的典型用例如下：
- TraceInputArea 或其他输入设备通过调用 () 方法启动跟踪事件。InputEngine.traceBegin
- 如果当前输入法接受该事件，则会创建跟踪对象并配置所需的数据通道（如果有）。
- TraceInputArea 为跟踪对象收集数据。
- TraceInputArea 调用 () 方法完成跟踪，并将跟踪对象传回输入法。InputEngine.traceEnd
- 输入法处理数据，并在不再需要时丢弃对象。
坐标数据通过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) 方法中构建的。
根据定义，跟踪对象最早可在InputMethod.traceEnd() (QML) 方法中销毁。
属性文档
canceled : bool
定义是否取消QVirtualKeyboardTrace 。
不应处理canceled 属性设置为 true 的跟踪中的输入数据。
访问功能：
| bool | isCanceled() const |
| void | setCanceled(bool canceled) |
Notifier 信号：
| 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 : const 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 的唯一 ID。
访问功能：
| int | traceId() const |
| void | setTraceId(int id) |
Notifier 信号：
| 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 QtQuick.VirtualKeyboard.Styles 6.1] void QVirtualKeyboardTrace::startHideTimer(int delayMs)
启动一个计时器，在delayMs 之后将不透明度设置为零。如果在delayMs 内再次调用，则重新启动计时器。
有了这个函数，输入法可以在销毁跟踪对象之前从屏幕上隐藏跟踪，例如，表明跟踪已被处理。
注： 可通过元对象系统和 QML 调用此函数。请参见Q_INVOKABLE 。
该函数在 QtQuick.VirtualKeyboard.Styles 6.1 中引入。
© 2025 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.
