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.

Properties (alphabetical)

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

Active

"active": 0

Will deactivate a control if 0 is passed. Controls which are deactivated can still be updated from Csound.

Automatable

"automatable": 1

Defaults to 1. 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

"channel": {"id": "xyPad1", "x": "channelX", "y": "channelY"}

Defines the channel configuration for the xyPad widget:

• id: Unique identifier for the xyPad widget itself. Use this channel with cabbageSet to update any of the xyPad's attributes.
• x: Channel name for the X-axis value (used with cabbageGetValue to retrieve the horizontal position)
• y: Channel name for the Y-axis value (used with cabbageGetValue to retrieve the vertical position)

Both X and Y 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.

Range

"range": {
    "x": {"min": 0, "max": 100, "defaultValue": 50, "skew": 1, "increment": 0.1},
    "y": {"min": 0, "max": 100, "defaultValue": 50, "skew": 1, "increment": 0.1}
}

Defines the ranges for both X and Y axes of the xyPad. Each axis has its own independent range 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": 1

A value of 0 will cause the widget to become invisible. Widgets have their visibility set to 1 by default.

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.

Example

<Cabbage>
form caption("XyPad Test") size(400, 400), guiMode("queue") pluginId("test")
xyPad bounds(20, 20, 350, 350) channel("cf", "bw"), rangex(100, 10000, 1000, 1, 0.001), rangey(0, 1, 0.5, 1, 0.001), text("Freq", "BW")
</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
    kFreq chnget "cf"
    kBW chnget "bw"
    
    printks "Freq: %f, BW: %f\n", 0.5, kFreq, kBW
    
    aOut oscili 0.2, kFreq
    outs aOut, aOut
endin

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

<Cabbage>
form caption("XyPad Test") size(400, 400), guiMode("queue") pluginId("test")
xyPad bounds(20, 20, 350, 350) channel("cf", "bw"), rangex(100, 10000, 1000, 1, 0.001), rangey(0, 1, 0.5, 1, 0.001), text("Freq", "BW")
</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
    kFreq chnget "cf"
    kBW chnget "bw"
    
    printks "Freq: %f, BW: %f\n", 0.5, kFreq, kBW
    
    aOut oscili 0.2, kFreq
    outs aOut, aOut
endin

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