XY Pad

xyPad creates a 2-dimensional X-Y pad controller that allows simultaneous control of two parameters. A draggable ball represents the current position, with independent channels for X and Y axes.

xyPad.csd

Download .csd

Properties

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.

Automatable

"automatable": true

Defaults to true. Determines if a widget is automatable by a host DAW. Automatable widgets show up as plug-in parameters in the host. Non-automatable widgets can still communicate with Csound but are not accessible by the host. Note that hosts don't allow this parameter to change dynamically. If you change this setting, the plugin will need to be reloaded.

BallSize

"ballSize": 20

Sets the size (diameter) of the ball in the xyPad widget. The ball represents the current position on the X-Y plane. The default value is 20 pixels. The ball size affects the usable range of the pad - the ball's center is constrained to stay within the pad boundaries, which means larger balls will have their movement range reduced by half the ball size on each edge.

Bounds

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

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

Channel

"channels": [
    {"id": "bandwidth", "event": "mouseDragX", "range": {"min": 10, "max": 2000, "defaultValue": 200, "skew": 1, "increment": 0.001}},
    {"id": "cutoff", "event": "mouseDragY", "range": {"min": 100, "max": 8000, "defaultValue": 1000, "skew": 1, "increment": 0.001}}
]

Defines the channel configuration for the xyPad widget. The X axis is channels[0] and the Y axis is channels[1]:

• id: Channel name for the axis value (used with cabbageGetValue to retrieve the position)
• event: Use mouseDragX for the X axis and mouseDragY for the Y axis

Both channels can be read independently in your Csound code using cabbageGetValue.

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.

Label

"label": {
  "text": "",
  "offsetY": 0
}

Configures the widget label displayed near the control.

• text: string — the label text.
• offsetY: number — vertical offset applied when the label is rendered outside the control (pixels).

Typography (font size, color, family, alignment) is set via style.label.*.

Popup

"popup": 1

This property will set whether a slider's popup value box will appear. It's enabled by default.

Persistence

"persistence": {
  "preset": true,
  "session": true
}

Controls whether a widget's state is saved in DAW presets and Csound session files. Both properties default to true.

• preset: When true, the widget's current value/state is included when using Csound's cabbageSaveState opcode to save preset data. Set to false for widgets that should not persist in Csound preset files (e.g., widgets that load presets).
• session: When true, the widget's state is included when the DAW saves a preset. Set to false for widgets that should not have their values loaded/saved when a DAW session loads (e.g., widgets that load presets).

Auto-cascade behavior: If you set preset to false without explicitly setting session, the system automatically sets session to false as well. This prevents state from being saved anywhere unless explicitly requested.

Range

"channels": [
    {"id": "bandwidth", "event": "mouseDragX", "range": {"min": 10, "max": 2000, "defaultValue": 200, "skew": 1, "increment": 0.001}},
    {"id": "cutoff", "event": "mouseDragY", "range": {"min": 100, "max": 8000, "defaultValue": 1000, "skew": 1, "increment": 0.001}}
]

Each xyPad axis has its own independent range, set on its channel entry (channels[0].range for X, channels[1].range for Y) with the following parameters:

• min: Minimum value (required)
• max: Maximum value (required)
• defaultValue: Initial value (optional, defaults to min)
• skew: Skew factor for non-linear scaling (optional, default is 1 for linear). A value of 0.5 creates exponential scaling
• increment: Step size for value changes (optional, default is 0.001)

range() cannot be updated or modified once a widget has been declared.

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,
  "borderRadius": 5,
  "borderWidth": 1,
  "borderColor": "#525252",
  "backgroundColor": "#323232"
},

• Colors accept named CSS colors, hex (e.g., #RRGGBB or #RRGGBBAA), or rgb/rgba strings.
• Label typography is configured under label.*.
• Ball appearance is configured under the ball.* object on the widget.

Csound Usage

The xyPad returns the ball position on two independent channels, one for each axis. Read both at k-rate with cabbageGetValue:

kBW:k = cabbageGetValue("bandwidth")
kCutoff:k = cabbageGetValue("cutoff")
aOut:a butterbp aSrc, kCutoff, kBW

Example

xyPad.csd

<Cabbage>
{
    "pluginId"      : "def1",
    "enableDevTools": true,
    "channelConfig" : [ {"name": "0 in 2 out", "ins": "0", "outs": "2"} ],
    "widgets"       : [
        { "type": "form", "caption": "XY Pad Example", "size": {"width": 400, "height": 400}, "guiMode": "queue" },
        {
            "type"    : "xyPad",
            "bounds"  : {"left": 20, "top": 20, "width": 350, "height": 350},
            "channels": [
                {"id": "bandwidth", "event": "mouseDragX", "range": {"min": 10, "max": 2000, "defaultValue": 200, "skew": 1, "increment": 0.001}},
                {"id": "cutoff", "event": "mouseDragY", "range": {"min": 100, "max": 8000, "defaultValue": 1000, "skew": 1, "increment": 0.001}}
            ],
            "label"   : {"textX": "Bandwidth", "textY": "Cutoff"}
        }
    ]
}

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

instr 1
    kBW:k = cabbageGetValue("bandwidth")
    kCutoff:k = cabbageGetValue("cutoff")

    printks("Bandwidth: %f, Cutoff: %f\n", 0.5, kBW, kCutoff)

    aSrc:a = vco2(0.5, 110, 12)
    aOut:a butterbp aSrc, kCutoff, kBW
    outs(aOut, aOut)
endin

</CsInstruments>
<CsScore>
i1 0 [60*60*24*7]
</CsScore>
</CsoundSynthesizer>