QML UI Slots & HostContext

Map a slot name to a .qml file inside your package via ui_extensions in mod.json to replace the corresponding visual region without modifying the host application.

Slot list, mutual exclusion and cascade fallback, background-slot guidelines, window_backdrop and settings_view injection now each live in their own knowledge card — this page no longer repeats them:

Topic	Card
Slot list / exclusion / cascade fallback / resolution priority / background guidelines	UI slots
Window material window_backdrop	theme
settings_view injected properties and save example	Custom settings view
General QML authoring / config hot-reload / visual rules	UI extensions (QML)

This page covers only what the cards do not: hostContext subsystems, per-slot extra injections, and a hands-on example.

---

1. HostContext (overlay-class slots)

The host injects property var hostContext into the component root object:

import QtQuick 2.15

Item {
    id: root
    property var hostContext: null

    readonly property color textColor:
        hostContext ? hostContext.style.textColor : "#ffffff"
    readonly property string translation:
        hostContext ? hostContext.subtitle.currTranslation : ""
    readonly property bool hovered:
        hostContext ? hostContext.window.hovered : false

    function callPython() {
        if (!hostContext) return
        hostContext.invoke("my.plugin.id", "ping", { "n": 1 })
    }

    Rectangle {
        anchors.fill: parent
        color: hostContext ? hostContext.style.bgColor : "#00000000"
        opacity: hostContext ? hostContext.style.bgOpacity : 1.0

        Text {
            anchors.centerIn: parent
            text: translation
            color: textColor
            font.pixelSize: hostContext ? hostContext.style.fontSize : 24
            font.family: hostContext ? hostContext.style.fontFamily : "sans-serif"
        }
    }
}

Subsystems

style
textColor · bgColor · fontOpacity · bgOpacity · fontSize · fontFamily · themeId · primary · primaryHover · primaryGlow · radiusLarge

subtitle
currSource · currTranslation · hasRealSubtitle · prevSource · prevTranslation · hasPrev · isTyping · isSourceActive · isTranslationActive

audio
isMicMuted · audioDuckingEnabled · playbackDevice

window
hovered · dragging · width · height · setBackdrop(type) · setClickThrough(bool)

RPC
hostContext.invoke(pluginId, action, params) → Python handle_action → action_<action>(**params)

---

2. Extra Injected Properties (by slot)

Slot	Extra properties / signals
overlay_background, etc.	hovered, appState
caption_view	appState, bridge
alert_capsule	alertType, alertCategory, showCapsule; signals closeRequested, gotoSettingsRequested, switchLocalRequested
style_bar_actions	hostContext
Window backplates	window, appState; may use customRadius

Multi-window backplates may declare:

property bool enforceCustomRadius: true
property real customRadius: 16
property real customOpacity: 0.85

3. Hands-on: Replace the Volume Bar

mod.json fragment:

{
  "type": "theme",
  "ui_extensions": { "audio_level": "CustomWaveform.qml" }
}

import QtQuick 2.15

Item {
    id: root
    anchors.fill: parent
    property real level: 0.0
    property var hostContext: null

    // If the host does not provide a level signal, you can wire Connections to bridge yourself (version-dependent)
    Row {
        anchors.bottom: parent.bottom
        anchors.right: parent.right
        anchors.margins: 8
        spacing: 2
        opacity: root.level > 0.01 ? 0.95 : 0.0

        Repeater {
            model: 5
            Rectangle {
                width: 2
                height: Math.max(2, Math.min(10, root.level * 10))
                color: "#00f0ff"
            }
        }
    }
}

Complete runnable references: extensions/example_custom_waveform_ui/、example_theme_cyberpunk/.

---

4. QML authoring notes

1. Keep anchors.fill: parent on the component root so you do not break the host layout.
2. Null-check every hostContext access so the component previews safely.
3. Do not depend on global object names that do not appear in this document.

Theme auto-adaptation (ThemeTokens / PluggableWindowBackground) and the "vector SVG icons" red line are covered in UI extensions (QML) and Runtime environment & red lines.