Keyboard

keyboard will display a keyboard that will send MIDI information to your Csound instrument. This component can be used together with a hardware controller.

Properties (alphabetical)

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

Active

"active": true

Will deactivate a control if false is set (use 0/1 to update from Csound). Controls which are deactivated can still be updated from Csound. Any widget that has its active property set to false will allow all mouse-clicks to pass through it.

Bounds

"bounds": {"left":0, "top":0, "width":100, "height":100}

Integer values that set position and size on screen(in pixels).

Channel

"channels": [
                {
                    "id":"channelName", 
                    "eventType": "valueChanged",
                    "type": "number",
                    "range": {"min":0, "max":100, "defaultValue":0, "skew":1, "increment":0.1}
                }
            ]

In Cabbage 3, widgets use an array of channels instead of a single channel string. Each channel object includes an id that defines a unique channel name. Widgets in Cabbage 3 can have any number of channels attached to them. An optional eventType property specifies the type of interaction. A range object can define the minimum, maximum, and default values, along with the skew and step increment. The type is set to number by default. Each widget sets its own type, number or string.

⚠️ Important: During runtime, range objects will be appended with the current value. You should never set this value explicilty as it will override any state recall.

If range is omitted, it defaults to a range from 0 to 1, with increments of 0.001 for widgets that use drag events (e.g., sliders, XY pads) and 1 for widgets that use click or toggle events (e.g., buttons, checkboxes).

Note on increment parameter behavior:

The increment parameter quantizes all values sent to Csound channels, ensuring they snap to the specified step size. For example, with increment: 0.1, values will be rounded to 0.0, 0.1, 0.2, etc. before reaching Csound.

The DAW host automation has additional constraints:

increment >= 1.0: The host will display discrete integer steps (e.g., move from 1 to 2 to 3, etc.) in its native controls, and enforce these steps during automation.
increment < 1.0: The host displays a continuous slider. Cabbage always quantizes values internally before sending to Csound.

A widget’s top-level id property defines the general communication channel for updating attributes, while the channels specified in the channels array are used for value and parameter updates. If no top level id is specified, the first channel.id will be used as the general communication channel.

Supported event types:

Event	Description
`valueChanged (default)`	Tracks simple value changes
`mousePressLeft`	Tracks presses of left mouse button
`mousePressRight`	Tracks presses of right mouse button
`mousePressMiddle`	Tracks presses of middle mouse button
`mouseMoveX`	Tracks movement along X axis.
`mouseMoveY`	Tracks movement along Y axis.
`mouseDragX`	Tracks movement along X axis with mouse pressed
`mouseDragY`	Tracks movement along Y axis with mouse pressed
`mouseInside`	Returns max when any mouse button is within the bounds of the widget, min if outside.

In Cabbage 3, channels don't need to start with a letter and white spaces are permitted.

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.

Key Width

"keyWidth": 24

Set the width of the keys in pixels.

Value

"value":0

Value sets the initial state of the widget. In the case of a keyboard widget, it sets the leftmost key to appear.

Visible

"visible": true

A value of true will cause the widget to become invisible (use 0/1 to update from Csound). Widgets have their visibility set to true by default.

ZIndex

"zIndex": 1

Sets the stacking order of the widget. Widgets with higher zIndex values will appear in front of widgets with lower values. Default is 1.

Style

"style": {
  "opacity": 1
},

Keyboard visuals (white/black keys, keydown color) are configured under the color.* object on the widget, not in style.

Example

<Cabbage>
{
    "widgets": [
        { "type": "form", "caption": "Combobox Example", "size": {"width": 580, "height": 500}, "pluginId": "def1" },
        {
            "type"    : "rotarySlider",
            "bounds"  : {"left": 12, "top": 9, "width": 86, "height": 90},
            "channels": [
                { "id": "att", "range": {"min": 0, "max": 1, "defaultValue": 0.01, "skew": 1, "increment": 0.001} }
            ],
            "text"    : "Att."
        },
        {
            "type"    : "rotarySlider",
            "bounds"  : {"left": 99, "top": 9, "width": 86, "height": 90},
            "channels": [
                { "id": "dec", "range": {"min": 0, "max": 1, "defaultValue": 0.4, "skew": 1, "increment": 0.001} }
            ],
            "text"    : "Dec."
        },
        {
            "type"    : "rotarySlider",
            "bounds"  : {"left": 187, "top": 9, "width": 86, "height": 90},
            "channels": [
                { "id": "sus", "range": {"min": 0, "max": 1, "defaultValue": 0.7, "skew": 1, "increment": 0.001} }
            ],
            "text"    : "Sus."
        },
        {
            "type"    : "rotarySlider",
            "bounds"  : {"left": 274, "top": 9, "width": 86, "height": 90},
            "channels": [
                { "id": "rel", "range": {"min": 0, "max": 1, "defaultValue": 0.8, "skew": 1, "increment": 0.001} }
            ],
            "text"    : "Rel."
        },
        {
            "type"    : "keyboard",
            "bounds"  : {"left": 12, "top": 104, "width": 348, "height": 80},
            "channels": [ {"id": "keyboard"} ]
        },
        {
            "type"    : "comboBox",
            "bounds"  : {"left": 260, "top": 188, "width": 100, "height": 30},
            "channels": [ {"id": "waveform"} ],
            "corners" : 5,
            "items"   : ["Saw", "Square", "Triangle"]
        }
    ]
}

</Cabbage>
<CsoundSynthesizer>
<CsOptions>
-n -d -+rtmidi=NULL -M0 -m0d --midi-key=4 --midi-velocity-amp=5
</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

    vcoModes:i[] fillarray 0, 10, 12
    att:i = cabbageGetValue("att")
    dec:i = cabbageGetValue("dec")
    sus:i = cabbageGetValue("sus")
    rel:i = cabbageGetValue("rel")
    env:k = madsr(att, dec, sus, rel)
    vcoOut:a = vco2(env*p5*.5, cpsmidinn:k(p4), vcoModes[cabbageGetValue:i("waveform")])
    outs(vcoOut, vcoOut)

endin


</CsInstruments>
<CsScore>
;causes Csound to run for about 7000 years...
f0 z
</CsScore>
</CsoundSynthesizer>

Properties (alphabetical)​

Active​

Bounds​

Channel​

Id​

Key Width​

Value​

Visible​

ZIndex​

Style​

Example​