Form

Form creates the main application window. pluginId() is the only required identifier. The default values for size are 600x300. Form identifiers are mostly static apart from latency() which can be updated dynamically.

form caption("string"), size(Width, Height), bundle("./folder1", "file2", "etc.."), pluginId("plug"), guiRefresh(val), guiMode("val"), import("file1", "file2", "etc.."), titleBarColour("colour"), style("style"), sideChain(), typeface("fontFile"), latency(val), autoUpdate(), opcodeDir(dir), colour("colour"), fontColour("colour"),

Specific Identifiers

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

size(Width, Height) integer values denoted the width and height of the form.

bundle("./folder1", "file2", "etc..") The bundle identifier will instruct Cabbage to copy the listed files and folders into the same folder your exported plugin goes. On OSX this will be the plugin bundle itself.

pluginId("plug") this unique string must be four characters long. It is the ID given to your plugin when loaded by plugin hosts.

Every plugin must have a unique plugin ID. If you experience problems loading two different plugins, it could be because they use the same plugin ID. The plugin ID seems to be more relevant when working with OSX than on Linux or Windows.

guiRefresh(val) [!!! DEPRECATED !!!] This is no longer needed when using the new guiMode("queue") system of updated widgets and should only be used for legacy instruments.

Sets the rate at which Cabbage will update its GUI widgets when controlled by Csound. The value passed represents the number of k-rate cycles to be skipped before the next update. The larger this is the slower the GUI updates will take place, but the less CPU intensive the instrument will be. val should be an integer greater than 1 and is set to ksmps x 2 by default.

For best performance one should set guiRefresh to be a factor of ksmps.

guiMode("val") Sets how widgets will be updated. guiMode("polling") (default if guiMode() is not specified), will cause each widget's channel to be polled for updates at k-boundaries. The update rate is set using the guiRefresh() identifier. If you are using a large number of widgets this can get quite slow, especially if the widgets also contains identifier channels defined with identChannel().

Using guiMode("queue") will improve performance, especially if you are using a large number of widgets. identChannel() identifiers are not supported when guiMode is set to "queue". In this case you can use the cabbageSet/Set opcodes to set and get data from a widget. More details can be found here.

import("file1", "file2", "etc..") The import identifier will import the file/s specified. This can be useful when including files that contains macros definitions, or custom plant imports.

titleBarColour("colour") This sets the colour of the button when it's value is 0. Any CSS or HTML colour string can be passed to this identifier. The colour identifier can also be passed an RBG, or RGBA value. All channel values must be between 0 and 255. For instance colour(0, 0, 255) will create a blue, while colour(0, 255, 0, 255) will create a green with an alpha channel set to full.

style("style") Will set the style of a button. Set to "flat" by default. Use "flat" for modern look, or "legacy" for old style look. If this identifier is used with a form, it will set the global styling used for sliders and buttons.

sideChain() [!!! DEPRECATED !!!] No longer needed to enable side-chaining for plugins. Side-chain channels can be controlled using nchnls and nchnls_i in the Csound header section.

typeface("fontFile") Set a custom .ttf/.otf font to be used by all widgets. Be sure to use a relative path to the font file. And don't forget to include the file if you share your instrument.

latency(val) Sets the plugin delay compensation in samples. Defaults to ksmps. Setting latency to -1 forces Csound to run at ksmps=1, but does not result in a one sample delay. In this mode, Cabbage performs ‘in-place’ processing. Note this -1 latency is only useful for realtime processing and in almost all cases it is more efficient to use the host’s PDC. Latency can be updated dynamically. The code shown below updates the plugin latency in realtime with a slider that jumps in integer increments from 1 to 8. Updating a plugin's PDC in real time may not be supported by some plugin hosts.

instr UpdateLatency
    kLatencySliderVal, kLatencyTrig cabbageGetValue "latencySlider"
    cabbageSet kLatencyTrig, "form", "latency", pow(2, kLatencySliderVal)
    printf "Setting latency to %d\n", kLatencyTrig, pow(2, kLatencySliderVal)
endin

autoUpdate() When added to the form declaration, this identifier will causes Cabbage to start a timer that periodically checks for updates to the underlying source code. When it sees the .csd file has changed, for example through an external editor, it will automatically update the instrument. Note that adding extra widgets will require you to re-instantiation your instrument in the DAW, as widgets are tied to plugin parameters, which can't be dynamically modified.

opcodeDir(dir) This will override the OPCODE6DIR64 directory. dir should be a directory. It's always best to use relative rather than absolute directories. The only time you every really need to use this is when you are distributing plugin that use some of Csound's plugin opcodes, in which case you will need to tell Csound where to find these plugins.

Common Identifiers

colour("colour") This sets the main colour. Any CSS or HTML colour string can be passed to this identifier. The colour identifier can also be passed an RBG, or RGBA value. All channel values must be between 0 and 255. For instance colour(0, 0, 255) will create a blue, while colour(0, 255, 0, 255) will create a green with an alpha channel set to full.

fontColour("colour") Sets the colour of the font. In the case of slider this sets teh colour of the font in the value textBox if it is shown.

Example

<Cabbage>
form caption("Form Example") size(380, 300), guiMode("queue"), colour(2, 145, 209) pluginId("def1")
texteditor bounds(12, 20, 352, 228) channel("infoText"), readOnly(1), wrap(1), scrollbars(1)
</Cabbage>
<CsoundSynthesizer>
<CsOptions>
-n -d -+rtmidi=NULL -M0 -m0d --midi-key=4 --midi-velocity-amp=5
</CsOptions>e
<CsInstruments>
; Initialize the global variables. 
ksmps = 16
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

    SText  = "A form represents an instrument plugin window. All widgets are positioned relative to the top left of the form, i.e., position 0,0.\n\nWhen declaring a form, you can also set some useful attributes of your plugin such as the pluginId and plugin delay compensation (latency)."
    cabbageSet "infoText", "text", SText

endin

</CsInstruments>
<CsScore>
;causes Csound to run for about 7000 years...
f0 z
;starts instrument 1 and runs it for a week
i1 0 z
</CsScore>
</CsoundSynthesizer>