乐器/发生器

Dashboard：Component API

本页介绍了如何为 Dashboard 自定义和创建新组件。

基础知识

Dashboard 组件由初始化文件 (*.INI) 和一组定义组件外观（皮肤）的位图图像（支持 *.BMP、*.JPG 和 *.TGA）构成。 INI 文件位于 Dashboard 的 Artwork 文件夹 ([FL Studio]/Plugins/Fruity/Generators/Dashboard/Artwork) 或该文件夹的子文件夹中。 图像可放置在任何位置，但最好放置在存储 INI 文件的位置，以便您可以直接引用图像，无需路径。

INI 文件可包含多个部分：

  • Info
  • Properties（可选）
  • Items（仅适用于某些类型的组件）

每个部分均包含一个或多个属性。 属性条目类似于：

propertyName=value

为方便使用，链接至图像文件时最好使用相对路径。 您可以链接至相对于 INI 位置或 Artwork 文件夹的文件夹：

  • 相对于 Artwork 文件夹：[文件夹]\image.bmp（链接至 Artwork\[文件夹]\image.bmp）。
  • 相对于 INI 文件：.\folder\image.bmp（链接至 Artwork\[INI 文件夹]\image.bmp）。

INI 文件部分

INI 文件包含以下部分：

[Info] 部分

您应在信息部分包含以下属性：

  • Name - 控件名称。 确保该名称对于其他组件名称是唯一的。 此属性为必选属性。
  • Kind - 组件类型。 可能的值包括：0 = 数字滚轮；1 = 滑块；2 = 滚轮；3 = 面板；4 = 开关；5 = 标签；6 = 图像；7 = 选择器；8 = Patch 选择器；9 = 页面选择器；此属性为必选属性。
    默认 - 指示此控件是否为其类型的默认控件（是：默认值 = 1，不是：默认值 = 0）。 默认控件用于面板预设值中，其中包含缺少的控件（此 Dashboard 副本中未安装的控件）。 例如，会用默认旋钮组件代替缺少的旋钮组件。 此属性为可选属性。
  • Background - 此属性是对将用作控件背景的图像文件的引用。 如果已指定背景，该属性会决定控件的宽度和高度。 如果您希望允许用户将背景设为透明，则必须指定 8 位 .bmp 文件。 并非所有控件都支持透明背景。 此属性为可选属性。
  • Foreground - 此属性是对将用作控件前景的图像文件的引用。 例如，此属性可以是滑块的旋钮。 并非所有控件都会使用此值（例如页面选择器）。 此属性为可选属性。

[Properties] 部分

此部分定义要为控件属性使用的值。 这些属性均为可选属性。 您可以在各组件的组件检查器中查看可在此设置的属性的完整列表。

[Items] 部分

此部分仅对选择器和 Patch 选择器有效， 它定义了将在选择器中提供的值。 这些值以文本行列表形式指定（每行代表一个值），以 "=" 结尾：

valueName=

对于 Patch 选择器控件，还可以包含对应于乐器名称的音色库和程序编号：

valueName=Bank MSB, Bank LSB, Program Number

示例：

[items]
100% Left=
50% Left=
Centered=
50% Right=
100% Right=

组件类型

本部分更深入地描述了各个组件类型（在 Kind 中指定）。目前提供十种不同的控件。

数字滚轮（Kind=0）

  • 为每个值显示不同图像的滚轮（图像应在水平条中按顺序排列）。
  • 可用作控制器。
  • 背景用于控件四周的边框。
  • 前景用于数值（参见提供的数字滚轮控件）。

此附加参数在 [Properties] 部分中受支持（在组件检查器中不可见）：

  • Border - 指定背景图像的边框大小，具体如下：

    Border=left, top, right, bottom

滑块（Kind=1）

  • 向上/向下滑块控件。
  • 可用作控制器。
  • 前景用作滑块的旋钮。 大部分情况下，此组件是可以呈现透明状态的 32 位 *.TGA 文件。

滚轮（Kind=2）

  • 带有一条数值指示线的旋钮控件。
  • 可用作控制器。
  • 未使用前景图像。

此附加参数在 [Properties] 部分中受支持（在组件检查器中不可见）：

  • Line Length - 指示线的长度，以控件宽度/高度百分比的形式表示。

面板（Kind=3）

  • 您可以通过此组件向 Dashboard 面板添加自定义背景。
  • 未使用前景图像。

此附加参数在 [Properties] 部分中受支持（在组件检查器中不可见）：

  • Border - 指定背景图像的边框大小，具体如下：

    Border=left, top, right, bottom

开关（Kind=4）

  • 此组件为双态切换按钮（开-关）。
  • 可用作控制器。
  • 前景应包含两个图像，一个向上，一个向下。
  • 未使用背景。

标签（Kind=5）

  • 此组件是用于显示文本标签的简单控件。
  • 未使用背景和前景。

图像（Kind=6）

  • 此控件仅显示一个图像。
  • 未使用前景图像。

选择器（Kind=7）

  • 此组件为组合框控件，显示自定义数值列表。
  • 数值列表是从 *.INI 文件的 [Items] 部分读取的。
  • 未使用前景图像。
  • 可用作控制器。

Patch 选择器（Kind=8）

  • 此控件允许用户从预定义数值列表中选择 Patch。
  • 数值列表是从 *.INI 文件的 [Items] 部分读取的。
  • 每个值均应附加音色库 MSB、音色库 LSB 和 Patch 编号信息（参见上文中 [Items] 部分的说明）。
  • 未使用前景图像。

页面选择器（Kind=9）

  • 此组件为特殊类型的控件，可用于选择可见界面页面（若存在）。
  • 未使用前景图像。

说明和提示

  • 控件是通过名称标识的，因此，请务必为其提供唯一的描述性名称。
  • 最好将属于某一组的所有控件放在一个目录中，与其他控件区分开。
  • 如果不为控件指定背景图像，该控件将为透明状态。 并非所有控件都支持透明状态。
  • 请查看提供的控件，这些控件将提供用户需要了解的大部分信息。