Windows便捷API

Windows 实用函数参数

对于所有接受 objectOrName 参数的 Windows 实用 API 函数，此参数可以是一个对象的引用或对象名称——对象必须是（或命名为）一个本地 Windows 对象。

一些 Windows 实用 API 函数可以接受一个 modifierState 参数，该参数指示鼠标单击时按下的特殊键。某些函数还可以接受一个 mouseButton 参数，指示哪个鼠标按钮被单击。

modifierState 可以是以下之一：Modifier.NoModifier，Modifier.Alt，Modifier.Control，Modifier.Shift。如果使用多个，它们必须进行 OR 操作，例如，Modifier.Alt|Modifier.Shift。此处显示的形式例如 Modifier::Control，Tcl 使用 enum 函数，例如 enum Modifier Control。

mouseButton 可以是以下任何一个：MouseButton.NoButton，MouseButton.Wheel，MouseButton.LeftButton，MouseButton.MiddleButton，MouseButton.RightButton，MouseButton.XButton1。 MouseButton.XButton2。

上述格式适用于 Python 和 JavaScript。

对于 Perl，请使用此：MouseButton::LeftButton，等等。

对于 Ruby，请使用此：MouseButton::LEFT_BUTTON，等等。

对于 Tcl，请使用此：enum MouseButton LeftButton，等等。

Windows 实用 API 函数和属性

以下是 Windows 实用 API 的函数和属性的快速链接

chooseFile(path)

此函数自动操作原生文件选择对话框。它假设已打开（或将打开）一个对话框，然后自动选择由 path 指定的文件路径。可以使用空字符串来模拟文件对话框被取消。

函数将等待最多 3 秒打开一个对话框。如果在 3 秒内未打开对话框，或者指定的路径名称过长，将引发异常。

函数等待打开对话框的持续时间可由 etc\winwrapper.ini 配置文件中的设置“Native File Dialog Script Call Timeout (ms)”配置。该设置可调整到不同的阈值。

clickButton(objectOrName)

此函数单击 objectOrName 小部件，该小部件应为按钮名称或按钮对象的引用。

clickItem(objectOrName, itemText)

clickItem(objectOrName, itemText, mouseButton)

clickItem(objectOrName, itemText, mouseButton, modifierState)

此函数会点击具有指定 itemText 的 objectOrName 小部件的项目。这将适用于具有 text 属性的任何小部件。

默认情况下使用 MouseButton.LeftButton，但可以通过指定可选的 mouseButton 参数进行更改。同样，默认情况下使用 Modifier.NoModifier 的修饰符状态，但可以通过指定 modifierState 参数进行更改。注意，要指定修饰符，必须还指定按钮。有关 mouseButton 参数和 modifierState 参数的有效值，请参阅 Windows Quick Function 参数。

collapse(objectOrName)

如果 objectOrName 是树或树项，则将其折叠以隐藏其所有子项目（如果有的话）。如果 objectOrName 是组合框，则其项目弹出列表将被隐藏。（另见 collapseItem(objectOrName, itemName)、expandItem(objectOrName, itemText) 和 expand(objectOrName)。）

collapseItem(objectOrName, itemName)

objectOrName 应该是树或树项。它将被折叠，以隐藏具有指定 itemText 的项目的所有子项。（另见 expandItem(objectOrName, itemText) 和 expand(objectOrName)。）

doubleClick(objectOrName)

doubleClick(objectOrName, x, y)

doubleClick(objectOrName, x, y, mouseButton)

doubleClick(objectOrName, x, y, mouseButton, modifierState)

此函数会双击 objectOrName 小部件。

默认情况下，凭点击小部件的中间，但可以通过传递相对坐标来更改，x 和 y。默认情况下使用 MouseButton.LeftButton，但可以通过指定可选的 mouseButton 参数进行更改。同样，默认情况下使用 Modifier.NoModifier 的修饰符状态，但可以通过指定 modifierState 参数进行更改。注意，要指定按钮，必须还指定坐标；要指定修饰符状态，必须还指定坐标和按钮。有关 mouseButton 参数和 modifierState 参数的有效值，请参阅 Windows Quick Function 参数。

doubleClickItem(objectOrName, itemText)

doubleClickItem(objectOrName, itemText, mouseButton)

doubleClickItem(objectOrName, itemText, mouseButton, modifierState)

该函数双击具有指定 itemText 的 objectOrName 小部件的项。这适用于任何拥有 text 属性的小部件。

默认情况下使用 MouseButton.LeftButton，但可以通过指定可选的 mouseButton 参数进行更改。同样，默认情况下使用 Modifier.NoModifier 的修饰符状态，但可以通过指定 modifierState 参数进行更改。注意，要指定修饰符，必须还指定按钮。有关 mouseButton 参数和 modifierState 参数的有效值，请参阅 Windows Quick Function 参数。

dragAndDrop(source_objectOrName, target_objectOrName)

dragAndDrop(source_objectOrName, sx, sy, target_objectOrName)

dragAndDrop(source_objectOrName, target_objectOrName, tx, ty)

dragAndDrop(source_objectOrName, sx, sy, target_objectOrName, tx, ty)

该函数执行拖放操作。它首先对 source_objectOrName 小部件发起拖动，然后在 target_objectOrName 小部件处放下。默认情况下，拖动从源对象的中间到目标对象的中间，除非提供特定坐标，在这种情况下，坐标将被尊重。

可以指定坐标集、两组坐标或都不指定。如果指定了源坐标，则拖动从 source_objectOrName 小部件的坐标中的 sx 和 sy 位置开始，如果指定了目标坐标，则在 target_objectOrName 小部件的坐标中的 tx 和 ty 位置执行放下操作。

expand(objectOrName)

如果 objectOrName 是一个树或树项，则扩展以显示其子项（如果有）。如果 objectOrName 是一个组合框，它将显示其项目弹出列表。（另见 expandItem(objectOrName, itemText)、collapseItem(objectOrName, itemName) 和 collapse(objectOrName)。）

expandItem(objectOrName, itemText)

objectOrName 应该是一个树或树项。它扩展以显示具有指定 itemText 的项及其子项（如果有）。（另见 collapseItem(objectOrName, itemName) 和 collapse(objectOrName)。）

gesture(objectOrName, touches)

该函数播放手势。指定的 objectOrName 可以指任何准备好用户交互的对象。手势相对于指定对象的左上角重新播放。指定的 touches 指的是 GestureBuilder 对象。

focusedWindow()

该函数返回具有键盘焦点的窗口的对象引用。（另见 setFocusedWindow(objectOrName)。）

installEventHandler(eventName, handlerFunctionNameOrReference)

该函数安装一个全局事件处理程序。当发生 eventName 类型的事件时，将调用在 handlerFunctionNameOrReference 中命名或引用的脚本函数。

eventName 可以是以下任何事件类型的名称

• 崩溃：如果 AUT 崩溃，则发生此事件。
• DialogOpened: 此事件在对话框窗口打开时发生；“对话框窗口”是一种具有以下（扩展）样式的窗口：DS_MODALFRAME + WS_EX_DLGMODALFRAME + WS_EX_WINDOWEDGE + WS_EX_CONTROLPARENT或DS_SYSMODAL + DS_SETFOREGROUND + WS_EX_TOPMOST + WS_EX_WINDOWEDGE + WS_EX_CONTROLPARENT（样式可以通过Visual Studio中的Microsoft Spy++工具检查）。
• MessageBoxOpened：当Squish检测到打开对话框窗口时发生（即，与DialogOpened事件的说明中给出的要求相同），但对话框窗口还匹配某种结构。确切的结构取决于特定的GUI工具包，但通常意味着对话框应只包含文本和一些标准按钮，例如确定和取消。
• Timeout：当达到Squish响应超时时发生。

名为handlerFunctionName的函数以单个参数调用——即事件发生的对象。

有关示例，请参阅如何使用事件处理器。

mouseClick(objectOrName)

mouseClick(objectOrName, mouseButton)

mouseClick(objectOrName, mouseButton, modifierState)

mouseClick(objectOrName, x, y, mouseButton)

mouseClick(objectOrName, x, y, mouseButton, modifierState)

此函数在指定的objectOrName小部件上执行鼠标点击。

如果只指定了objectOrName，则使用MouseButton.LeftButton在对象的中间点击。所有其他用法需要指定mouseButton，可跟对象相关坐标x和y，这些坐标表明点击发生的位置，并可跟一个可选的modifierState（如果未指定，则默认为Modifier.NoModifier）。

有关有效的mouseButton参数值和modifierState参数值的更多详细信息，请参阅Windows Convenience Function Parameters。

mouseDrag(objectOrName, dx, dy)

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

mouseDrag(objectOrName, x, y, dx, dy, mouseButton)

mouseDrag(objectOrName, x, y, dx, dy, mouseButton, modifierState)

此函数执行从objectOrName小部件到水平偏移dx像素和垂直偏移dy像素的位置的鼠标拖动（或在objectOrName小部件的坐标中如果指定了，从位置x，y）。如果您需要指定鼠标按钮或修改状态但不希望指定起点（因为对象的中心就足够了），请将x坐标和y坐标传递为0。

默认情况下，鼠标从对象的中心拖拽，但可以通过传递对象相对坐标x和y来改变此行为。拖拽的量，即dx和dy，必须指定。默认使用MouseButton.LeftButton，但可以通过指定可选的mouseButton参数来改变。同样，默认使用Modifier.NoModifier的修改器状态，但可以通过指定modifierState参数来改变。请注意，为了指定修改器，必须也指定按钮。请参见Windows Convenience Function Parameters，了解哪些值对于mouseButton参数和modifierState参数是有效的。

mousePress()

mousePress(mouseButton)

mousePress(mouseButton, modifierState)

mousePress(x, y, mouseButton)

mousePress(x, y, mouseButton, modifierState)

mousePress(objectOrName)

mousePress(objectOrName, mouseButton)

mousePress(objectOrName, mouseButton, modifierState)

mousePress(objectOrName, x, y, mouseButton)

mousePress(objectOrName, x, y, mouseButton, modifierState)

此函数执行鼠标点击操作。所有参数都是可选的，除了坐标必须同时存在或都不存在。

如果提供了x和y坐标，点击将在这些坐标处执行，如果指定了objectOrName对象，则相对该对象；否则相对于当前屏幕。如果没有提供坐标，则在指定了objectOrName对象的情况下在对象的中间执行点击，或者在鼠标当前位置执行点击。

默认使用MouseButton.LeftButton，但可以通过指定可选的mouseButton参数来改变。同样，默认使用没有修改器的修改器状态，但可以通过指定modifierState参数来改变。请参见Windows Convenience Function Parameters，了解哪些值对于mouseButton参数和modifierState参数是有效的。

mouseRelease()

mouseRelease(mouseButton)

mouseRelease(mouseButton, modifierState)

mouseRelease(x, y, mouseButton)

mouseRelease(x, y, mouseButton, modifierState)

mouseRelease(objectOrName)

mouseRelease(objectOrName, mouseButton)

mouseRelease(objectOrName, mouseButton, modifierState)

mouseRelease(objectOrName, x, y, mouseButton)

鼠标释放(objectOrName, x, y, mouseButton, modifierState)

此函数执行鼠标释放操作。所有参数都是可选的，除了坐标，必须同时提供或都不提供。

如果提供了 x 和 y 坐标，释放操作将在这些坐标处进行，如果指定了 objectOrName 对象，则相对于该对象，否则相对于当前屏幕。如果没有提供坐标，如果在指定了 objectOrName 对象的情况下释放操作将在对象中心进行，否则在鼠标当前所在的位置进行。

默认使用MouseButton.LeftButton，但可以通过指定可选的mouseButton参数来改变。同样，默认使用没有修改器的修改器状态，但可以通过指定modifierState参数来改变。请参见Windows Convenience Function Parameters，了解哪些值对于mouseButton参数和modifierState参数是有效的。

鼠标滚轮(n)

鼠标滚轮(n, modifierState)

此函数执行鼠标滚轮操作，模拟鼠标垂直滚轮的旋转。操作在当前鼠标位置进行。要将鼠标移动到指定位置，请使用 mouseMove(x, y) 函数。

车轮旋转的量由参数 n 指定。一个 n 值相当于一个车轮凹槽，大约是 15 度或鼠标滚轮事件的 120 个 delta 单位。n 的正值使车轮向上旋转（远离用户），负值则向下旋转（朝向用户）。

可以指定鼠标滚轮时的键盘状态，使用参数 modifierState。有关此参数有效值的详细信息，请参阅 Windows 方便函数参数。

对象原生对象

Squish 默认在每个 Windows 对象的属性列表中添加一个名为 nativeObject 的属性。原生对象提供对所有底层对象的方法和属性的访问。

有关如何使用 nativeObject 的示例，请参阅 如何使用 Windows API。

读取手势(gesture-file)

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

设置前景窗口(objectOrName)

此函数尝试将 objectOrName 窗口带到前台，即如果可能的话，将其置于任何重叠窗口的上方。

设置焦点窗口(objectOrName)

此函数将键盘焦点给予 objectOrName 窗口或将包含 objectOrName 小部件的窗口。 （另见 focusedWindow()。）

设置值(objectOrName, 整数)

此函数将 objectOrName 可编辑小部件的值设置为给定的 整数 值。

此函数可用于设置 spinbox 中的数值，或设置 TrackBar（滑动小部件）或 ScrollBar 的值。

输入文本(objectOrName, 文本)

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

uninstallEventHandler(eventName, handlerFunctionNameOrReference)

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

GestureBuilder

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

int GestureBuilder.areaWidth

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

int GestureBuilder.areaHeight

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

在手势创建和手势操作部分中列出的所有 GestureBuilder 方法，除非明确指定，否则都返回 GestureBuilder 对象。

Gesture creation

本节列出了用于手动创建 GestureBuilder 对象的方法。

GestureBuilder(width, height, unit)

GestureBuilder(xml)

创建 GestureBuilder 对象的两个构造函数。宽度和高度是目标屏幕大小。单位可以是 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 参数指定时间偏移量（以毫秒为单位）。笔迹在时间上不能断开，在整整个手势过程中至少要有一个手指或笔按下。最大同时触摸数为 10。

最后，压力和大小分别是笔或手指的压力和尺寸的相对测量值。这些值应在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()

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

手势操作

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`，正值会将笔画向下移动。