基础类型对象的API

在上一篇中我们了解了CukeTest中的容器类和控件基类，接下来就是针对各种不同的控件类的API介绍了。本篇文章中将介绍以下几个基础的控件类：

• 按钮控件: Button
• 窗口控件: Window
• 标签控件: Label
• 输入框控件: Edit
• 单选按钮控件: RadioButton
• 复选框控件: CheckBox
• 组合框: ComboBox
• 选值框: SpinBox
• 应用控件: Application
• 进度条控件: ProgressBar
• 旋钮控件: Dial
• 滑动条控件: Slider
• 滚动区域控件: ScrollArea
• 图形视图控件: GraphicsView
• 菜单栏控件和菜单栏选项控件: MenuBar & MenuBarItem
• 菜单控件和菜单选项控件: Menu & MenuItem
• 标签栏控件和标签页控件: Tab & TabItem

而相对复杂的控件类有以下几个，由于包含的方法比较多，因此放到了其它文档中，请按照需求点击链接跳转：

• 列表类型对象: 介绍列表控件List和列表项控件ListItem;
• 树类型对象: 介绍树控件Tree和树节点控件TreeItem;
• 表格类型对象: 介绍表格控件Table和单元格控件TableItem;

以及以上三个复杂控件的基类自定义视图ItemView控件，针对Qt应用中从AbstractView抽象视图派生出来的自定义组件，介绍如下:

• 自定义视图对象: 介绍自定义视图控件ItemView和自定义项控件ItemViewItem;

由于各个控件类因为是继承自IQtControl，因此每个控件类都拥有[通用控件](node_operations.html#common-control]的所有操作和属性方法。以CheckBox控件类举例：

CheckBox控件有一个操作方法——check()用于设置是勾选还是清除勾选; 一个属性方法checked()用于判断CheckBox的勾选状态。true表示勾选，false代表未勾选:

export interface IQCheckBox extends IQtControl {
    toggleCheck(checkState: boolean): Promise<void>
    checkState(): Promise<boolean>
}

但实际上CheckBox除了这两个方法，还从IQtControl基类继承了所有的方法，所以CheckBox的方法实际上应该包含了基类的方法：

export interface IQCheckBox extends IQtControl {
    toggleCheck(checkState: boolean): Promise<void>
    checkState(): Promise<boolean>
    // 来自IQtControl  
    click(x?: number, y?: number, mousekey?: number): Promise<void>;
    dblClick(x?: number, y?: number, mousekey?: number): Promise<void>;
    moveMouse(x?: number, y?: number): Promise<void>;
    wheel(value: number): Promise<void>;
    takeScreenshot():Promise<string>;
    rect(): Promise<Rect> 
}

如果一个对象不包含任何操作和属性方法，代表它只适用其基类——也就是IQtControl和IQtContainer中的操作和属性方法而没有自己特有的，比如Button控件。

基础控件类介绍

按钮控件: Button

针对普通的按钮控件，模型管理器提供了Button对象类型。

export interface IQButton extends IQtControl {
}

由于Button控件的操作和属性方法与基类QtContainer的一致，没有自己特有的方法，因此为空。它的操作方法可以参考基类方法介绍。

窗口控件: Window

针对应用窗口控件，模型管理器提供了Window对象类型。

export interface IQWindow extends IQtControl {
    activate(): Promise<void>;
    close(): Promise<void>;
    maximize(): Promise<void>;
    minimize(): Promise<void>;
    restore(): Promise<void>;
}

activate(): Promise<void>

激活目标窗口，使目标窗口出现在桌面最上层，避免被其它窗口遮盖。

• 返回值: 不返回任何值的异步方法。

  由于CukeTest与Qt的桌面操作自动化是通过通信实现的，因此自动化操作不会因为Qt窗口被遮住而失效。

close(): Promise<void>

关闭目标窗口。

• 返回值: 不返回任何值的异步方法。

maximize(): Promise<void>

最大化目标窗口。

• 返回值: 不返回任何值的异步方法。

minimize(): Promise<void>

最小化目标窗口。

• 返回值: 不返回任何值的异步方法。

restore(): Promise<void>

恢复目标窗口。当目标最小化以后可以使用这个方法恢复为正常状态。

• 返回值: 不返回任何值的异步方法。

标签控件: Label

针对用于标示其它控件或显示固定内容的标签控件Label，没有操作方法，只有一个自己的属性方法：

export interface IQLabel extends IQtControl {
    text(): Promise<string>
}

text(): Promise<string>

获得标签当前的值。

• 返回值: Promise<string>类型，需要使用await关键字取出其中的结果。

输入框控件: Edit

针对用于接收用户输入的输入框控件Edit，没有区分单行输入框与多行输入框。提供的操作方法和属性方法都是针对输入框中的值。

export interface IQEdit extends IQtControl {
    set(value: String): Promise<void>;
    clearAll(): Promise<void>;
    value(): Promise<string>;
}

set(value): Promise<void>

设置输入框中的值。将目标输入框中的值替换为传入的字符串。

• value: String类型，期望写入到输入框的值；
• 返回值: 不返回任何值的异步方法。

clearAll(): Promise<void>

清除输入框中的值。

• 返回值: 不返回任何值的异步方法。

value(): Promise<string>

获取当前输入框中的值并返回。

• 返回值: Promise<string>类型，需要使用await关键字取出其中的结果。

单选按钮控件: RadioButton

针对单选按钮的RatioButton控件，按照使用逻辑提供了选中和获取选中状态的方法。

export interface IQRadioButton extends IQtControl {
    check(): Promise<void>;
    checked(): Promise<boolean>;
}

check(): Promise<void>

选中目标单选按钮。

• 返回值: 不返回任何值的异步方法。

checked(): Promise<boolean>

获取目标单选按钮的选中状态，true代表已选中，false代表未选中。

• 返回值: Promise<boolean>类型，代表目标复选框是否选中。需要使用await关键字取出其中的结果。

复选框控件: CheckBox

针对复选框控件的CheckBox控件，能够直接设定选中状态，当然也可以获取状态。

    export interface IQCheckBox extends IQtControl {
        toggleCheck(checkState: boolean): Promise<void>
        checkState(): Promise<boolean>
    }

toggleCheck(checkState): Promise<void>

设置目标复选框的选中状态。

• checkState: Boolean类型，true代表选中复选框，false代表取消选中目标复选框。
• 返回值: 不返回任何值的异步方法。

checked(): Promise<boolean>

获取目标单选按钮的选中状态，true代表已选中，false代表未选中。

• 返回值: Promise<boolean>类型，代表目标复选框是否选中。需要使用await关键字取出其中的结果。

组合框: ComboBox

针对带下拉框的一类特殊输入框的ComboBox控件，提供了选择指定下拉选项的操作方法。

export interface IQComboBox extends IQtControl {
    open(): Promise<void>;
    select(nameOrIndex: String | number): Promise<void>;
    selectedIndex(): Promise<number>;
    selectedName(): Promise<string>;
    items(): Promise<string[]>;
}

open(): Promise<void>

展开下拉框，可以视作触发了目标右侧的▼按钮。

• 返回值: 不返回任何值的异步方法。

select(nameOrIndex): Promise<void>

• nameOrIndex: number或String类型。如果为数字，则会选中下拉框中相应索引位置的选项；如果为字符串，则会选择下拉框中相应名称的选项。
• 返回值: 不返回任何值的异步方法。

selectedIndex(): Promise<number>

获取当前选中的值在下拉框中的位置。

• 返回值: Promise<number>类型，代表当前值在下拉框中的位置。需要使用await关键字取出其中的结果。

selectedItem(): Promise<string>

获取当前选中的值。

• 返回值: Promise<string>类型，代表当前选中的值。需要使用await关键字取出其中的结果。

itemsToSelect(): Promise<string[]>

获取目标组合框中所有可选选项的名称。

• 返回值: Promise<string[]>类型，即字符串数组，获取目标组合框中所有可选选项的名称。需要使用await关键字取出其中的结果。

选值框: SpinBox

针对应用中带上下箭头的选值框SpinBox控件，为其提供了触发其增加/减少值的操作API。

SpinBox控件继承自Edit控件，也就是说它除了以下的方法外，还能够使用Edit控件的方法。这点可以从类型文件中看出来。

该控件的类型定义如下:

export interface IQSpinBox extends IQEdit {
    increment(): Promise<void>;
    decrement(): Promise<void>;
}

increment(): Promise<void>

使取值框的值增加一个单位，单位大小取决于应用中的设置。可以理解为触发了一次取值框中的上箭头。

• 返回值: 不返回任何值的异步方法。

decrement(): Promise<void>

使取值框的值减少一个单位，单位大小取决于应用中的设置。可以理解为触发了一次取值框中的下箭头。

• 返回值: 不返回任何值的异步方法。

应用控件: Application

针对应用本身的一个控件，通常作为最顶层控件存在，提供了获取应用属性和操作应用的方法。

export interface IQApplication extends IQtControl {
    appInfo(): Promise<AppInfo>;
    pid(): Promise<number>;
    quit(): Promise<void>;
}
export interface AppInfo {
    appName: string,
    appPath: string,
    appVersion: string,
    pid: number,
}

appInfo(): Promise<AppInfo>

获取应用自身的信息，比如应用名称、版本、路径等等信息。

• 返回值: AppInfo类型，包含了应用名称、路径、版本和进程号的对象。

pid(): Promise<number>

获取应用的进程号。

• 返回值: number类型，进程编号。

quit(): Promise<void>

退出应用。会关闭应用以及属于应用的所有子窗口。

• 返回值: 不返回任何值的异步方法。

菜单栏控件和菜单栏选项控件: MenuBar & MenuBarItem

针对应用中的工具栏操作的MenuBar控件，以及工具栏中的按钮——MenuBarItem控件，通常只用于点击菜单按钮展开菜单栏。如果需要直接操作菜单选项，建议阅读菜单控件[Menu&MenuItem]的invoke()方法。

export interface IQMenuBar extends IQtControl {
    open(itemName: String): Promise<void>;
}
export interface IQMenuBarItem extends IQtControl {
    open(itemName: String): Promise<void>;
}

菜单控件和菜单选项控件: Menu & MenuItem

针对应用中的菜单和菜单选项的控件，Menu和MenuItem，操作菜单的选择、展开和隐藏。
关于菜单控件的定义如下，但最常用和关键的是invoke()操作方法，在后面进行介绍：

export interface IQMenu extends IQtControl {
    invoke(itemName: String): Promise<void>;
    show(): Promise<void>;
    hide(): Promise<void>;
    items(): Promise<string[]>;
}
export interface IQMenuItem extends IQtControl {
    invoke(): Promise<void>;
    toggleCheck(value: boolean): Promise<void>;
    checked(): Promise<boolean>;
    checkable(): Promise<boolean>;
    text(): Promise<string>;
    itemIndex(): Promise<number>;
    hover(): Promise<void>;
}

invoke(itemName): Promise<void>

直接触发目标菜单中的菜单项。在Menu控件中需要传入目标菜单项的名称；而在MenuItem控件中，不需要传入任何参数。

此方法不会展开菜单，而是通过通信直接触发目标菜单项功能，因此在用户角度不会观察到菜单的变化。

• itemName: 目标菜单项的名称，需要为目标菜单的一级菜单项；
• 返回值: 不返回任何值的异步方法。

以下是MenuItem对象的方法。

invoke(): Promise<void>

直接触发目标菜单项。

此方法不会展开菜单，而是通过通信直接触发目标菜单项功能，因此在用户角度不会观察到菜单的变化。

• 返回值: 不返回任何值的异步方法。

进度条控件: ProgressBar

针对应用中的进度条所支持的控件，可以通过调用value()方法取得进度条的值。

由于进度条的值通常是受控于内部逻辑或者其它控件，因此不支持直接修改其值。

形状如下:

类型文件如下:

export interface IQProgressBar extends IQtControl {
    value(): Promise<number>;
}

value(): Promise<number>

获取当前进度条中的值并返回。因为返回结果是数字，因此会省略百分比%号。

• 返回值: Promise<number>类型，需要使用await关键字取出其中的结果。

旋钮控件: Dial

针对用于手动调节值的旋钮控件，功能与滑动条控件类似，是Qt为了适配触屏应用推出的控件。 形状如下:

export interface IQDial extends IQtControl {
    value(): Promise<number>;
    setValue(value: number): Promise<void>;
}

value(): Promise<number>

获取当前旋钮的值并返回。

• 返回值: Promise<number>类型，需要使用await关键字取出其中的结果。

setValue(value): Promise<void>

设置旋钮的值，将旋钮旋至指定值的位置，但不会超出最大值。

• value: number类型，将旋钮旋至指定值的位置;
• 返回值: 不返回任何值的异步方法。

滑动条控件: Slider

针对用于接收用户设定的值的滑动条控件。

export interface IQSlider extends IQtControl {
    value(): Promise<number>;
    setValue(value: number): Promise<void>;
}

value(): Promise<number>

获取当前滑动条的值并返回。

• 返回值: Promise<number>类型，需要使用await关键字取出其中的结果。

setValue(value): Promise<void>

设置滑动条的值，将滑块拖拽至指定值的位置，但不会超出最大值。

• value: number类型，将滑块拖拽至指定值的位置;
• 返回值: 不返回任何值的异步方法。

滚动区域控件: ScrollArea

作为一种容器，当容器中内容较多时，可以进行滚动浏览。由于有时候该控件会设置为不显示滚动条，因此另外支持了一个用于滚动的方法——ensureVisible()方法进行滚动。

export interface IQScrollArea extends IQtControl {
    ensureVisible(x:number, y: number);
}

ensureVisible(x, y): Promise<void>

滚动到目标位置（相对滚动区域左上角顶点而言）。

• x: number类型，水平像素数;
• y: number类型，垂直像素数;
• 返回值: 不返回任何值的异步方法。

图形视图控件: GraphicsView

属于一种容器，用于显示绘制的图形（比如使用OpenGL绘制的图形），当然也可以显示常规的控件，类似HTML中的canvas标签。

由于它只是一种特殊的容器，因此并未提供逻辑意义上的实际方法，但仍可调用其继承来的方法。

export interface IQScrollArea extends IQtControl {
}

标签栏控件和标签页控件: Tab & TabItem

针对应用中的标签页的控件，Tab和TabItem，进行标签页的切换。
关于标签栏控件的定义如下:

export interface IQTab extends IQtControl {
    getItem(itemNameOrIndex: string | number): IQTabItem;
    activate(itemNameOrIndex: string | number): Promise<void>;
    count(): Promise<string[]>;
    items(): Promise<string[]>;
}
export interface IQTabItem extends IQtControl {
    activate(): Promise<void>;
    text(): Promise<string>;
    itemIndex(): Promise<number>;
}

getItem(itemNameOrIndex): IQTabItem

获取指定标签页的自动化对象，传入标签页的索引值或标题。

• itemNameOrIndex: number或string类型，目标标签页的索引值或标签页标题。
• 返回值: TabItem类型，同步的返回一个TabItem类型的操作对象。

activate(itemNameOrIndex): Promise<void>

激活目标标签页，传入标签页的索引值或标题。

如果是TabItem上的activate()方法则不需要传入任何参数。

• itemNameOrIndex: number或string类型，目标标签页的索引值或标签页标题。
• 返回值: 不返回任何值的异步方法。

count(): Promise<number>

获取标签栏中的标签页数量。

• 返回值: number类型，标签页的数量。

items(): Promise<string[]>

获取标签栏中的标签页的名称。

• 返回值: string[]类型，由所有标签页标题组成的字符串数组。

以下是TabItem对象的方法。

activate(): Promise<void>

激活标签页。

• 返回值: 不返回任何值的异步方法。

text(): Promise<string>

获取标签页标题。

• 返回值: string类型，返回标签页的标题。

itemIndex(): Promise<number>

获取标签页在整个标签栏中的次序。

• 返回值: number类型，返回标签页的索引值。