24. 脚本 API 引用 | UI

模块: UI

studio.ui 模块可用于创建用户界面。

ui.showModalDialog(description)

显示对话窗口。对话框关闭后该函数返回。

有关小部件description参数的更多信息，请参阅ui.showModelessDialog(description)。

ui.showModelessDialog(description)

显示对话窗口。对话框显示后，该函数就会返回。

对话框的布局基于小部件 description 对象，其包含以下属性:

• widgetType: Astudio.ui.widgetType.必要属性。
• widgetId: 用于引用此小部件的 string 。不可变。
• isVisible: 设置小部件可见性的 Boolean 。
  -isEnabled: 设置小部件是否是交互式的布尔值。
• minimumWidth: 小部件的最小宽度（以像素为单位）（number）。
• minimumHeight: 小部件的最小高度（以像素为单位）（number）。
  -sizePolicy: studio.ui.sizePolicy。
  -onConstructed: 在构建小部件后调用的 Function。
• onTimerEvent(timerId): 回调 Function。在小部件上调用 startTimer() 后，将定期调用该函数。timerId 与 startTimer() 返回的相应 timerId 相匹配。

适用于对话框中的根小部件描述:

• windowTitle: 窗口的标题 string。
  -windowWidth: 窗口的宽度（number）。
  -windowHeight: 窗口的高度（number）。
  -onClose: 作为小部件调用的 Function 被销毁。

适用于widgetType.Layout:

• layout: Astudio.ui.layoutType.必要属性。
• items: 嵌套在此布局中的操作台小部件描述的 Array。
  -contentsMargins: 描述布局周围的边距。格式为 { left:[number], top:[number], right:[number], bottom:[number] } 的 Object。
• spacing: 项目之间的间距，以像素为单位（number）。

适用于 layoutType.HBoxLayout 或 layoutType.VBoxLayout 中的项目:

• stretchFactor: 确定一个项目相对于其兄弟项目占用多少空间（number）。不可变。
• alignment: Astudio.ui.alignment.不可变。

适用于 layoutType.GridLayout 中的项目:

• row: 网格中的行索引（number）。不可变。
• column: 网格中的列索引（number）。不可变。
  -rowSpan: 项目要跨越的行数。不可变。
  -columnSpan: 项目要跨越的列数。不可变。
• alignment: Astudio.ui.alignment.不可变。

适用于 widgetType.Label:

• text: 一个 string.
• wordWrap: 一个 boolean.

适用于widgetType.PushButton:

• text: 一个 string.
  -onClicked: 回调 Function。

适用于widgetType.LineEdit:

• text: 一个 string.
  -isReadOnly: 一个 bool.
  -echoMode: studio.ui.echoMode。
  -onTextEdited: 回调 Function。
  -onEditingFinished: 回调 Function。

适用于widgetType.TextEdit:

• text: 文本编辑的内容，作为纯文本 string。或者，使用 html 属性指定 HTML 格式的文本。
  -html: 文本编辑的内容，作为 HTML 格式的 string。这可用来代替 text。
  -isReadOnly: 一个 boolean.

适用于widgetType.ComboBox:

• items: 格式为 { text:[string], userData:[]} 的对象数组。只写。
  -currentIndex: 一个 number。
  -currentText: 一个 string.只读。
  -currentUserData: 只读。
  -onCurrentIndexChanged: 回调 Function。

适用于widgetType.CheckBox:

• text: 一个 string.
• isChecked: 一个 boolean.
  -onToggled: 回调 Function。

适用于widgetType.Slider:

• orientation: studio.ui.orientation。
• value: 一个 number。
• range: 格式为 { minimum:[int], maximum:[int] } 的对象。
  -onValueChanged: 回调 Function。

适用于widgetType.SpinBox:

• value: 一个 number。
• range: 格式为 { minimum:[int], maximum:[int] } 的对象。
  -onValueChanged: 回调 Function。

适用于widgetType.PathLineEdit:

• text: 一个 string.
• label: 一个 string.不可变。
• caption: 一个 string.不可变。
• pathType: Astudio.ui.pathType.不可变。
  -onEditingFinished: 回调 Function。

请注意，除了标记为必需的属性外，所有属性都是可选的。

调用小部件回调函数时将 this 值设置为相应的小部件。可以使用相应的“getter”和“setter”动态获取和设置小部件描述中可用的各种属性（例如，调用 widget.setVisible() 将修改 widget.isVisible() 属性）。标记为不可变的属性没有“setter”功能。例如:

{
    widgetType: ui.widgetType.PushButton,
    text:  "Show Alert",
    onClicked: function() {
        // 显示带有单击按钮文本的警报
        alert("The button's text is: "; + this.text());
    },
}

从回调的上下文中，许多附加成员函数可用于小部件:

• findWidget(widgetId): 返回具有匹配 widgetId 的同级小部件。
• closeDialog(): 关闭父项窗口。
• startTimer(intervalInMs): 使用 intervalInMs 启动计时器并返回 timerId。定时器启动后，将定期调用小部件描述的 onTimerEvent() 函数。当启动了多个定时器时，可使用 timerId 来区分定时器。
• stopTimer(timerId): 使用给定的 timerId 停止计时器。

有关自行编写小部件的深入示例，请参阅 FMOD Studio 安装目录的 Scripts 文件夹中的 EngineDesigner.js 示例。

ui.widgetType

对应于 UI 小部件描述中可用的不同小部件类型的枚举。可能的价值是:

• Spacer: 空白的小部件。
• Layout: 容器小部件。必须指定相应的布局类型。
• Label: 文本标签。
• PushButton: 一个可点击的按钮。
• LineEdit: 单行文本输入小部件。
• TextEdit: 多行文本输入小部件。支持纯文本和 HTML。
• ComboBox: 一个下拉菜单。
• CheckBox: 带有文本标签的布尔值复选框。
• Slider: 具有整数范围的滑块。
• SpinBox: 具有整数范围的数字框。
• PathLineEdit: 一个便利的小部件，提供一个单行文本输入小部件和一个“浏览”按钮，允许用户输入文件或目录路径。

ui.layoutType

对应于 widgetType.Layout 的 UI 小部件描述中可用的不同布局类型的枚举。可能的价值是:

• HBoxLayout: 横向布局。除非指定了 stretchFactor ，否则项目的间距是均匀的。
  -VBoxLayout: 垂直布局。除非指定了 stretchFactor ，否则项目的间距是均匀的。
• GridLayout: 网格布局。项目可以指定 row、column、 rowSpan 和 columnSpan。

ui.alignment

对应于布局小工具内项目对齐方式的枚举。可能的价值是:

• AlignLeft
• AlignRight
• AlignHCenter
• AlignJustify
• AlignAbsolute
• AlignTop
• AlignBottom
• AlignVCenter
• AlignBaseline
• AlignCenter

ui.sizePolicy

对应于小部件尺寸规则的枚举。这决定了它将尝试在其布局中占用多少空间，以及当可用空间增加或减少时它将如何反应。

将需要指定单独的垂直和水平尺寸规则。例如: sizePolicy: { horizontalPolicy: studio.ui.sizePolicy.Fixed, verticalPolicy: studio.ui.sizePolicy.Fixed }.

请注意，尺寸规则仅适用于单个小部件，不适用于对话框窗口的尺寸。

可能的价值是:

• Fixed - 小部件永远不会增长或缩小
• Minimum - 小部件可以展开但不能小于小部件描述对象中指定的 minimumWidth/minimumHeight
• Maximum - 小部件可以变小但不能扩展到超出小部件描述对象中指定的 maximumWidth/maximumHeight
• Preferred - 小部件可以展开或缩小，但大于小部件描述对象中指定的 minimumWidth/minimumHeight 没有任何优势
• MinimumExpanding - 小部件可以利用额外的空间，因此它应该获得尽可能多的空间，并在小部件描述对象中指定首选的 minimumWidth/minimumHeight
• Expanding - 小部件可以利用额外的空间，因此应该获得尽可能多的空间
• Ignored - 小部件将获得尽可能多的空间

ui.orientation

表示方向的枚举。可能的价值是:

• Horizontal
• Vertical

ui.echoMode

对应于 LineEdit 小部件回显模式的枚举。这可用于在输入密码时显示星号而不是字符。可能的价值是:

• Normal
• NoEcho
• Password
  -PasswordEchoOnEdit

ui.pathType

对应于 PathLineEdit 支持的不同路径类型的枚举。这控制了浏览器对话框的行为。可能的价值是:

• OpenFile: 用户将能够选择现有文件。
• SaveFile: 用户将能够在给定目录中指定新文件名。
• Directory: 用户将能够选择现有目录。