GENERATORS

Dashboard: Component API

This page explains how to customize and create new components for Dashboard.

Basics

A Dashboard component is built of an initialization file (*.INI) and a set of bitmap images (*.BMP, *.JPG and *.TGA are supported) that define the component appearance (skin). The INI files resides in the Artwork folder of Dashboard ([FL Studio]/Plugins/Fruity/Generators/Dashboard/Artwork), or in subfolder of that folder. The images can be placed anywhere, but it is best to place them where the INI file is, so you can reference the images directly, without path.

There can be several section in the INI file:

• Info
• Properties (optional)
• Items (only for some types of components)

Each section contains one or more properties. A property entry looks like this:

propertyName=value

For ease of use, it is best to use relative paths when you link to image files. You can link to a folder relative to the INI position or the Artwork folder:

• Relative to the Artwork folder : [Folder]\image.bmp (links to Artwork\[Folder]\image.bmp).
• Relative to the INI file : .\folder\image.bmp (links to Artwork\[INI Folder]\image.bmp).

INI File Sections

The INI file contains the following sections:

[Info] Section

You should include these properties in the info section:

• Name - The name of the control. Make sure the name is unique to the other component names. This property is required.
• Kind - The component type. The possible values are: 0 = DigiWheel; 1 = Slider; 2 = Wheel; 3 = Panel; 4 = Switch; 5 = Label; 6 = Image; 7 = Selector; 8 = Patch selector; 9 = Page selector; This property is required.
  Default - Indicates if this control is the default control for its kind (Default=1) or not (Default=0). A default control is used in panel presets which contains missing controls (not installed in this copy of dashboard). For example, a missing wheel component is replaced with the default wheel component. This property is optional.
• Background - This is a reference to the image file that will be used as background for the control. If a background is specified, it determines the control's width and height. If you want to allow the user to make a background transparent, you have to specify an 8-bit .bmp file. Not all controls supports transparency. This property is optional.
• Foreground - This is a reference to the image file that will be used as a foreground for the control. This could be a knob for a slider, for example. Not all controls will use this value (for example page selectors). This property is optional.

[Properties] Section

[Items] Section

This section is only valid for selectors and patch selectors. It defines the values that will be available in the selector. The values are specified as a list of text lines (each line is a value) ending with "=":

valueName=

For patch selector controls, you also include the bank and program numbers that correspond to the instrument names:

valueName=Bank MSB, Bank LSB, Program Number

EXAMPLE:

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

Component Types

DigiWheel (Kind=0)

• Wheel which displays a different image for each value (the images should be ordered sequentially in a horizontal strip).
• It can be used as a controller.
• The background is used for the border around the control.
• The foreground is used for the values (see the supplied DigiWheel controls).

This additional parameter is supported in the [Properties] section (not visible in the component inspector):

• Border - Specifies the border size of the background image as follows:

  Border=left, top, right, bottom

Slider (Kind=1)

• An up/down slider control.
• Can be used as a controller.
• The foreground is used as the knob of the slider. Most of the time, this is a 32-bit *.TGA file which can be transparent.

Wheel (Kind=2)

• A wheel control with a line as indicator of the value.
• Can be used as a controller.
• The foreground image is not used.

This additional parameter is supported in the [Properties] section (not visible in the component inspector):

• Line Length - the length of the indicator line, as a percentage of the width/height of the control.

Panel (Kind=3)

• This component allows you to add custom backgrounds to the dashboard's panel.
• The foreground image is not used.

This additional parameter is supported in the [Properties] section (not visible in the component inspector):

• Border - Specifies the border size of the background image as follows:

  Border=left, top, right, bottom

Switch (Kind=4)

• This is a two-state toggle button (on-off).
• Can be used as a controller.
• The foreground should contain two images, one for up and one for down
• The background is not used.

Label (Kind=5)

• This is a simple control that displays text labels.
• Background and Foreground are not used.

Image (Kind=6)

• This control simply displays an image.
• Foreground image is not used.

Selector (Kind=7)

• This is a combo box control, showing a custom list of values.
• The list of values is read from the [Items] section of the *.INI file.
• Foreground image is not used.
• It can be used as a controller.

Patch Selector (Kind=8)

• This control allows the user to select a patch from a list of predefined values.
• The list of values is read from the [Items] section of the *.INI file.
• Each value should have a Bank MSB, Bank LSB and a Patch Number information appended (see the description of the [Items] section above).
• Foreground image is not used.

Page Selector (Kind=9)

• This is a special type of control which allows you to select the visible interface page (if there are any).
• Foreground image is not used.

Notes & Tips

• A control is identified by its name, so make sure to give it one that's both descriptive and unique.
• Preferably put all controls of a certain group in a directory away from the rest.
• If you don't specify a background image for a control, it's transparent. Not all controls support this very well.
• Take a look at the provided controls, they'll show you most of what you need to know.