Skip to main content

Form

form creates the main application window. pluginId is the only required property, while caption will only be used when running an instrument as a standalone. The default values for size are 600x300. There can only be one form per instrument, and it has the unique channel name of MainForm.

Properties (alphabetical)​

Below is the full, alphabetical list of top-level widget properties for form.

Caption​

"caption": "string"

The string passed to caption will be the string that appears on the main application window.

ChannelConfig​

"channelConfig": "2-2"

Sets the preferred channel and bus layout. You can add as many configuration strings as you like, e.g., "2-2 2-1 1-1". You can also organise channels into buses by using a '.' operator. For example, the following string will group the inputs into a stereo bus, alongside a mono sidechain input: "2.1-2".

EnableDevTools​

"enableDevTools": true

Enables right-clicking of webview context menu. When this is disabled users will not be able to inspect your UI or access any of the browser dev tools. This is enabled by default.

Logger​

"logger":{
    "file":"",
    "replace": true,
    "enabled": true
}

Enables file logging when in plugin mode. If "file" is left empty, the log file will default to the same name as the .csd file, but with a .log extension. The "replace" parameter determines whether Cabbage overwrites the log file on successive runs. File logging, along with this log overwriting, is enabled by default. Note the logger is only available in plugin builds.

Package​

"package" : {
    "include": [ {"src": "sample", "dest": "samples"} ],
    "cabzOuputDir":""
},

The package object is used to manage the resources required by your instruments when they are exported. The package accepts an array of src/dest pairs. The src value may be a relative or absolute path and can include file wildcards (for example, * or **).

"include": [ {"src": "/Users/me/cabbage3-recipes/samples/*.wav", "dest": "audioSamples"} ]

This example copies all .wav files from the samples folder into an audioSamples folder located at the top level of the exported plugin’s resources directory. The dest directory is always the top level directory. If your src is a folder, and you leave out the dest dir, all the files from that folder will be placed in the top-level plugin resource directory. cabzOutputDir is the output location for encrypted resource, available only in the Cabbage pro add-on.

Id​

"id": "widgetId"

This optional channel can be used to define a top-level line of communication between the instrument’s UI and Csound. It is reserved for UI updates only. If omitted, it defaults to the first id from the channels array. Its primary purpose is to help produce clearer code, especially for widgets with multiple channels.

Style​

"style": {
  "fill": "#004c6b",
  "opacity": 1
},
  • The form background color is controlled by style.fill.
  • Opacity applies to the form’s background.

Example​

<Cabbage>
{
    "widgets": [
        { "type": "form", "caption": "Button Example", "size": {"width": 380, "height": 300}, "guiMode": "queue", "pluginId": "def1" },
        {
            "type"    : "checkBox",
            "bounds"  : {"left": 10, "top": 16, "width": 126, "height": 18},
            "channels": [
                { "id": "trigger", "event": "valueChanged", "range": {"min": 0, "max": 1, "defaultValue": 0, "skew": 1, "increment": 1} }
            ],
            "label"   : {"text": "Synth Enabled"}
        },
        {
            "type"    : "button",
            "bounds"  : {"left": 146, "top": 12, "width": 80, "height": 30},
            "channels": [
                { "id": "mute", "event": "valueChanged", "range": {"min": 0, "max": 1, "defaultValue": 0, "skew": 1, "increment": 1} }
            ],
            "label"   : { "text": {"off": "Unmute", "on": "Mute"} }
        },
        {
            "type"    : "button",
            "bounds"  : {"left": 240, "top": 12, "width": 121, "height": 30},
            "channels": [ {"id": "toggleFreq", "event": "valueChanged"} ],
            "label"   : { "text": {"off": "Toggle Freq", "on": "Toggle Freq"} },
            "style"   : {
                "off": {"backgroundColor": "#ff0000", "textColor": "#ffffff"},
                "on" : {"backgroundColor": "#0295cf", "textColor": "#ffffff"}
            }
        }
    ]
}

</Cabbage>
<CsoundSynthesizer>
<CsOptions>
-n -d -+rtmidi=NULL -M0 -m0d
</CsOptions>
<CsInstruments>
; Initialize the global variables.
ksmps = 32
nchnls = 2
0dbfs = 1

; Rory Walsh 2021
;
; License: CC0 1.0 Universal
; You can copy, modify, and distribute this file,
; even for commercial purposes, all without asking permission.

instr 1

    kVal, kTrig = cabbageGetValue("trigger")

    if kTrig == 1 then
        if kVal == 1 then
            event("i", "Synth", 0, 3600)
        else
            iInstrNum = nstrnum("Synth")
            turnoff2(iInstrNum, 0, 0)
        endif
    endif

endin

instr Synth
    prints("Starting Synth")
    kMute = cabbageGetValue("mute")
    a1 = oscili(.5*kMute, 300*(cabbageGetValue("toggleFreq")+1))
    outs(a1, a1)
endin




</CsInstruments>
<CsScore>
;starts instrument 1 and runs it for a week
i1 0 z
</CsScore>
</CsoundSynthesizer>