### Install from Source with C++ Plugin (Arch Linux)

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Installs build and runtime dependencies for Arch Linux, then clones and builds the widget and C++ plugin. The install script runs CMake twice: first to install the QML plasmoid locally, then to build and install the C++ plugin system-wide.

```sh
# Install build and runtime dependencies (Arch Linux)
sudo pacman -S git gcc cmake extra-cmake-modules libplasma spectacle python python-dbus python-gobject

# Clone and build+install widget + C++ plugin
git clone https://github.com/luisbocanegra/plasma-panel-colorizer
cd plasma-panel-colorizer
./install.sh
# The script runs cmake twice:
#   1. Installs the QML plasmoid to ~/.local (no sudo)
#   2. Builds and installs the C++ plugin system-wide (requires sudo)
```

--------------------------------

### Install Panel Colorizer with Nix (flakes)

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Install the Plasma Panel Colorizer widget using the 'nix profile install' command for systems using flakes.

```sh
nix profile install nixpkgs#plasma-panel-colorizer
```

--------------------------------

### NixOS / Nix Package Manager Installation

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Installs the Panel Colorizer package using NixOS system packages or Home-manager. Also shows how to install imperatively using flakes.

```nix
# NixOS system packages
environment.systemPackages = with pkgs; [ plasma-panel-colorizer ];

# Home-manager
home.packages = with pkgs; [ plasma-panel-colorizer ];

# Imperative (flakes)
nix profile install nixpkgs#plasma-panel-colorizer
```

--------------------------------

### Install Panel Colorizer with Nix (non-flakes)

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Install the Plasma Panel Colorizer widget using the 'nix-env' command for systems not using flakes.

```sh
nix-env -iA nixpkgs.plasma-panel-colorizer
```

--------------------------------

### Install Panel Colorizer with Home-manager

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Install the Plasma Panel Colorizer widget using the home-manager configuration.

```nix
home.packages = with pkgs;
  [ plasma-panel-colorizer ];
```

--------------------------------

### Preset File Format Example

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

An example of a preset file (`settings.json`) used to customize panel appearance. This file defines specific settings for background, radius, and shadow.

```json
// ~/.config/panel-colorizer/presets/dark-floating/settings.json
{
    "nativePanel": {
        "background": { "enabled": false, "opacity": 0.0, "shadow": false },
        "floatingDialogs": true
    },
    "panel": {
        "normal": {
            "enabled": true,
            "backgroundColor": {
                "enabled": true,
                "sourceType": 0,
                "custom": "#1e1e2e",
                "alpha": 0.92
            },
            "radius": {
                "enabled": true,
                "corner": { "topLeft": 12, "topRight": 12, "bottomLeft": 12, "bottomRight": 12 }
            },
            "border": { "enabled": false },
            "shadow": {
                "background": {
                    "enabled": true,
                    "color": { "sourceType": 0, "custom": "#000000", "alpha": 0.4 },
                    "size": 16, "xOffset": 0, "yOffset": 4
                }
            }
        }
    },
    "stockPanelSettings": {
        "floating": { "enabled": true, "value": true }
    }
}
```

--------------------------------

### Install on Immutable Distributions

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Installs the widget or C++ plugin using immutable install scripts. Configures the QML module path for Plasma to find the widget after logging out and back in.

```sh
# Use the -immutable install scripts
./install-immutable.sh          # widget only
./install-plugin-immutable.sh   # C++ plugin only

# Add to ~/.config/plasma-workspace/env/path.sh so the QML module is found:
export QML_IMPORT_PATH="$HOME/.local/lib64/qml:$HOME/.local/lib/qml:$QML_IMPORT_PATH"
# Then log out and back in.
```

--------------------------------

### Clone and Install Plasma Panel Colorizer

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Clones the Plasma Panel Colorizer repository from GitHub and executes the installation script. This is part of the build-from-source process.

```sh
git clone https://github.com/luisbocanegra/plasma-panel-colorizer
cd plasma-panel-colorizer
./install.sh
```

--------------------------------

### Example MO File Path

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/package/translate/ReadMe.md

This is an example of the directory structure for compiled binary translation files (.mo) that are bundled with the plasmoid.

```plaintext
package/contents/locale/fr/LC_MESSAGES/plasma_applet_luisbocanegra.panel.colorizer.mo
```

--------------------------------

### Install Widget Only (No C++ Plugin)

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Builds and installs only the QML plasmoid, omitting the C++ plugin for features like blur and icon replacement. Ensures executable permissions for helper scripts.

```sh
cmake -B build/plasmoid -S . -DINSTALL_PLASMOID=ON -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build/plasmoid
cmake --install build/plasmoid
chmod 700 "$HOME/.local/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/tools/list_presets.sh"
chmod 700 "$HOME/.local/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/tools/gdbus_get_signal.sh"
```

--------------------------------

### Install Panel Colorizer on Arch Linux (AUR)

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Install the Plasma Panel Colorizer widget on Arch Linux using the AUR helper 'yay'.

```sh
yay -S plasma6-applets-panel-colorizer
```

--------------------------------

### Install Build Dependencies for Plasma Panel Colorizer

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Installs dependencies required to build the Plasma Panel Colorizer widget from source on Arch Linux, Fedora, and Kubuntu. Includes development tools and libraries.

```sh
# Arch Linux
sudo pacman -S git gcc cmake extra-cmake-modules libplasma spectacle python python-dbus python-gobject
# Fedora
sudo dnf install git gcc-c++ cmake extra-cmake-modules libplasma-devel spectacle python3 python3-dbus python3-gobject
# Kubuntu
sudo apt install git build-essential cmake extra-cmake-modules libplasma-dev kde-spectacle python3 python3-dbus python3-gi
```

--------------------------------

### Install Runtime Dependencies for Plasma Panel Colorizer

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Installs necessary runtime dependencies for the Plasma Panel Colorizer widget on Arch Linux, Fedora, and Kubuntu. Spectacle is required for creating preset previews.

```sh
# Arch Linux
sudo pacman -S spectacle python python-dbus python-gobject
# Fedora
sudo dnf install spectacle python3 python3-dbus python3-gobject
# Kubuntu
sudo apt install kde-spectacle python3 python3-dbus python3-gi
```

--------------------------------

### Install Panel Colorizer on NixOS

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Add the Plasma Panel Colorizer widget to your system packages in NixOS configuration.

```nix
environment.systemPackages = with pkgs;
  [ plasma-panel-colorizer ];
```

--------------------------------

### Build Plasma Panel Colorizer Plugin

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/plugin/CMakeLists.txt

Defines the plugin library, links against Qt6 libraries, and specifies installation directories for the plugin and its QML module definition.

```cmake
set(PLUGIN_NAME "panelcolorizerplugin")
set(LIB_NAME "panelcolorizer")

add_library(${PLUGIN_NAME} SHARED ${PLUGIN_NAME}.cpp ${LIB_NAME}.cpp)

target_link_libraries(${PLUGIN_NAME}
    Qt6::Gui
    Qt6::Qml
)

install(TARGETS ${PLUGIN_NAME} DESTINATION ${KDE_INSTALL_QMLDIR}/org/kde/plasma/${LIB_NAME})
install(FILES qmldir DESTINATION ${KDE_INSTALL_QMLDIR}/org/kde/plasma/${LIB_NAME})
```

--------------------------------

### Get Icon Hash with PanelColorizer QML

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Compute the SHA-1 hash of a QIcon object for system-tray icon replacement matching. This is useful for matching replacement rules against tray icons.

```qml
// Icon hash — used to match replacement rules against tray icons
const hash = panelColorizer.getIconHash(trayIcon, /*logIconNames*/ false);
// hash === "a3f1c2..." (SHA-1 hex of the first available icon pixmap)
// Used by Utils.getTrayIconFromRules() to look up replacement icon names
```

--------------------------------

### Resolve Widget Settings with Utils.getItemCfg

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Computes effective appearance settings for a panel element by layering global, preset, user, and element state overrides. Use this to get the final configuration for a widget's appearance.

```javascript
// itemType: Enums.ItemType (WidgetItem | TrayItem | TrayArrow | PanelBgItem)
// widgetName: plasmoid pluginName, e.g. "org.kde.plasma.digitalclock"
// widgetId: plasmoid id (integer), -1 for tray StatusNotifier items
// config: current globalSettings JSON object
// globalOverrides: user's persistent overrides JSON object
const result = Utils.getItemCfg(
    Enums.ItemType.WidgetItem,
    "org.kde.plasma.digitalclock",
    42,
    config,
    globalOverrides,
    /*busy*/    false,
    /*needsAttention*/ false,
    /*hovered*/ true,
    /*expanded*/ false
);
// result.settings — effective appearance config to apply
// result.override — true if an override was applied

// Example: read the effective background color source type
console.log(result.settings.backgroundColor.sourceType); // e.g. 1 (System color)
```

--------------------------------

### Run kpac i18n Script

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/package/translate/ReadMe.md

Use this script to parse QML files for translatable strings, update POT files, merge changes into PO files, and convert PO files to MO files for bundling.

```bash
python3 ./kpac i18n
```

--------------------------------

### Generating Presets List Documentation

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/package/contents/ui/presets/README.md

Command to run from the project root to update the README.md file with any new or modified presets. This script regenerates the documentation based on the current presets.

```sh
./gen-presets-list-doc.sh
```

--------------------------------

### Interactive Preset Switching with fzf

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

A one-liner using fzf, qdbus6, and jq to preview and switch presets interactively. It searches for preset directories and allows selection via fzf.

```sh
find /usr/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/presets/ ~/.local/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/presets/ ~/.config/panel-colorizer/presets -mindepth 1 -prune -type d 2>/dev/null -mindepth 1 -prune -type d | fzf --bind 'enter:execute(qdbus6 luisbocanegra.panel.colorizer.c337.w2346 /preset preset {})' --preview 'jq --color-output . {}/settings.json'
```

--------------------------------

### Island Section Types Enumeration

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Categorizes widgets within a visual group or 'island'. Use these to define whether a widget is standalone, the start, middle, or end of an island.

```JavaScript
// enum.js — IslandSectionType
Enum.IslandSectionType.Default  // 0 — standalone widget
Enum.IslandSectionType.Start    // 1 — first widget of an island
Enum.IslandSectionType.Middle   // 2 — interior widget of an island
Enum.IslandSectionType.End      // 3 — last widget of an island
```

--------------------------------

### Preset Folder Structure

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/package/contents/ui/presets/README.md

Defines the required files and directory structure for a new preset. Ensure 'settings.json' contains the color configuration and 'preview.png' visually represents the preset.

```sh
PresetName/
├── settings.json
└── preview.png
```

--------------------------------

### Select Auto-loading Preset with Utils.getPresetName

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Evaluates the current panel window state against auto-loading configuration to return the path of the preset to be applied. Priority is given to fullscreen, then maximized, and so on.

```javascript
// panelState is a live object with boolean flags:
const panelState = {
    fullscreenWindow: false,
    maximized:        true,  // <-- this is active
    touchingWindow:   false,
    activeWindow:     false,
    visibleWindows:   true,
    floating:         true,
    activity:         "some-activity-id",
};

// presetAutoloading config (stored in the plasmoid config key "presetAutoloading")
const presetAutoloading = {
    enabled:         true,
    fullscreenWindow: "",
    maximized:        "/home/user/.config/panel-colorizer/presets/dark-opaque/",
    touchingWindow:   "",
    activeWindow:     "",
    visibleWindows:   "",
    floating:         "/home/user/.config/panel-colorizer/presets/floating/",
    activity:         {},   // { "activity-id": "/path/to/preset/" }
    normal:           "/home/user/.config/panel-colorizer/presets/default/",
};

// Priority: fullscreenWindow > maximized > touchingWindow > activeWindow >
//           visibleWindows > floating > activity > normal
const presetPath = Utils.getPresetName(panelState, presetAutoloading);
// Returns "/home/user/.config/panel-colorizer/presets/dark-opaque/"
// because maximized is true and has a configured preset
```

--------------------------------

### Utils.getPresetName

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Evaluates the current panel window state against the user's auto-loading configuration and returns the path of the preset that should be applied, respecting a fixed priority order.

```APIDOC
## `Utils.getPresetName(panelState, presetAutoloading)` — Auto-loading preset selector

Evaluates the current panel window state against the user's auto-loading configuration and returns the path of the preset that should be applied, respecting a fixed priority order.

```js
// panelState is a live object with boolean flags:
const panelState = {
    fullscreenWindow: false,
    maximized:        true,  // <-- this is active
    touchingWindow:   false,
    activeWindow:     false,
    visibleWindows:   true,
    floating:         true,
    activity:         "some-activity-id",
};

// presetAutoloading config (stored in the plasmoid config key "presetAutoloading")
const presetAutoloading = {
    enabled:         true,
    fullscreenWindow: "",
    maximized:        "/home/user/.config/panel-colorizer/presets/dark-opaque/",
    touchingWindow:   "",
    activeWindow:     "",
    visibleWindows:   "",
    floating:         "/home/user/.config/panel-colorizer/presets/floating/",
    activity:         {},   // { "activity-id": "/path/to/preset/" }
    normal:           "/home/user/.config/panel-colorizer/presets/default/",
};

// Priority: fullscreenWindow > maximized > touchingWindow > activeWindow >
//           visibleWindows > floating > activity > normal
const presetPath = Utils.getPresetName(panelState, presetAutoloading);
// Returns "/home/user/.config/panel-colorizer/presets/dark-opaque/"
// because maximized is true and has a configured preset
```
```

--------------------------------

### Plasma Version Comparison

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Provides semantic version comparison methods like `isGreaterThan`, `isLowerThan`, and `isEqual`. Useful for applying compatibility workarounds based on the Plasma release version. The `Utils.getSystemTrayState` function demonstrates its internal usage.

```javascript
// Available methods: compare(), isLowerThan(), isGreaterThan(), isEqual()
// VersionDifference enum: Lower=0, Greater=1, Equal=2

const plasmaVer = new Version("6.3.80");

plasmaVer.isGreaterThan("6.2.0");   // true
plasmaVer.isLowerThan("6.2.0");     // false
plasmaVer.isEqual("6.3.80");        // true
plasmaVer.isGreaterThan("6.4.0");   // false

// Used internally to select D-Bus API variant:
// Plasma > 6.3.5 uses applet.systemTrayState directly;
// older versions use applet.internalSystray.systemTrayState
const systemTrayState = Utils.getSystemTrayState(applet, new Version("6.3.80"));
```

--------------------------------

### Interactive Preset Switching for All Panels with fzf

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Similar to the single-panel version, this command uses fzf to preview and apply presets to all panels. It utilizes dbus-send for signal transmission.

```sh
find /usr/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/presets/ ~/.local/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/presets/ ~/.config/panel-colorizer/presets -mindepth 1 -prune -type d 2>/dev/null -mindepth 1 -prune -type d | fzf --bind 'enter:execute(dbus-send --session --type=signal /preset luisbocanegra.panel.colorizer.all.preset string:{})' --preview 'jq --color-output . {}/settings.json'
```

--------------------------------

### D-Bus Method Call Abstraction (Primary)

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Wraps asynchronous D-Bus method calls using the native Qt/KDE `org.kde.plasma.workspace.dbus` API. Preferred for Plasma versions 6.2 and newer. Handles method invocation and response processing, including error checking.

```qml
// DBusPrimary usage — native QtDBus (preferred)
DBusPrimary {
    id: dbusCall
    service:    "org.kde.KWin"
    objectPath: "/KWin"
    iface:      "org.kde.KWin"
    method:     "reconfigure"
    arguments:  []
}
// Invoke and handle response:
dbusCall.call(function(reply) {
    if (reply.isError) {
        console.error("D-Bus error:", reply.error.message);
    } else {
        console.log("KWin reconfigured, result:", reply.value);
    }
});
```

--------------------------------

### Set individual configuration properties at runtime

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Allows setting individual configuration properties for a panel instance or all panels at runtime via D-Bus.

```APIDOC
## Set individual configuration properties at runtime

```sh
# Syntax: 'dot.path.to.key {"field": value}'  or  'dot.path value'
# No validation — malformed input will break the configuration!

# Hide the panel (stockPanelSettings.visible)
qdbus luisbocanegra.panel.colorizer.c337.w2346 /preset \
    luisbocanegra.panel.colorizer.c337.w2346.property \
    'stockPanelSettings.visible {"enabled": true, "value": false}'

# Restore panel visibility
qdbus luisbocanegra.panel.colorizer.c337.w2346 /preset \
    luisbocanegra.panel.colorizer.c337.w2346.property \
    'stockPanelSettings.visible {"enabled": false, "value": true}'

# Set panel background alpha to 50% on ALL panels
dbus-send --session --type=signal /preset \
    luisbocanegra.panel.colorizer.all.property \
    string:'panel.normal.backgroundColor.alpha 0.5'

# Enable native panel background on all panels
dbus-send --session --type=signal /preset \
    luisbocanegra.panel.colorizer.all.property \
    string:'nativePanel.background.enabled true'
```
```

--------------------------------

### Apply Preset to All Panels

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

This command applies a preset to all panels simultaneously. The preset path should be enclosed in quotes.

```sh
dbus-send --session --type=signal /preset luisbocanegra.panel.colorizer.all.preset string:"/path/to/preset dir/"
```

--------------------------------

### Interactive Preset Switcher for a Single Panel

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

An interactive fuzzy-finder script to select and apply presets to a single panel instance. It searches for presets in common locations and uses `fzf` for selection.

```sh
# Interactive fuzzy-finder (fzf) preset switcher for a single panel
find /usr/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/presets/ \
     ~/.local/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/presets/ \
     ~/.config/panel-colorizer/presets \
     -mindepth 1 -prune -type d 2>/dev/null | \
fzf --bind 'enter:execute(qdbus6 luisbocanegra.panel.colorizer.c337.w2346 /preset preset {})' \
    --preview 'jq --color-output . {}/settings.json'
```

--------------------------------

### Apply Preset to All Panels Simultaneously via D-Bus

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Apply a colorizer preset to all running panel instances simultaneously using a D-Bus signal. This is a convenient way to apply a consistent theme across all panels.

```sh
# Apply the same preset to ALL panels simultaneously
dbus-send --session --type=signal /preset \
    luisbocanegra.panel.colorizer.all.preset \
    string:"/home/user/.config/panel-colorizer/presets/dark-opaque/"
```

--------------------------------

### Deep-merge Preset onto Defaults (`Utils.mergeConfigs`)

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Recursively merges a source configuration (defaults) into a new configuration (preset), filling in missing keys. Arrays are shallow-copied. Use this to apply custom settings from a preset file to the default configuration.

```javascript
import "code/utils.js" as Utils

// Loaded preset JSON (partial — only overrides what changed)
const presetJson = {
    panel: {
        normal: {
            enabled: true,
            backgroundColor: { enabled: true, sourceType: 0, custom: "#1e1e2e", alpha: 0.85 }
        }
    }
};

// Merge: missing keys are filled from defaultConfig
const merged = Utils.mergeConfigs(defaultConfig, presetJson);
// merged.panel.normal.radius.enabled === false  (inherited from default)
// merged.panel.normal.backgroundColor.custom === "#1e1e2e"  (from preset)
// merged.widgets.normal.spacing === 4           (untouched default)

```

--------------------------------

### D-Bus Method Call Abstraction (Fallback)

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Provides an identical API surface to `DBusPrimary` but shells out to `gdbus call` for compatibility with older Plasma versions (e.g., 6.1). Use this when the native DBus API is unavailable. Handles method invocation and response processing.

```qml
// DBusFallback usage — identical API surface, shells to gdbus
DBusFallback {
    id: dbusFallback
    service:    "org.kde.plasmashell"
    objectPath: "/PlasmaShell"
    iface:      "org.kde.PlasmaShell"
    method:     "evaluateScript"
    arguments:  ["var panel = panelById(3); panel.floating = true;"]
}
dbusFallback.call(function(reply) {
    console.log("Script result:", reply.value);
});
```

--------------------------------

### Configure QML_IMPORT_PATH for Immutable Distributions

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Sets the QML_IMPORT_PATH environment variable for the C++ plugin to work on immutable distributions. This file should be placed in ~/.config/plasma-workspace/env/.

```sh
export QML_IMPORT_PATH="$HOME/.local/lib64/qml:$HOME/.local/lib/qml:$QML_IMPORT_PATH"
```

--------------------------------

### Toggle Visibility for All Panels

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

This command allows toggling the visibility of all panels simultaneously. Ensure the property string is correctly formatted to avoid breaking the configuration.

```sh
# hide all panels
dbus-send --session --type=signal /preset luisbocanegra.panel.colorizer.all.property string:'stockPanelSettings.visible {"enabled": true, "value": false}'
# to revert:
dbus-send --session --type=signal /preset luisbocanegra.panel.colorizer.all.property string:'stockPanelSettings.visible {"enabled": false, "value": true}'
```

--------------------------------

### Apply a preset to a specific panel instance

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Applies a color preset to a specific panel instance using its D-Bus service.

```APIDOC
## Apply a preset to a specific panel instance

```sh
# Apply by absolute preset directory path
qdbus6 luisbocanegra.panel.colorizer.c337.w2346 /preset preset \
    /home/user/.config/panel-colorizer/presets/dark-opaque/

# Apply the same preset to ALL panels simultaneously
dbus-send --session --type=signal /preset \
    luisbocanegra.panel.colorizer.all.preset \
    string:"/home/user/.config/panel-colorizer/presets/dark-opaque/"

# Interactive fuzzy-finder (fzf) preset switcher for a single panel
find /usr/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/presets/ \
     ~/.local/share/plasma/plasmoids/luisbocanegra.panel.colorizer/contents/ui/presets/ \
     ~/.config/panel-colorizer/presets \
     -mindepth 1 -prune -type d 2>/dev/null | \
fzf --bind 'enter:execute(qdbus6 luisbocanegra.panel.colorizer.c337.w2346 /preset preset {})' \
    --preview 'jq --color-output . {}/settings.json'
```
```

--------------------------------

### Toggle Panel Visibility

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Use this command to toggle the visibility of a specific panel. Incorrectly formatted input can break the configuration.

```sh
# hide
qdbus luisbocanegra.panel.colorizer.c337.w2346 /preset luisbocanegra.panel.colorizer.c337.w2346.property 'stockPanelSettings.visible {"enabled": true, "value": false}'
# to revert:
qdbus luisbocanegra.panel.colorizer.c337.w2346 /preset luisbocanegra.panel.colorizer.c337.w2346.property 'stockPanelSettings.visible {"enabled": false, "value": true}'
```

--------------------------------

### Run kpac localetest Script

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/package/translate/ReadMe.md

This script converts PO files to MO files and then runs plasmoidviewer for testing translations.

```bash
python3 ./kpac localetest
```

--------------------------------

### PanelColorizer QML Plugin

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

The PanelColorizer QML plugin provides functionalities for generating clip masks for Wayland windows and computing SHA-1 hashes for system-tray icons.

```APIDOC
## `PanelColorizer` C++ plugin — Mask generation and icon hashing

The optional C++ QML extension (`org.kde.plasma.panelcolorizer`) provides two capabilities not achievable in pure QML: (1) composing per-panel rounded-rectangle clip masks for the `WaylandWindow` blur region, and (2) computing SHA-1 pixel hashes of `QIcon` objects for system-tray icon replacement matching.

```qml
import org.kde.plasma.panelcolorizer 1.0 as PC

PC.PanelColorizer {
    id: panelColorizer

    // Update (or create) a mask region for widget at index i
    // Parameters: index, rect, topLeft/topRight/bottomLeft/bottomRightRadius,
    //             offset, radiusCompensation, visible
    Component.onCompleted: {
        panelColorizer.updatePanelMask(
            0,                      // widget index
            Qt.rect(0, 0, 120, 44), // bounding rect
            8, 8, 8, 8,             // corner radii (px)
            Qt.point(0, 0),         // offset
            1,                      // radius compensation (anti-aliasing hack)
            true                    // visible
        );
    }

    // mask (QRegion) and hasRegions are reactive properties:
    onMaskChanged: {
        panelWindow.mask = panelColorizer.mask;
    }
    onHasRegionsChanged: {
        if (!panelColorizer.hasRegions) panelWindow.mask = null;
    }

    // Remove the last visible region (e.g. when a widget is removed)
    // panelColorizer.popLastVisibleMaskRegion()
}

// Icon hash — used to match replacement rules against tray icons
const hash = panelColorizer.getIconHash(trayIcon, /*logIconNames*/ false);
// hash === "a3f1c2..." (SHA-1 hex of the first available icon pixmap)
// Used by Utils.getTrayIconFromRules() to look up replacement icon names
```
```

--------------------------------

### Apply Preset to Specific Panel

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Use this command to apply a specific preset to a single panel. Ensure the path to the preset directory is absolute.

```sh
qdbus6 luisbocanegra.panel.colorizer.c337.w2346 /preset preset /path/to/preset/dir/
```

--------------------------------

### Default Configuration Schema (`globals.js`)

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Defines the default configuration object for the Plasma Panel Colorizer, serving as a schema for loaded presets. It covers panel, widget, and tray widget appearance, native panel controls, stock panel settings, and per-widget overrides.

```javascript
// globals.js — top-level defaultConfig object
const defaultConfig = {
    // Panel-level appearance (background, fg color, border, shadow, radius, margin)
    panel: {
        normal:         basePanelConfig,  // base state
        busy:           basePanelConfig,
        hovered:        basePanelConfig,
        needsAttention: basePanelConfig,
        expanded:       basePanelConfig,
    },
    // All non-tray widgets
    widgets: {
        normal:         baseWidgetConfig, // includes spacing: 4
        busy:           baseWidgetConfig,
        hovered:        baseWidgetConfig,
        needsAttention: baseWidgetConfig,
        expanded:       baseWidgetConfig,
    },
    // System-tray items
    trayWidgets: {
        normal:               baseTrayConfig,
        busy:                 baseTrayConfig,
        hovered:              baseTrayConfig,
        needsAttention:       baseTrayConfig,
        expanded:             baseTrayConfig,
        wideTrayArrow:        false,
        customCellSizeEnabled: false,
        customCellSize:       22,
    },
    // Controls the native Plasma panel background/shadow/opacity
    nativePanel: {
        background: { enabled: true, opacity: 1.0, shadow: true },
        floatingDialogs: false,
        floatingDialogsAllowOverride: false,
        fillAreaOnDeFloat: true,
    },
    // Stock panel geometry/visibility settings (applied via Plasma scripting API)
    stockPanelSettings: baseStockPanelSettings,
    // Per-widget appearance overrides
    configurationOverrides: { overrides: {}, associations: [] },
};

// Background/foreground color config object shape (baseBgColor / baseFgColor)
const baseBgColor = {
    enabled:          false,
    sourceType:       1,          // Enums.ColorSourceType: 0=Custom,1=System,2=List,3=Random,4=Follow
    custom:           "#013eff",
    systemColor:      "backgroundColor",
    systemColorSet:   "View",
    list:             ["#ED8796", "#A6DA95", ...],
    followColor:      0,          // 0=panel,1=parent tray,2=parent
    alpha:            1,
    saturationEnabled: false,
    saturationValue:  0.5,
    lightnessEnabled: false,
    lightnessValue:   0.5,
    animation: { enabled: false, interval: 3000, smoothing: 800 },
    gradient: { stops: [{color:"#ff0000", position:0}, ...], orientation: 0 },
    image:    { source: "", fillMode: 2 },
};

// Border config shape
const baseBorder = {
    enabled:     false,
    width:       0,
    customSides: false,
    custom: {
        widths:  { left: 0, bottom: 3, right: 0, top: 0 },
        margin:  baseMargin,
        radius:  baseRadius,
    },
    color: baseBorderColor,
};

// Stock panel settings shape (each property is {enabled, value})
const baseStockPanelSettings = {
    position:   { enabled: false, value: "top" },       // "top"|"bottom"|"left"|"right"
    alignment:  { enabled: false, value: "center" },    // "left"|"center"|"right"
    lengthMode: { enabled: false, value: "fill" },      // "fill"|"fit"|"custom"
    visibility: { enabled: false, value: "none" },      // "none"|"autohide"|"dodgewindows"|...
    floating:   { enabled: false, value: false },
    thickness:  { enabled: false, value: 48 },
    opacity:    { enabled: false, value: "adaptive" },
    visible:    { enabled: false, value: true },
    screen:     { enabled: false, value: 0 },
};

```

--------------------------------

### Enable Native Panel Background on All Panels via D-Bus

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Enable the native panel background feature across all panel instances using a D-Bus signal. This command sets the `nativePanel.background.enabled` property to true.

```sh
# Enable native panel background on all panels
dbus-send --session --type=signal /preset \
    luisbocanegra.panel.colorizer.all.property \
    string:'nativePanel.background.enabled true'
```

--------------------------------

### Apply Preset to Specific Panel Instance via D-Bus

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Apply a colorizer preset to a specific panel instance using its unique session-bus service name. This command targets a single panel identified by its service name.

```sh
# Apply by absolute preset directory path
qdbus6 luisbocanegra.panel.colorizer.c337.w2346 /preset preset \
    /home/user/.config/panel-colorizer/presets/dark-opaque/
```

--------------------------------

### Update Panel Mask with PanelColorizer QML

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Use this QML component to generate per-panel clip masks for Wayland window blur regions. It requires importing the PanelColorizer plugin and can be configured with various parameters for corner radii and visibility.

```qml
import org.kde.plasma.panelcolorizer 1.0 as PC

PC.PanelColorizer {
    id: panelColorizer

    // Update (or create) a mask region for widget at index i
    // Parameters: index, rect, topLeft/topRight/bottomLeft/bottomRightRadius,
    //             offset, radiusCompensation, visible
    Component.onCompleted: {
        panelColorizer.updatePanelMask(
            0,                      // widget index
            Qt.rect(0, 0, 120, 44), // bounding rect
            8, 8, 8, 8,             // corner radii (px)
            Qt.point(0, 0),         // offset
            1,                      // radius compensation (anti-aliasing hack)
            true                    // visible
        );
    }

    // mask (QRegion) and hasRegions are reactive properties:
    onMaskChanged: {
        panelWindow.mask = panelColorizer.mask;
    }
    onHasRegionsChanged: {
        if (!panelColorizer.hasRegions) panelWindow.mask = null;
    }

    // Remove the last visible region (e.g. when a widget is removed)
    // panelColorizer.popLastVisibleMaskRegion()
}
```

--------------------------------

### Persistent D-Bus Signal Listener

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Monitors a D-Bus signal continuously using `gdbus_get_signal.sh` and emits `signalReceived(message)` on each signal. It's used for external commands like preset switching. Configuration includes bus type, service, interface, path, method, and instance ID. Cleanup is automatic.

```qml
DBusSignalMonitor {
    id: signalMonitor
    enabled:    cfg_enableDBusService
    busType:    "session"
    service:    "luisbocanegra.panel.colorizer.c337.w2346"
    iface:      "luisbocanegra.panel.colorizer.c337.w2346"
    path:       "/preset"
    method:     "preset"
    instanceId: plasmoid.id

    onSignalReceived: function(message) {
        // message = absolute path to preset directory
        loadPresetFromPath(message);
    }
    onDisabled: {
        console.log("D-Bus signal monitor stopped");
    }
}
// Cleanup is automatic on Component.onDestruction and Qt.application.aboutToQuit
```

--------------------------------

### Set Panel Background Alpha on All Panels via D-Bus

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Adjust the background alpha transparency for all panel instances simultaneously using a D-Bus signal. This command sets the `panel.normal.backgroundColor.alpha` property.

```sh
# Set panel background alpha to 50% on ALL panels
dbus-send --session --type=signal /preset \
    luisbocanegra.panel.colorizer.all.property \
    string:'panel.normal.backgroundColor.alpha 0.5'
```

--------------------------------

### Set Panel Visibility via D-Bus

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Control the visibility of a specific panel instance using D-Bus. This command allows toggling the panel's visibility by setting the `stockPanelSettings.visible` property.

```sh
# Hide the panel (stockPanelSettings.visible)
qdbus luisbocanegra.panel.colorizer.c337.w2346 /preset \
    luisbocanegra.panel.colorizer.c337.w2346.property \
    'stockPanelSettings.visible {"enabled": true, "value": false}'
```

```sh
# Restore panel visibility
qdbus luisbocanegra.panel.colorizer.c337.w2346 /preset \
    luisbocanegra.panel.colorizer.c337.w2346.property \
    'stockPanelSettings.visible {"enabled": false, "value": true}'
```

--------------------------------

### Theme Scopes Enumeration

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Lists the available scopes for Kirigami color sets, used when referencing system colors. These cover various UI elements like windows, buttons, and tooltips.

```QML
// Enums.qml — ThemeScopes (Kirigami color set for system colors)
// View | Window | Button | Selection | Tooltip | Complementary | Header
```

--------------------------------

### Utils.getItemCfg

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Computes the final appearance settings for a panel element by layering global settings, preset overrides, user overrides, and the element's current state (busy/hovered/needsAttention/expanded).

```APIDOC
## `Utils.getItemCfg(...)` — Resolve effective settings for a widget

Computes the final appearance settings for a panel element by layering global settings, preset overrides, user overrides, and the element's current state (busy/hovered/needsAttention/expanded).

```js
// itemType: Enums.ItemType (WidgetItem | TrayItem | TrayArrow | PanelBgItem)
// widgetName: plasmoid pluginName, e.g. "org.kde.plasma.digitalclock"
// widgetId: plasmoid id (integer), -1 for tray StatusNotifier items
// config: current globalSettings JSON object
// globalOverrides: user's persistent overrides JSON object
const result = Utils.getItemCfg(
    Enums.ItemType.WidgetItem,
    "org.kde.plasma.digitalclock",
    42,
    config,
    globalOverrides,
    /*busy*/    false,
    /*needsAttention*/ false,
    /*hovered*/ true,
    /*expanded*/ false
);
// result.settings — effective appearance config to apply
// result.override — true if an override was applied

// Example: read the effective background color source type
console.log(result.settings.backgroundColor.sourceType); // e.g. 1 (System color)
```
```

--------------------------------

### Resolve Color with Utils.getColor

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Resolves the final QML color value for a background or foreground configuration object, supporting custom hex, system theme, custom list, random, and parent follow modes. Optional saturation and lightness scaling are available.

```javascript
// ColorSourceType enum values (Enums.ColorSourceType):
// 0 = Custom hex  1 = System theme  2 = Custom list  3 = Random  4 = Follow parent

// Example: system theme color
const colorCfgSystem = {
    sourceType:       1,
    systemColor:      "highlightColor",
    systemColorSet:   "View",
    alpha:            0.9,
    saturationEnabled: true,
    saturationValue:  0.7,
    lightnessEnabled: false,
    lightnessValue:   0.5,
};
const color = Utils.getColor(colorCfgSystem, 0, parent.color,
                             Enums.ItemType.WidgetItem, kirigamiItem);
// Returns a Qt color derived from Kirigami.Theme.highlightColor with alpha=0.9,
// saturation scaled to 0.7.

// Example: cycling through a custom list per widget index
const colorCfgList = {
    sourceType: 2,
    list: ["#ED8796", "#A6DA95", "#EED49F", "#8AADF4"],
    alpha: 1.0,
    saturationEnabled: false,
    lightnessEnabled:  false,
};
const widgetIndex = 2; // third widget
const listColor = Utils.getColor(colorCfgList, widgetIndex, null, Enums.ItemType.WidgetItem, null);
// Returns Qt color from "#EED49F" (index 2 % 4)
```

--------------------------------

### Theme Form Colors Enumeration

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Details the available named colors within Kirigami's theme system. This includes text, background, highlight, and negative text colors, among others.

```QML
// Enums.qml — ThemeFormColors (available Kirigami.Theme color names)
// TextColor | BackgroundColor | HighlightColor | NegativeTextColor | ... (20 total)
```

--------------------------------

### Panel Item Types Enumeration

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Defines the different types of panel elements that can be styled by the colorizer. Use these to specify which part of the panel you are targeting.

```QML
// Enums.qml — ItemType (which panel element is being styled)
Enums.ItemType.WidgetItem   // 0 — regular panel widget
Enums.ItemType.TrayItem     // 1 — item inside system tray grid
Enums.ItemType.TrayArrow    // 2 — system tray expand/collapse arrow
Enums.ItemType.PanelBgItem  // 3 — the panel background rectangle
```

--------------------------------

### Utils.editProperty

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Navigates a nested configuration object using dot/bracket notation and sets the value at the resolved leaf key. This is the function invoked when the D-Bus `property` method is called.

```APIDOC
## `Utils.editProperty(object, path, value)` — D-Bus property editor

Navigates a nested configuration object using dot/bracket notation and sets the value at the resolved leaf key. This is the function invoked when the D-Bus `property` method is called.

```js
// Dot notation path, value is auto-parsed (JSON / bool / number / string)
const config = JSON.parse(cfg_globalSettings);

// Disable native panel background
Utils.editProperty(config, "nativePanel.background.enabled", "false");
// config.nativePanel.background.enabled === false

// Set panel opacity to 0.5
Utils.editProperty(config, "nativePanel.background.opacity", "0.5");

// Override a specific array element (gradient stop color)
Utils.editProperty(config, "panel.normal.backgroundColor.gradient.stops[0].color", '"#ff0000"');

// Object replacement
Utils.editProperty(config,
    "stockPanelSettings.visible",
    '{"enabled": true, "value": false}');
// Hides the panel

cfg_globalSettings = JSON.stringify(config);
```
```

--------------------------------

### Remove Panel Colorizer Plugin (Shell)

Source: https://github.com/luisbocanegra/plasma-panel-colorizer/blob/main/README.md

Use this command to manually remove the C++ plugin if it causes Plasma to crash after a system update. This can temporarily recover from crashes.

```sh
sudo rm -rf /usr/lib/qt6/qml/org/kde/plasma/panelcolorizer/ /usr/lib64/qt6/qml/org/kde/plasma/panelcolorizer/ $HOME/.local/lib/qml/org/kde/plasma/panelcolorizer/ $HOME/.local/lib64/qml/org/kde/plasma/panelcolorizer/
```

--------------------------------

### Widget Click Modes Enumeration

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Defines the possible actions that can be triggered by clicking on a widget. Options include toggling the colorizer, switching presets, or showing a popup.

```JavaScript
// enum.js — WidgetClickModes
Enum.WidgetClickModes.TogglePanelColorizer  // 0
Enum.WidgetClickModes.SwitchPresets         // 1
Enum.WidgetClickModes.ShowPopup             // 2
```

--------------------------------

### Plasmoid Configuration Keys

Source: https://context7.com/luisbocanegra/plasma-panel-colorizer/llms.txt

Defines the configuration keys used in main.xml for the plasmoid. These keys control various aspects of the plasmoid's behavior and appearance, with specified types and default values.

```xml
<!-- Key reference with types and defaults -->

<!-- Master enable/disable toggle -->
<entry name="isEnabled"           type="Bool">   <default>true</default>  </entry>

<!-- Hide the widget itself (only visible in edit mode when true) -->
<entry name="hideWidget"          type="Bool">   <default>false</default> </entry>

<!-- Full appearance configuration (JSON, see defaultConfig shape above) -->
<entry name="globalSettings"      type="String"> <default>{}</default>    </entry>

<!-- Preset auto-loading rules (JSON) -->
<entry name="presetAutoloading"   type="String"> <default>{}</default>    </entry>

<!-- Per-widget appearance overrides (JSON) -->
<entry name="configurationOverrides" type="String">
    <default>{"overrides": {}, "associations":[]}</default>
</entry>

<!-- Force foreground color settings (JSON) -->
<entry name="forceForegroundColor" type="String">
    <default>{"widgets":[], "reloadInterval": 250}</default>
</entry>

<!-- Widget click behaviour: 0=TogglePanelColorizer, 1=SwitchPresets, 2=ShowPopup -->
<entry name="widgetClickMode"     type="Enum">   <default>0</default>     </entry>

<!-- Enable/disable the per-instance D-Bus service -->
<entry name="enableDBusService"   type="Bool">   <default>true</default>  </entry>

<!-- Widget Islands feature -->
<entry name="islandsEnabled"      type="Bool">   <default>false</default> </entry>
<entry name="islandSeparatorWidget" type="String">
    <default>org.kde.plasma.panelspacer</default>
</entry>
<entry name="islandSeparatorPairing" type="Bool"> <default>false</default></entry>
<entry name="blacklistIslandSeparator" type="Bool"><default>true</default></entry>

<!-- System tray icon replacement (requires C++ plugin) -->
<entry name="systemTrayIconsReplacementEnabled" type="Bool"><default>false</default></entry>
<entry name="systemTrayIconUserReplacements"    type="String"><default>[]</default></entry>
<entry name="systemTrayIconBuiltinReplacementsEnabled" type="Bool"><default>true</default></entry>

<!-- Hidden widgets list (JSON) -->
<entry name="hiddenWidgets"       type="String"> <default>{"widgets":[]}</default></entry>

<!-- Blacklisted widgets (excluded from colorization, JSON) -->
<entry name="blacklistedWidgets"  type="String"> <default>{"widgets":[]}</default></entry>
```