Skip to main content

Image

image creates an on-screen image. Users can interact with an image via mouse events if a channel name has been assigned.

Properties (alphabetical)​

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

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.

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",
                    "range": {"min":0, "max":100, "value":0, "skew":1, "incr":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.

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).

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.

Supported event types:

EventDescription
valueChanged (default)Tracks simple value changes
mousePressLeftTracks presses of left mouse button
mousePressRightTracks presses of right mouse button
mousePressMiddleTracks presses of middle mouse button
mouseMoveXTracks movement along X axis.
mouseMoveYTracks movement along Y axis.
mouseDragXTracks movement along X axis with mouse pressed
mouseDragYTracks movement along Y axis with mouse pressed
mouseInsideReturns 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.

File​

"file": "filename"

This property sets the file to be displayed by the image widget. The following image formats should be supported on most systems: PNG, JPEG, GIF BMP, SVG (Scalable Vector Graphics).

Note: SVG files might not load if they contains scripts or other features that violate security policies (like CORS - Cross-Origin Resource Sharing).

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.*.

Sample​

"sample": {"start":0, "end":-1}

This property sets the visible range of samples in a gentable. You can adjust these properties in real-time to enable zooming.

TableNumber​

"tableNumber": 1

Sets the function table to be displayed by the genTable widget.

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": 4,
  "borderWidth": 1,
  "borderColor": "#dddddd",
  "backgroundColor": "#0295cf"
},
  • When file is set, the image is rendered and backgroundColor is not visible; otherwise a filled rectangle is shown.
  • Colors accept named CSS colors, hex (e.g., #RRGGBB or #RRGGBBAA), or rgb/rgba strings.

Example​

<Cabbage>
[
    {"type": "form", "caption": "Label Example", "size": {"width": 500, "height": 500}, "pluginId": "def1"},
    {
        "type": "image",
        "channels": [
            {
                "id": "image1X",
                "event": "mouseMoveX",
                "range": {"min": 0, "max": 1, "defaultValue": 0, "skew": 1, "increment": 0.01}
            },
            {
                "id": "image1Y",
                "event": "mouseMoveY",
                "range": {"min": 0, "max": 1, "defaultValue": 0, "skew": 1, "increment": 0.01}
            }
        ],
        "bounds": {"left": 10, "top": 10, "width": 480, "height": 480},
        "automatable": 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 = 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
    imageX:k, trigX:k = cabbageGetValue:k("image1X")
    imageY:k, trigY:k = cabbageGetValue:k("image1Y")
    printf("Current Mouse X Position: %f\n", trigX, imageX)
    printf("Current Mouse Y Position: %f\n", trigY, imageY)
endin


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