GUI Script Syntax

Introduction

This page is the manual and scripting reference for the GUI definition language used in many deadbeef plugins to define their settings UI.

A good way to learn more, and see some real-world usage, is to look at the source code, for examples of how to do various things.

The most important feature of the scripted UI is that the same plugin works on all supported platforms -- even in 3rd party GUI plugins, if they implement the scripting support.

At the time of writing, the scripted UI works in GTK, Cocoa/OSX, and Android versions.

There are 3 main use cases for it:

Defining the plugin settings UI dialogs.

This is done by assigning a string constant to the configdialog field of the DB_plugin_t structure. The dialog can be presented in various ways, and let the user to change the values of the text fields, sliders, etc. Then the result will be applied to the specified config variables.

DSP plugin instance configuration

Done the same way as for plugin settings, but slightly differently. Each value is get/set using the plugin's instance API, by index, instead of writing to config file.

Running custom dialogs, usually via menus

This is done by calling the run_dialog function of the current GUI plugin.

The run_dialog is optional, so make sure you check it's not NULL before using.

It will return the pressed button code, and will use the provided API for setting and getting values.

The script syntax

The syntax is very simple.

Each script defines 1 dialog. The dialog consists of items. Items are separated with semicolons.

Strings can be quoted, if they contain spaces.

General syntax of an item:

property LABEL TYPE[ADDITIONAL_PARAMETERS] KEY DEFAULT_VALUE [ADDITIONAL ARGUMENTS];

Example:

property "A Check Box" checkbox myplugin.checkbox 1;
property "A Text Field" entry myplugin.textfield Hello;

This will define a dialog, which contains a checkbox and a text field, labelled as "A Check Box" and "A Text Field", respectively.

Their values will be written to the configuration file under "myplugin.checkbox" and "myplugin.textfield" keys, and will have default values of "1" and "Hello", respectively.

List of widely supported item types

entry -- text entry property "Playlist name, for adding files from other apps" entry cli_add_playlist_name Default;
password -- text entry for passwords property Password password lastfm.password "";
file -- file path with browse button property "Songlengths.txt (from HVSC)" file hvsc_path "";
checkbox -- a checkbox with 2 states (on/off) property "Mono synth" checkbox sid.mono 0;
hscale[min,max,step] -- a horizontal spin button, with min, max values and step size property "Left mix:" hscale[0,1,0.001] leftmix 1;
spinbtn[min,max,step] -- same as hscale
vscale[min,max,step] -- same as hscale, but vertical (e.g. used in the EQ). This requires vertical layout support, which is not always available.
select[count] -- a drop down list, with "count" items; the items go after the default value; the resulting value/default is an index property "ReplayGain mode" select[3] replaygain_mode 0 Disable Track Album;