Qt便捷API

Qt便利函数参数

一些Qt便利函数可以接受一个modifierState参数，该参数指示鼠标点击时按下了哪些特殊键。某些函数也可以接受一个button参数，该参数指示哪个鼠标按钮被点击。

modifierState可以是一个或多个以下值之一：Qt.NoModifier、Qt.AltModifier、Qt.ControlModifier、Qt.KeypadModifier、Qt.MetaModifier、Qt.ShiftModifier。如果使用了多个，它们必须使用OR运算符组合起来，例如，Qt.AltModifier|Qt.ShiftModifier。此处所示的形式适用于Python和JavaScript。对于Perl和Ruby，请将点号替换为两个冒号，例如，Qt::ControlModifier，对于Tcl，请使用enum函数，例如，enum Qt ControlModifier。

button可以是以下任何一个：Qt.NoButton、Qt.LeftButton、Qt.MidButton、Qt.RightButton。

• 对于Perl，请使用以下语法：Qt::LeftButton。
• 对于Ruby，请使用以下语法：Qt::LEFT_BUTTON。
• 对于Tcl，请使用以下语法：enum Qt LeftButton。

KDE上的原生对话框

为了确保测试记录和回放的最可靠性，Squish使用Qt自己的对话框（例如，用于选择颜色、文件和字体），而不是底层平台的原生对话框。

不幸的是，在KDE上，Qt使用KDE对话框，这可能会在跨平台测试脚本开发时引起问题。解决方法是设置环境变量QT_PLATFORM_PLUGIN为无效值，例如，QT_PLATFORM_PLUGIN=nonesuch。例如，可以在squishide的测试套件设置视图的环境部分中完成此操作。

Qt便利函数

以下是Qt便利API函数的快速链接

activateItem(itemObject)

activateItem(objectOrName, itemText)

此函数激活指定的itemObject或由objectOrName表示的弹出菜单、上下文菜单或菜单栏中的指定itemText项。

表示键盘快捷方式的空格字符(&)不应包含在项目文本中。如果字符串中的字符使用下划线(_)格式化，表示程序内的文本包含&，则请将文本写入不带特殊字符或格式的形式。例如，对于"&Add"，请写"Add"。

激活链接(objectOrName, Url)

此函数会激活在对象objectOrName中指定URL地址的链接。该函数适用于QTextBrowser和QLabel及其子类。

QObject castToQObject(object)

此函数将对象object转换为QObject。对象必须是QObject或QGraphicsItem的子类，或者从QGraphicsItem派生的类，并且QObject是最先继承的。在QGraphicsObjects和QGraphicsWidgets上，由于Squish已经知道这些既是QObject也是QGraphicsItems，因此无需使用此函数。

不幸的是，QGraphicsItem不提供反射支持。这意味尽管Squish提供了对所有内置的QGraphicsItem类及其属性和方法的完全访问权限，包括它们继承自QObject的属性和方法，以及当使用castToQObject函数时——但你添加到自己的QGraphicsItem子类中的任何属性或方法都无法被Squish访问。

要查看测试Qt的图形/视图类的示例，请参阅如何测试图形视图、图形场景和图形项。

clickButton(objectOrName)

此函数点击指定的objectOrName按钮。

clickItem(objectOrName, itemOrIndex, x, y, modifierState, button)

此函数在给定objectOrName视图文本中指定itemOrIndex的的项目上模拟鼠标点击。该函数通常用于访问列表、表格和树等视图中项目。

对于表格而言，itemOrIndex是一个格式为的字符串，例如，"4/21"。对于树视图，itemOrIndex是由点号"."分隔的段列表。每个段可以包含一个可选的后缀_X，其中X被解释为基于1的索引位置。如果涉及的树项文本中包含点号"."、下划线"_"或反斜线"\"字符，则必须在itemOrIndex中分别将这些字符转义为"\."、"\_"和"\\"以避免它们被视为特殊字符。（请注意，脚本解释器可能需要对反斜线"\"进行额外的转义。）段的顺序对应于返回项的树路径。例如，"Item1.Sub\.ItemX_3.Leaf"将找到文本为"Leaf"的项，它是根节点文本为"Item1"的第三级子项"Sub.ItemX"的直接子项。对于其他视图，它是对应项的文本。

startDrag(sourceObject, sx, sy)
mouseMove(otherObject, x, y)
dropOn(targetObject, tx, ty, action)

function main()
{
    //...

    mouseMove(waitForObject(":target_object_name"), 5, 5);
    mousePress(waitForObject(":target_object_name"));
    snooze(3);
    mouseRelease(waitForObject(":target_object_name"));

    //...
}

返回与对象关联的QQmlEngine或在没有与之关联的对象时返回null。这相当于QQmlEngine::contextForObject(object)->engine()，但更高效。《code translate="no">QQmlEngine类提供了一个实例化QML组件的环境。

readGesture(gesture-file)

此函数从测试套件目录中打开一个手势文件，并返回一个GestureBuilder对象。然后可以将其传递给gesture(objectOrName, touches)。指定的gesture-file是指定文件名。

scrollTo(objectOrName, position)

此函数将objectOrName小部件滚动到指定的position。该position是一个绝对值（即，像素偏移）。

sendEvent(eventName, objectOrName, ...)

该函数向 objectOrName 小部件发送类型为 eventName 的事件。所有其他参数（...）都传递给事件构造函数——它们通常是坐标、按钮状态等。eventName 是 Squish 支持的所有 Qt 事件之一——这包括所有最常用的，如，"QCloseEvent"、"QHideEvent"、"QKeyEvent"、"QMouseEvent"、"QMoveEvent"、"QShowEvent"、"QTabletEvent" 和 "QWheelEvent"。

setFocus(objectOrName)

此方法将键盘输入焦点切换到由 objectOrName 指定的对象。

目前，键盘输入焦点切换在类型为 QQuickItem、QWidget 和 QWindow 的对象上是受支持的。

setMouseTracking(className, onOrOff)

此函数可用于 init 文件中，用于禁用或启用某些小部件类 MouseMove 事件的记录。禁用或启用鼠标跟踪的类由 className 参数指定。通过传递值为 true 的 onOrOff 参数来启用鼠标跟踪，或传递值为 false 的参数来禁用鼠标跟踪。（默认情况下，鼠标跟踪是关闭的。）

包装器特定初始化

init 文件是用 Tcl 编写的脚本，它们与 squishrunner 注册并在开始任何测试之前读取。注册过程在 配置 squishrunner 中进行说明。尽管 init 文件必须用 Tcl 编写，但这不会影响测试套件使用的脚本语言，测试套件可以使用 Squish 支持的任何脚本语言。

我们可以为每个 GUI 工具包有任意多的 init 脚本，或者我们可以为每个工具包放入单个 Tcl 脚本中的所有初始化语句。但是，无论我们使用多少个 init 脚本，都必须将它们全部注册到 squishrunner 上。

示例

setMouseTracking ScribbleArea true

此示例为 AUT 的自定义 ScribbleArea 类开启鼠标跟踪。

为了使这项工作正常，我们必须告诉 Squish，在用其测试基于 Qt 的 AUT 时，启动时执行包含此 Tcl 脚本的文件。

squishrunner --config addInitScript Qt /home/harri/qt_init1.tcl

必须使用绝对路径。

setRecordMouseDrag(className, onOrOff)

此函数可用于 init 文件中来禁用或启用某些小部件类的 mouseDrag 语句的记录。禁用鼠标拖动的类由 className 参数指定。传递一个值为 true 的 onOrOff 参数来启用鼠标拖动记录，或者传递一个值为 false 的参数来禁用鼠标拖动记录。（默认情况下，鼠标拖动记录是开启的。）

另请参阅 包装器特定初始化。

init 文件是用 Tcl 编写的脚本，它们与服务器注册并在开始任何测试之前读取。注册过程在 配置 squishrunner 中进行说明。

示例

setRecordMouseDrag ScribbleArea false

此示例为 AUT 的自定义 ScribbleArea 类关闭鼠标拖动记录。

为了使这项工作正常，我们必须告诉 Squish，在用其测试基于 Qt 的 AUT 时，启动时执行包含此 Tcl 脚本的文件。

squishrunner --config addInitScript Qt /home/harri/qt_init2.tcl

必须使用绝对路径。

setWindowState(objectOrName, windowState)

此函数将特定于 objectOrName 窗口的状态设置为 windowState 枚举指定的状态。

请注意，此函数仅适用于顶级窗口。

有效的窗口状态值有：WindowState.Fullscreen、WindowState.Maximize、WindowState.Minimize以及WindowState.Normal。

上述表单适用于Python和JavaScript。

对于Perl，使用以下代码：WindowState::Maximize等。

对于Ruby，使用以下代码：WindowState::MAXIMIZE等。

对于Tcl，使用以下代码：enum WindowState Maximize等。

spinUp(objectOrName)

此函数在objectOrName微调框的“向上”按钮上点击。该函数适用于QAbstractSpinBox及其子类，如QSpinBox和QDoubleSpinBox。

spinDown(objectOrName)

此函数在objectOrName微调框的“向下”按钮上点击。该函数适用于QAbstractSpinBox及其子类，如QSpinBox和QDoubleSpinBox。

startDrag(source_objectOrName, sx, sy)

此函数在位置sx和sy（在source_objectOrName微调框的坐标中）处启动source_objectOrName小部件的拖动。可以使用dropOn(target_objectOrName, tx, ty, action)函数执行放置。

tapObject(objectOrName)

tapObject(objectOrName, x, y)

tapObject(objectOrName, x, y, modifiers)

此函数在指定的objectOrName小部件上进行点击。坐标x、y以及键盘修饰符modifiers都是可选的。如果没有指定，则在不受键盘修饰符影响的情况下在部件的中心进行点击。另一方面，如果提供了额外的坐标参数，则点击在objectOrName部件的x和y位置进行。

点击支持类型为QQuickItem、QWindow和QWidget的对象。

touchAndDrag(objectOrName, x, y, dx, dy)

touchAndDrag(objectOrName, x, y, dx, dy, modifiers)

touchAndDrag(objectOrName, x, y, dx, dy, modifiers, delayAfterPress)

此函数执行基于触摸的拖动操作。在指定位置启动对objectOrName小部件的触摸拖动操作，位置为x和y（在objectOrName小部件的坐标中）。垂直方向上拖动dx像素，水平方向上拖动dy像素。

如果指定，则在进行拖动时设置在modifiers中提供的键盘修饰符。

如果指定，则在开始拖动之前等待delayAfterPress提供的毫秒数。

基于触摸的拖动支持类型为QQuickItem和QWindow的对象。

touchPress(对象或名称, x, y)

touchPress(对象或名称, x, y, 按键修饰符)

此函数执行基于触摸的按下操作。它在指定位置的位置 x 和 y（在 objectOrName 组件的坐标下）上重新播放对指定 objectOrName 组件的触摸按下操作。

如果指定，则在执行操作时设置 modifiers 中提供的键盘修饰符。

由于对象和 Qt 本身都依赖于按下和释放操作始终成对发生，因此对 touchPress 的调用应始终与对 touchRelease 的调用配对，以确保一致的状态。对于大多数情况，仅使用 tapObject 就足够了。

可以在类型为 QQuickItem 和 QWindow 的对象上执行单个触摸按下。

touchRelease(对象或名称, x, y)

touchRelease(对象或名称, x, y, 按键修饰符)

此函数执行基于触摸的释放操作。它在指定位置的位置 x 和 y（在 objectOrName 组件的坐标下）上重新播放对指定 objectOrName 组件的触摸释放操作。

如果指定，则在执行操作时设置 modifiers 中提供的键盘修饰符。

由于对象和 Qt 本身都依赖于按下和释放操作始终成对发生，因此在 touchRelease 的调用之前应始终调用 touchPress，以确保一致的状态。对于大多数情况，仅使用 tapObject 就足够了。

可以在类型为 QQuickItem 和 QWindow 的对象上执行单个触摸释放。

type(对象或名称, 文本)

此函数将指定的 text（就像用户使用键盘一样）输入到可编辑的 objectOrName 组件中。如果文本被尖括号包围，它被解释为一个键盘组合，例如 "<Ctrl+Return>"。输入是区分大小写的，因此 type(object, "R") 与 type(object, "r") 不同。（有关支持的特定键的列表，请参阅 nativeType(keys) 函数的文档。）

与 nativeType(keys) 不同，type() 将所有平台上的 Ctrl 和 Command 视为相同的键。这意味着您可以在测试脚本中编写 type("<Ctrl+c>")，它在 Linux 和 Windows 上会产生 Ctrl+r，而在 macOS 上会产生 Command+r。反过来，为了使 Squish 在 macOS 上按下实际的 Ctrl 键，您需要使用 Qt 术语： type("<Meta+r>")。

uninstallEventHandler(事件名称, 处理函数名称)

uninstallEventHandler(类名称, 事件名称, 处理函数名称)

uninstallEventHandler(对象, 事件名称, 处理函数名称)

此函数卸载使用 installEventHandler(eventName, handlerFunctionName) 之前安装的事件处理程序。

uninstallSignalHandler(objectOrName, signalSignature, handlerFunctionName)

此函数可卸载数据库中先前通过使用 installSignalHandler(objectOrName, signalSignature, handlerFunctionName) 安装的信号处理器。

uninstallLazySignalHandler(name, signalSignature, handlerFunctionName)

该函数卸载数据库中先前通过使用 installLazySignalHandler(name, signalSignature, handlerFunctionName) 安装的信号处理器。

waitForSignal(object, signalSignature)

waitForSignal(object, signalSignature, timeoutMSec)

此函数等待给定的模型对象发出 Qt（不是 Unix！）信号。该 object 是对象的引用，可以从中获得其中一个返回对象引用的函数（例如，Object waitForObject(objectOrName) 或 Object findObject(objectName)。该 signalSignature 必须是一个字符串，并包含与 C++ 中使用的确切签名相同的内容（无参数名）（有关有效签名的示例，请参阅 installSignalHandler(objectOrName, signalSignature, handlerFunctionName)）。等待循环的持续时间由 testSettings.waitForObjectTimeout 属性定义，或者如果使用可选的 timeoutMSec 参数，则为这么多毫秒。如果在给定的超时时间内信号没有到达，将引发（可捕获）RuntimeError 异常。

waitForSignal(waitForObject(names.window_Window), "titleChanged()")

waitForSignal(waitForObject(names.windowWindow), "titleChanged()")

waitForSignal(waitForObject($Names::window_window), "titleChanged()");

waitForSignal(waitForObject(Names::Window_Window), "titleChanged()")

invoke waitForSignal [waitForObject $names::window_Window] "titleChanged()"

QWebView 类

Squish 通过三个附加方法为 QWebView 类提供额外的支持。

Object QWebView.clearObjectCache()

此函数清除使用类似 document.html1.body1.div2 这样的层次名称查找的对象缓存。另请参阅 clearObjectCache()。

Object QWebView.evalJS(code)

此函数在分配的 QWebView 的上下文中计算 (即，在活动 QWebView 页面的上下文中) JavaScript code 字符串。返回代码中最后一个声明的结果作为字符串。另请参阅 如何使用 evalJS。

Object QWebView.retrieveJSObject(code)

此函数在分配的 QWebView 的上下文中计算 (即，在活动 QWebView 页面的上下文中) JavaScript code 字符串。返回代码中最后一个声明的结果作为一个原始值，例如一个字符串或数字，或者页面上 JsObject 的引用。（另请参阅 如何使用 retrieveJSObject 和 JsObject retrieveJSObject(javascriptcode)。）

Boolean QWebView.isPageLoaded()

此函数返回 true，表示页面已完全加载；否则返回 false。完整且成功加载意味着页面的所有对象都可以 潜在地 被访问。此函数可与 Boolean waitFor(condition) 函数结合使用，在测试脚本访问页面前等待页面加载。

由于页面加载、HTTP请求等操作是异步的，即使 isPageLoaded 函数调用返回 true，仍然需要使用 Object waitForObject(objectOrName) 函数（或其他等待函数）来确保感兴趣的特定对象或对象已准备好被访问。另外，可能需要将 Object waitForObject(objectOrName) 函数的超时时间设置得比默认的20秒（20,000毫秒）更长。另请参阅 如何同步网页加载用于测试。

QWebView.loadUrl(url)

此函数将 QWebView 的当前页面更改为新的 url。

QML扩展API

使用 QtQuick 的 Qt 应用程序可以动态加载 QML 代码，包括自定义 QML 对象，因此使用 QML 的 AUT 可能会包含 Squish 所不知道的 QML 对象。这并不是问题，因为 Squish 仍然可以记录和回放与这些对象的交互，只是会用它们构建的原始元素（例如，矩形或文本项）来表示，而不是实际的（逻辑）元素类型（例如，自定义按钮）。

QML扩展API使得 Squish 能够将某些自定义QML对象类型视为“黑箱”，从而可以在较高层面（即，使用自定义对象本身的术语而不是它们构建的原始元素）进行记录和回放。Squish 随带一个小的示例，它使用了某些 QML扩展API，并展示了如何为自定义计算器 Button 类型实现 SquishHook：SQUISHDIR/examples/qt5/calqlatr/extension/Calqlatr.qml。

Squish 还包括一个支持 QtQuick 控件的更全面的 QML 扩展，位于 SQUISHDIR/lib/extensions/qt/qtquick/ControlsExt.qml。

QML扩展的格式

QML扩展是标准 QML 脚本，存储在 .qml 文件中（使用UTF-8编码），并使用 Squish 提供的一些附加功能。在 QtQuick 1.x 中，Squish QML 扩展的结构如下所示：

import Qt 4.7
import com.froglogic.squish.qml 0.1

SquishHook {
    // extension code...
}

在 QtQuick 2.x 中，QML扩展的基本结构如下：

import QtQuick 2.0
import com.froglogic.squish.qtquick 0.1

SquishHook {
    // extension code...
}

安装 QML 扩展

Squish 会自动在 SQUISHDIR/lib/extensions/qt/qml 目录中查找针对 QtQuick 1.x 的扩展文件，并在 SQUISHDIR/lib/extensions/qt/qtquick 目录中查找针对 QtQuick 2.x 的扩展文件。要“安装”新的 QML 扩展，只需将其移动或复制到这些目录之一即可。还可以为 Squish 添加一个额外的目录来搜索 QML 扩展：设置 SQUISH_QML_EXTENSION_PATH 环境变量（可能需要创建），将其设置为要保存您的 QtQuick 1.x QML 扩展的目录。对于 QtQuick 2.x，而不是设置 SQUISH_QTQUICK_EXTENSION_PATH 环境变量到您保存 QML 扩展的目录。

QML扩展API文档

Squish 的 QML 扩展API由一个类型为 SquishHook 的单项组成。此项提供了以下列出的的各种属性和函数。自定义 QML 扩展可以使用这些属性和函数——在某些情况下还可以覆盖它们。此外，Squish 还提供了一些辅助函数，使编写 QML 扩展变得更加容易。

QtQuick 1.x API 使用在 Qt 4.8 参考文档中指定的 QML 基础类型 和 元素。

QtQuick 2.x API 使用在 Qt 5.x 参考文档中指定的 QML 基础类型 和 项目。

bool isCustomQmlType(item)

此函数返回给定的类型为 Item 的 item 是否是自定义类型。 (Qt（以及此函数）将引入新属性的每个 QML 项目视为自定义 QML 类型。)

bool isQmlType(item, className)

此函数返回类型为 Item 且由 className 字符串指定的类是否被给定的 item 继承。

bool itemHasContents(item)

此函数返回给定的类型为 Item 的 item 是否设置了 QQuickItem::ItemHasContents 标志。这是一个辅助函数，可以在 QML 中访问此特定标志。它可以用作一个提示，是否默认忽略某个项目。也可参见 Flag 枚举。

String qmlId(item)

此函数返回给定 item 的 id 或空字符串（如果 item 未设置 id）。

String qmlType(item)

如果给定的 item 类型为 Item 是声明性类型，则此函数返回它的类名；否则返回空字符串。

String source(item)

如果项目是从本地文件或远程加载的，则此函数返回给定类型为 Item 的 item 的 URL；否则返回包含此 item 的组件的 URL（这可能是一个空字符串）。

SquishHook

SquishHook 类是一个抽象类，用于扩展自定义 QML 扩展。

readonly property var SquishHook.blacklistedTypes

此变量可以包含一个字符串列表，其中包含希望此扩展忽略的 QML 类型。

readonly property var SquishHook.containerTypes

某些类型可以成为其他类型的容器。如果您正在与容器类型的子类型交互，则应该在 Squish 为该子类型生成的真实名称中看到 container=，指向其容器。

在此属性中，您可以指定一个字符串列表，包含可以成为其所有子类型容器类的类型名称。

此属性用于简单情况，其中给定类可以根据其类名始终是容器类型。

如果您需要查看属性来确定某物是否为特定项目的容器，则应改用覆盖 containerFor() 函数而不是使用此属性。

Item SquishHook.containerFor(item)

此函数返回包含给定 item 类型的容器（自身也是类型 Item，例如 ListView 或 GridView），这通常是 item 的父容器；否则如果没有 item 在容器中，则返回 null。

您可以在您的 QML 扩展中实现此函数的版本，在这种情况下，对于任何给定的 item，您必须返回以下三个值之一：一个包含给定 item 的 Item（可能为您自己的自定义类型）。或者，如果不需要给定 item 有一个容器（在这种情况下，视图将视为 item 的容器），则返回 null。或者，返回特殊值 unhandled，如果您不希望此扩展处理给定的 item（例如，因为它是一个您希望 Squish 处理的标准 Item 类型），因为 unhandled 告诉 Squish 自己处理 item。

StringList SquishHook.extraPropertiesFor(item)

此函数返回给定类型为 Item 的 item 的属性名称列表，应考虑在为 item 生成 Squish 对象名称时。 (此函数可用于达到与编辑 Qt 包装描述文件相同的命名控制，有关详细信息，请参考 对象名称生成—但可能的控制更精细，因为可以在每个项目的基础上考虑属性名称，而不仅仅是每个类型。)

您可以在您的 QML 扩展中实现此函数的版本，在这种情况下，对于任何给定的 item，您必须返回以下两种选择之一：一组属性名称（作为字符串数组），用于创建给定 item 的 Squish 对象名称。或者，返回特殊值 unhandled，如果您不希望此扩展处理给定的 item（例如，因为它是一个您希望 Squish 处理的标准 Item 类型），因为 unhandled 告诉 Squish 自己处理 item。

bool SquishHook.isIgnored(item)

如果给定的类型为 Item 的 item 应由 Squish 注意到（例如，在 Spy 中可视且可拾取，并被记录），则此函数返回 false。

您可以在您的 QML 扩展中实现此函数的版本，在这种情况下，对于任何给定的 item，您必须返回以下三个值之一：如果想让 Squish 注意到给定的 item，则返回 false；如果想让 Squish 忽略 item，则返回 true；或者，如果不想此扩展处理给定的 item（例如，因为它是一个您希望 Squish 处理的标准 Item 类型），则返回特殊值 unhandled，因为 unhandled 告诉 Squish 自己处理 item。

bool SquishHook.isItemReady(item)

如果给定的类型为 Item 的 item 已准备好被交互，即它可见、启用了，并且处于稳定状态（例如，它不是正在或即将被动画化），则此函数返回 true。

您可以在自己的QML扩展中实现此函数的版本，在此情况下，对于任何给定的item，您必须返回以下三个值之一：如果给定的item已准备好交互，则返回值true，或者false表示item尚未准备好，或者特殊值unhandled，如果您不希望此扩展处理给定的item（例如，因为它是一个您希望Squish处理的普通Item类型），因为unhandled会告诉Squish自己处理item。

只读属性 var SquishHook.objectNameProperties

此变量应是一个包含键：值对的{字典}，其中键是一个"字符串"，表示QML类型名，而值是该类型的[列表]属性的字符串名称，应在将其添加到对象映射（在记录时间）时用于生成真实名称。

此仅适用于QML的功能与qtwrapper_descriptors.xml类似，它适用于所有Qt类型。

int SquishHook.priority

此属性用于QML扩展的优先级值，默认值为0。Squish按从高到低的优先级顺序访问QML扩展。

您可以在自己的QML扩展中实现此属性的版本，以给您的扩展一个大于0的优先级值，例如，为了提高其优先级。

String SquishHook.propertyFor(item, property)

此函数返回给定类型的Item的property（指定为字符串）的属性值（作为字符串）。

您可以在自己的QML扩展中实现此函数的版本，在此情况下，对于任何给定的item和property，您必须返回以下之一：一个字符串属性值，或者特殊值unhandled，如果您不希望此扩展处理给定的item（例如，因为它是一个您希望Squish处理的普通Item类型），因为unhandled会告诉Squish自己处理item。

注意，当在测试脚本中使用object.property("propertyName")函数时，不会调用此函数。

只读属性 var SquishHook.whitelistedTypes

此变量可以包含一个字符串列表，这些字符串是您希望在Squish选择对象时优先考虑的QML类型（而不是其更原始的子类型）。

GestureBuilder

此类型的对象包含重放gesture(objectOrName, touches)所需的触摸笔触信息。通过readGesture(gesture-file)返回此类的实例。笔触由屏幕坐标点、压力和触摸大小定义。

int GestureBuilder.areaWidth

此手势定义区域的宽度。这将等于设备或模拟器的屏幕宽度。

int GestureBuilder.areaHeight

此手势定义区域的高度。这将等于设备或模拟器的屏幕高度。

在《Gesture 创建》和《Gesture 操作》章节中列出的所有 GestureBuilder 方法，在除非有別的说明的情况下，都会返回 GestureBuilder 对象本身。

Gesture 创建

本节列出手动创建一个 GestureBuilder 对象的方法。

GestureBuilder(width, height, unit)

GestureBuilder(xml)

创建了两个创建 GestureBuilder 对象的构造函数。参数 width 和 height 是目标屏幕尺寸。unit 可以是 0 或 1，分别表示像素或毫米。可以使用常数 GestureBuilder.Pixel 和 GestureBuilder.MilliMeter。

第二个构造函数通过传递包含 XML 的字符串来构建一个 GestureBuilder 对象，XML 应与记录的手势文件格式相同。

Object GestureBuilder.addStroke(x, y)

Object GestureBuilder.addStroke(startTime, x, y)

Object GestureBuilder.addStroke(startTime, x, y, pressure)

Object GestureBuilder.addStroke(startTime, x, y, pressure, size)

开始一个新的笔迹。从接触屏幕到释放整个过程，一只手指或笔的一整个移动被称为笔迹。接触坐标是 (x, y)。对于非第一笔迹，可以使用参数 startTime 指定时间偏移，单位是毫秒。笔迹在时间上不能断开，整个手势过程中至少有一个手指或笔要按下。最大同时接触数取决于设备（见 QTouchDevice::maximumTouchPoints()）。

最后，pressure 和 size 分别表示笔或手指的压力和大小，它们是相对计量值。这些值应该在 0.0 到 1.0 之间，如果省略，默认值为 0.25。

Object GestureBuilder.curveTo(duration, controlX, controlY, endX, endy)

Object GestureBuilder.curveTo(duration, control1X, control1Y, control2X, control2Y, endX, endy)

在最新的笔迹中添加一个二次贝塞尔曲线运动，持续时间为 duration 毫秒。曲线从最后添加的运动结束坐标开始，如果没有添加任何运动到笔迹中，就从笔迹的接触坐标开始。结束坐标用 endX 和 endY 指定。可以使用一个或两个控制点。

Object GestureBuilder.lineTo(duration, endX, endy)

在最新的笔迹中添加一个直线运动，持续时间为 duration 毫秒。直线从最后添加的运动结束坐标开始，如果没有添加任何运动到笔迹中，就从笔迹的接触坐标开始。结束坐标用 endX 和 endY 指定。

Object GestureBuilder.build()

从添加的笔迹和运动中创建手势。调用此方法后，无法再添加笔迹或运动。

Gesture 操作

Object GestureBuilder.accelerate(factor)

根据一个系数改变笔触速度。介于0.0和1.0之间的系数会减慢手势，大于1.0则会加快手势。

Object GestureBuilder.rotate(degrees)

Object GestureBuilder.rotate(degrees, originX, originY)

旋转笔触。参数degrees是以逆时针方向计算的角度。参数originX和originY定义旋转操作的基点。如果省略，则取区域中心作为基点。

Object GestureBuilder.scale(scale)

Object GestureBuilder.scale(scaleX, scaleY)

Object GestureBuilder.scale(scaleX, scaleY, originX, originY)

改变笔触大小。参数scaleX是水平方向的缩放系数，而scaleY是垂直方向的缩放系数。参数originX和originY定义缩放操作的基点。如果省略，则取区域中心作为基点。当同时省略scaleY时，则在两个方向上进行均匀缩放。

Object GestureBuilder.translate(x, y)

移动笔触。参数x和y指定移动。正值的x将笔触向右移动，而正值的y将笔触向下移动。