Skip to main content

File Button

fileButton creates a button that opens a native file browser dialog. When clicked, it allows users to select files from their system. The selected file path is sent as a string value through the widget's channel, enabling dynamic audio file loading and other file-based operations in Csound.

Properties (alphabetical)​

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

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.

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:

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.

The fileButton channel returns a string value containing the full path to the selected file. Use cabbageGetValue in Csound to retrieve both the file path and a trigger value (1 when a new file is selected, 0 otherwise).

Directory​

Type: String Default: ""

Sets the initial directory that the file browser will open in. If empty, the browser opens in the system's default location or the last known location (depending on openAtLastKnownLocation).

"directory": "/Users/username/audio_files"

Filters​

Type: String Default: "*"

Specifies file type filters for the file browser. Use wildcards to filter by extension. Multiple filters can be separated by semicolons.

"filters": "*.wav;*.aif;*.mp3"

For all files, use "*" or "*.*".

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

Mode​

Type: String Default: "file"

Determines whether the file browser selects files or directories.

  • "file": Select a single file (default)
  • "directory": Select a directory/folder
"mode": "directory"

Open At Last Known Location​

Type: Boolean Default: true

When true, the file browser will open at the location of the last selected file. When false, it opens at the location specified by directory (or the system default if directory is empty).

"openAtLastKnownLocation": false

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.

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": 4,
  "borderWidth": 0,
  "borderColor": "#dddddd",

  "on": {
    "backgroundColor": "#3d800a",
    "textColor": "#dddddd"
  },
  "off": {
    "backgroundColor": "#3d800a",
    "textColor": "#dddddd"
  },
  "hover": {
    "backgroundColor": "#4ca10c",
    "textColor": "#dddddd"
  },
  "active": {
    "backgroundColor": "#2d6008",
    "textColor": "#dddddd"
  }
},
  • Colors accept named CSS colors, hex (e.g., #RRGGBB or #RRGGBBAA), or rgb/rgba strings.
  • The label text is configured under label.text.on and label.text.off.
  • Border radius/width/color control the button outline.

Csound Usage​

The fileButton returns a string containing the file path and a k-rate trigger value. Here's how to use it in Csound:

//insert example

The trigger value will be 1 for one k-cycle when a new file is selected, then return to 0.