UserSettings
File: Rhapsodist/Core/Includes/UserSettings.js · Namespace: UserSettings
Overview
UserSettings builds and manages the Settings window (Engine, Audio, MIDI I/O, Instrument, Automation, About), and provides a general-purpose key/value store for user preferences, independent of the preset system.
Adding a settings page
Any ScriptPanel that’s a direct child of pnlSettings (other than pnlSettingsMenu itself) automatically gets a sidebar entry, using its text property as the label.
State and persistence
Settings written via setProperty persist in AppData/UserSettings.json across every preset and project session, they are not part of any preset. Engine-settings-page values (Max Voices, Disk Mode, custom BPM, Lazy Load, and others) are persisted the same way automatically.
Usage
UserSettings wires itself up once Core.js is included. Call UserSettings.setProperty()/getProperty() from any script to store or read a preference outside the preset system, scoped by name:
// Store a global (not project-specific) preference
UserSettings.setProperty("rhapsody", "preferDarkMode", true);
// Read it back later, from anywhere Core has already loaded
local preferDark = UserSettings.getProperty("rhapsody", "preferDarkMode");
Look and Feel
| Function | Draws |
|---|---|
drawSettingsPanel | The whole Settings window panel, replacing the default drawing entirely. |
drawSettingsPanelBackground | The Settings window panel’s background fill and border, keeping the title text and inner divider line drawn by default. |
Public API
| Function | Description | Returns |
|---|---|---|
setProperty(scope: string, key: string, value: Colour) | Writes a value to AppData/UserSettings.json, namespaced by scope ("rhapsody" for global settings, or an expansion name for project-specific scope). This is Rhapsodist’s general runtime preference store. The value parameter is typed Colour in the source, but in practice it’s used to store any JSON-storable value (string, number, boolean). | — |
getProperty(scope: string, key: string) | Reads a value previously written with setProperty, or undefined. | — |
show() | Opens the Settings window. | — |
hide() | Closes the Settings window. | — |
setMenuIcon(menuItem: string, iconCodePoint: string) | Sets the Phosphor icon shown next to a Settings sidebar entry. | — |
Internal Reference
| Function | Description | Returns |
|---|---|---|
getAllSettingsPanels() | Finds every component matching .*pnl.*Settings.*, excluding menu/container panels. Its result isn’t referenced elsewhere in the source; populateMenuItems() is what actually builds the sidebar. | Array |
populateMenuItems() | Builds pnlSettingsMenu’s item list (and height) from the text property of each ScriptPanel that’s a direct child of pnlSettings (other than pnlSettingsMenu itself). | — |
getScopedPropertiesFromFile(scope: string) | Reads the scope object out of UserSettings.json, or {} if it isn’t defined. Shared by getProperty() and restoreEngineSettings(). | ComplexType |
restoreEngineSettings() | Restores each Engine-settings component’s value from UserSettings.json (falling back to built-in defaults for Max Voices, Disk Mode, BPM, and Lazy Load), then sets settingsLoaded = true. Runs once, shortly after load. | — |
toggleAllMidiChannels(state) | Enables or disables all 16 MIDI input channels at once, used when the “all channels” toggle or a double-click on a channel dot is triggered. | — |
getAboutInfo() | Returns project/expansion name, version, and other Engine.getProjectInfo() fields used to render the About page. | object |
Broadcasters
| Broadcaster | Description |
|---|---|
bcEngineSettingChanged | Fires when cmbStreamingMode, cmbMaxVoices, knbGlobalBpm, btnLazyLoad, or btnTooltips changes value, once settingsLoaded is true. Persists the new value via setProperty(), scoped to the current project name. |