XY Pad

xypad is an x/y controller that sends data to Csound on two named channels. The first channel transmits the current position of the ball on the X axis, while the second transmits the position of the ball on the Y axis. The XY pad can function in two unique modes of automation, free and path based. The two modes can be toggled by clicking on the corresponding icon on the bottom left of the xypad control. With either mode selected you can right-click the xypad and create a trajectory or path for the circle's movement. Release the mouse and the circle will start moving. Once the ball is in full flight you can control the speed of the ball using the XY pad slider that will appear once you hover over it with the mouse. To stop the ball simple left click anywhere on the xy pad canvas with the left mouse button.

xypad range identifiers do not permit the setting of custom skew factors. If you wish to set a custom skew factor, or increment value, you will need to do so using Csound code.
Also note that to update the x/y values of a xypad from within your Csound code you should use cabbageSet with a valueX or valueY identifier along with the the first channel name.

xypad channel("chan"), text("string"), textColour("colour"), bounds(x, y, width, height), automatable(val), valuePrefix("valuePrefix"), valuePostfix("valuePostfix"), identChannel("channel"), visible(val), active(val), colour("colour"), fontColour("colour"), alpha(val), parent(val), toFront(), moveBehind("widgetName"), presetIgnore(val), widgetArray("chan", number),

Specific Identifiers

channel("chan") or channel("chan1", "chan2") in the case of widgets that accept two channels such as xypad, soundfiler and range widgets. channel() accepts a string/s that names the channel/s that Cabbage will communicate with Csound on. The current value of this widget can be retrieved in Csound using a chnget, or a cabbageGetValue opcode. Its value can be set using the cabbageSet, or cabbageSetValue opcodes. hrange, vrange, xypad, and soundfiler all take two channels:

hrange, vrange : channel("min", "max") - min and max values

xypad : channel("x", "y") - x and y values

soundfiler : channel("start", "length") - start time and length of user selection, in samples

Channels named should start with a letter and cannot have any white spaces. Note that all widgets should have a unique channel name.

text("string") "string" will be the text that appears on the widget. button widgets take two strings, one for on and one for off.

rangeX(min, max, value) sets the range of the X axis. The first 2 parameters are required. The third is optional. The first two parameters let you set the minimum value and the maximum value. The next parameter determines the initial value.

rangeY(min, max, value) sets the range of the Y axis. The first 2 parameters are required. The third is optional. The first two parameters let you set the minimum value and the maximum value. The next parameter determines the initial value.

textColour("colour") This set the colour of the text passed to text(). If you wish to change the colour of the numbers being displayed use fontColour(). See below. See above for details on valid colours.

Common Identifiers

bounds(x, y, width, height) integer values that set position and size on screen(in pixels).

automatable(val) Default 1. Determines if a widget is automatable by a DAW host. Automatable widgets show up as plug-in parameters in the host. Non-automatable widgets still communicate with Csound but are not accessible by the host. Note that hosts don't allow this parameter to change dynamically -- the plugin will have to be reloaded for any changes to take effect.

value(val) value sets the initial state of the widget. In the case of a keyboard widget, it sets the leftmost ky to appear.

valuePrefix("valuePrefix") Sets the prefix that is prepended to parameter values when displayed in the host and the plugin GUI. Defaults to "". xypad widgets take two strings, one of the x values, and one for the y values.

valuePostfix("valuePostfix") Sets the postfix that is appended to parameter values when displayed in the host and the plugin GUI. This can be helpful to make the units of parameters clear to the user (e.g. "Hz", "dB", etc.). Defaults to "". xypad widgets take two strings, one of the x values, and one for the y values.

identChannel("channel") [!!! DEPRECATED !!!] Although identifier channels still work, they are no longer supported. Please use the new guiMode("queue") system and the cabbageGet and cabbageSet opcodes instead. They are far more efficient then identifiers channel.

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

active(val) Will deactivate a control if 0 is passed. Controls which are deactivate can still be updated from Csound.

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.

alpha(val) A value between 0 and 1 will set the alpha blend value for the entire component. Can be useful if you need to fade widgets in and out.

parent(val) This identifier is can be to set a widget's parent. It should only be used when creating widgets dynamically using the cabbageCreate opcode. See plants for more details.

toFront() Brings a widget to the front of the z order. This identifier takes no arguments and is only intended for use within the Csound orchestra. it makes no sense to call it when declaring the widget.

moveBehind("widgetName") Moves a widget directly behind another. This identifier should only ever be called from your Csound orchestra using a cabbageSet opcode.

This only works with widgets or plants that have the same parent.

presetIgnore(val) Defaults to 0. Set this to 1 to ignore this widget's value when a preset is taken.

widgetArray("chan", number) [!!! DEPRECATED !!!] Deprecated. Please see the section on Managing large numbers of widgets

Example:

<Cabbage>
form caption("XYPad Example") size(400, 650), guiMode("queue"), colour(2, 145, 209) pluginId("def1")
texteditor bounds(22, 337, 361, 294) channel("infoText"), readOnly(1), wrap(1), scrollbars(1)
xypad bounds(26, 20, 260, 250) channel("x", "y") rangeX(0, 400, 105) rangeY(0, 400, 200)
rslider bounds(300, 190, 73, 71) channel("gain") textColour(255, 255, 255, 255), text("Gain") range(0, 2, 1.158, 1, 0.001)
rslider bounds(300, 110, 73, 71) channel("speed") textColour(255, 255, 255, 255), text("Sample Speed") range(-2, 2, -0.384, 1, 0.001)

rslider bounds(300, 32, 73, 71) channel("wetDry") textColour(255, 255, 255, 255), text("Wet/Dry") range(0, 1, 0, 1, 0.001)

checkbox bounds(28, 274, 104, 26) channel("random"), colour:1(147, 210, 0), fontColour:1(255, 255, 255) text("Randomise")
nslider bounds(136, 274, 61, 26) visible(0), channel("updateSpeed") range(0, 20, 2, 1, 0.01) velocity(50)
</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 work, 
; even for commercial purposes, all without asking permission. 

instr 1

    SText  = "An xypad provides quick access two parameters at once. It accepts two channels, one for the X values, and one for the Y values. The ball can be moved around by clicking on it, while a right-click drag will cause it to bounce around the screen.\n\nAlthough two channels are passed to this widget, identifier data should only be sent to the first channel, i.e, the X channel.\n\nIn this example a soundfile is being ring modulated by a modulator signal, taht is itself a result of ring modulation suing two sine waves. The signal is then passed to some comb filters, and finally to a simple stereo reverb unit. The ntrpol opcodes is used to balance the wet and dry signals.\n\nA randomise button is added to add some modulation to various parameters. Note that because the xypad has two channels, we cannot use cabbageSetValue to set its value. We must use cabbageSet instead."
    cabbageSet "infoText", "text", SText
    kX = cabbageGetValue:k("x")
    kY = cabbageGetValue:k("y")
    kSpeed = cabbageGetValue:k("speed")

    kRand, kTrig cabbageGetValue "random"
    cabbageSet kTrig, "updateSpeed", "visible", kRand
    kUpdateSpeed cabbageGetValue "updateSpeed"

    if kRand == 1 then
       cabbageSet metro(kUpdateSpeed), "x", "valueX", random:k(0, 400)
       cabbageSet metro(kUpdateSpeed), "x", "valueY", random:k(0, 400)
       cabbageSetValue "speed", random:k(-2, 2), metro(kUpdateSpeed)    
    endif

    aMod oscili 1, kX
    aCar oscili aMod, kY

    aDryL, aDryR diskin2 "808loop.wav", kSpeed, 0, 1 
    aDelL comb aDryL, 5, 0.25
    aDelR comb aDryR, 5, 0.75

    aPan jspline 1, .1, .5

    aWetL, aWetR reverbsc (aDelL*aCar)*aPan, (aDelR*aCar)*(1-aPan), .7, 1000

    aL ntrpol aWetL, aDryL, cabbageGetValue:k("wetDry")
    aR ntrpol aWetR, aDryR, cabbageGetValue:k("wetDry")

    outs aL*cabbageGetValue:k("gain"), aR*cabbageGetValue:k("gain")


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>