DankMaterialShell/.agents/skills/dms-plugin-dev/references/settings-components-reference.md

Settings Components Reference

All plugin settings use the PluginSettings wrapper. Setting components auto-save on change and auto-load on creation.

PluginSettings Wrapper

import QtQuick
import qs.Common
import qs.Widgets
import qs.Modules.Plugins

PluginSettings {
    pluginId: "yourPlugin"  // Required: must match plugin.json id

    // Setting components go here
}

Important: The plugin must declare "permissions": ["settings_write"] in plugin.json for the settings UI to render. Without it, users see an error.

PluginSettings provides to children:

• saveValue(key, value) - save a setting value
• loadValue(key, defaultValue) - load a setting value
• saveState(key, value) - save plugin state (separate file)
• loadState(key, defaultValue) - load plugin state
• clearState() - clear all plugin state
• Variant management functions (for variant plugins)

StringSetting

Text input field.

StringSetting {
    settingKey: "apiKey"        // Required: storage key
    label: "API Key"            // Required: display label
    description: "Your API key" // Optional: help text
    placeholder: "sk-..."      // Optional: input placeholder
    defaultValue: ""            // Optional: default (default: "")
}

Layout: Vertical stack - label, description, input field.

ToggleSetting

Boolean toggle switch.

ToggleSetting {
    settingKey: "notifications"    // Required: storage key
    label: "Enable Notifications"  // Required: display label
    description: "Show alerts"     // Optional: help text
    defaultValue: true             // Optional: default (default: false)
}

Layout: Horizontal - label/description on left, toggle on right.

SelectionSetting

Dropdown menu.

SelectionSetting {
    settingKey: "theme"           // Required: storage key
    label: "Theme"                // Required: display label
    description: "Color scheme"   // Optional: help text
    options: [                    // Required: array of options
        { label: "Dark", value: "dark" },
        { label: "Light", value: "light" },
        { label: "Auto", value: "auto" }
    ]
    defaultValue: "dark"          // Optional: default value
}

Options can be { label, value } objects or simple strings. Stores the value field, displays the label field.

Layout: Horizontal - label/description on left, dropdown on right.

Reacting to changes:

SelectionSetting {
    settingKey: "updateInterval"
    label: "Update Interval"
    options: [
        { label: "1 minute", value: "60" },
        { label: "5 minutes", value: "300" }
    ]
    defaultValue: "300"
    onValueChanged: (newValue) => {
        console.log("Interval changed to:", newValue)
    }
}

SliderSetting

Numeric slider with min/max.

SliderSetting {
    settingKey: "opacity"      // Required: storage key
    label: "Opacity"           // Required: display label
    description: "Background"  // Optional: help text
    defaultValue: 85           // Optional: default value
    minimum: 0                 // Required: min value
    maximum: 100               // Required: max value
    unit: "%"                  // Optional: unit label shown after value
    leftIcon: "dark_mode"      // Optional: Material icon on left
    rightIcon: "light_mode"    // Optional: Material icon on right
}

ColorSetting

Color picker.

ColorSetting {
    settingKey: "accentColor"      // Required: storage key
    label: "Accent Color"          // Required: display label
    description: "Custom accent"   // Optional: help text
    defaultValue: "#ff5722"        // Optional: default hex color
}

Displays a color swatch that opens a color picker dialog.

ListSetting

Manage a list of items with manual add/remove. Use when you need custom UI for adding items.

ListSetting {
    id: itemList
    settingKey: "items"           // Required: storage key
    label: "Saved Items"          // Required: display label
    description: "Your items"     // Optional: help text
    defaultValue: []              // Optional: default array
    delegate: Component {         // Optional: custom item display
        StyledRect {
            width: parent.width
            height: 40
            radius: Theme.cornerRadius
            color: Theme.surfaceContainerHigh

            StyledText {
                anchors.left: parent.left
                anchors.leftMargin: Theme.spacingM
                anchors.verticalCenter: parent.verticalCenter
                text: modelData.name
                color: Theme.surfaceText
            }

            Rectangle {
                anchors.right: parent.right
                anchors.rightMargin: Theme.spacingM
                anchors.verticalCenter: parent.verticalCenter
                width: 60
                height: 28
                color: removeArea.containsMouse ? Theme.errorHover : Theme.error
                radius: Theme.cornerRadius

                StyledText {
                    anchors.centerIn: parent
                    text: "Remove"
                    color: Theme.errorText
                    font.pixelSize: Theme.fontSizeSmall
                    font.weight: Font.Medium
                }

                MouseArea {
                    id: removeArea
                    anchors.fill: parent
                    hoverEnabled: true
                    cursorShape: Qt.PointingHandCursor
                    onClicked: itemList.removeItem(index)
                }
            }
        }
    }
}

Methods:

• addItem(item) - add an item to the list
• removeItem(index) - remove item at index

ListSettingWithInput

Complete list management with built-in form. Best for collecting structured data.

ListSettingWithInput {
    settingKey: "locations"        // Required: storage key
    label: "Locations"             // Required: display label
    description: "Track zones"     // Optional: help text
    defaultValue: []               // Optional: default array
    fields: [                      // Required: field definitions
        {
            id: "name",            // Required: key in saved object
            label: "Name",         // Required: column header
            placeholder: "Home",   // Optional: input placeholder
            width: 150,            // Optional: column width (default: 200)
            required: true         // Optional: must have value to add
        },
        {
            id: "timezone",
            label: "Timezone",
            placeholder: "America/New_York",
            width: 200,
            required: true
        }
    ]
}

Automatically generates: column headers, input fields, add button with validation, list display, remove buttons.

Mixing Custom UI with Settings

You can interleave regular QML elements with setting components:

PluginSettings {
    pluginId: "myPlugin"

    StyledText {
        width: parent.width
        text: "General Settings"
        font.pixelSize: Theme.fontSizeLarge
        font.weight: Font.Bold
        color: Theme.surfaceText
    }

    StringSetting {
        settingKey: "name"
        label: "Display Name"
    }

    StyledText {
        width: parent.width
        text: "Advanced Settings"
        font.pixelSize: Theme.fontSizeLarge
        font.weight: Font.Bold
        color: Theme.surfaceText
        topPadding: Theme.spacingL
    }

    ToggleSetting {
        settingKey: "debug"
        label: "Debug Mode"
        defaultValue: false
    }
}

Default Values

Define sensible defaults in every setting component. The default is used when no saved value exists:

StringSetting { settingKey: "text"; defaultValue: "Hello" }
ToggleSetting { settingKey: "enabled"; defaultValue: true }
SelectionSetting { settingKey: "mode"; defaultValue: "auto" }
SliderSetting { settingKey: "opacity"; defaultValue: 85 }
ColorSetting { settingKey: "color"; defaultValue: "#ff5722" }
ListSetting { settingKey: "items"; defaultValue: [] }
ListSettingWithInput { settingKey: "data"; defaultValue: [] }