DankMaterialShell/PLUGINS/ExampleWithVariants

Example with Variants Plugin

This plugin demonstrates the dynamic variant system for DankMaterialShell plugins.

What are Variants?

Variants allow a single plugin to create multiple widget instances with different configurations. Each variant appears as a separate widget option in the Bar Settings "Add Widget" menu.

How It Works

Plugin Architecture

1. Single Component: The plugin defines one widget component (VariantWidget.qml)
2. Variant Data: Each variant stores its configuration in plugin settings
3. Dynamic Creation: Variants are created through the plugin's settings UI
4. Widget ID Format: Variants use the format pluginId:variantId (e.g., exampleVariants:variant_1234567890)

Widget Properties

Each variant widget receives:

• pluginService: Reference to PluginService
• pluginId: The base plugin ID (e.g., "exampleVariants")
• variantId: The specific variant ID (e.g., "variant_1234567890")
• variantData: The variant's configuration object

Variant Configuration

This example stores:

{
    id: "variant_1234567890",
    name: "My Variant",
    text: "Display Text",
    icon: "star",
    color: "#FF5722"
}

Creating Your Own Variant Plugin

1. Widget Component

Create a widget that accepts variant data:

Rectangle {
    property var pluginService: null
    property string pluginId: ""
    property string variantId: ""
    property var variantData: null

    // Use variantData for configuration
    property string displayText: variantData?.text || "Default"
}

2. Settings Component

Provide UI to manage variants:

FocusScope {
    property var pluginService: null

    // Create variant
    pluginService.createPluginVariant(pluginId, variantName, variantConfig)

    // Remove variant
    pluginService.removePluginVariant(pluginId, variantId)

    // Update variant
    pluginService.updatePluginVariant(pluginId, variantId, variantConfig)

    // Get all variants
    var variants = pluginService.getPluginVariants(pluginId)
}

3. Plugin Manifest

Standard plugin manifest - no special configuration needed:

{
    "id": "yourPlugin",
    "name": "Your Plugin",
    "component": "./Widget.qml",
    "settings": "./Settings.qml"
}

Use Cases

• Script Runner: Multiple variants running different scripts
• System Monitors: Different monitoring targets (CPU, GPU, Network)
• Quick Launchers: Different apps or commands per variant
• Custom Indicators: Different data sources or APIs
• Time Zones: Multiple clocks for different time zones

API Reference

PluginService Functions

• getPluginVariants(pluginId): Get all variants for a plugin
• getAllPluginVariants(): Get all variants across all plugins
• createPluginVariant(pluginId, name, config): Create new variant
• removePluginVariant(pluginId, variantId): Delete variant
• updatePluginVariant(pluginId, variantId, config): Update variant
• getPluginVariantData(pluginId, variantId): Get specific variant data

Widget Properties

• pluginId: Base plugin identifier
• variantId: Variant identifier (null if no variant)
• variantData: Variant configuration object
• pluginService: PluginService reference