mirror of
https://github.com/AvengeMedia/DankMaterialShell.git
synced 2025-12-07 22:15:38 -05:00
117 lines
3.2 KiB
Markdown
117 lines
3.2 KiB
Markdown
# 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
|