plugins: support for multiple widgets per-plugin (variants)

2025-12-11 07:52:50 -05:00 · 2025-10-06 12:33:58 -04:00
parent 11a1af89f4
commit 89793d2d62
10 changed files with 676 additions and 14 deletions
--- a/PLUGINS/ExampleWithVariants/README.md
+++ b/PLUGINS/ExampleWithVariants/README.md
@@ -0,0 +1,116 @@
+# 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:
+```javascript
+{
+    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:
+
+```qml
+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:
+
+```qml
+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:
+
+```json
+{
+    "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