slint_interpreter/

debug_hook.rs

// Copyright © SixtyFPS GmbH <info@slint.dev>
// SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0

//! Runtime side of the `debug_hooks` compiler feature: evaluating an
//! `Expression::DebugHook` calls the callback installed with
//! `ComponentInstance::set_debug_hook_callback`, which may override the value.

use crate::Value;
use crate::eval::EvalContext;

use smol_str::SmolStr;

pub type DebugHookCallback = Box<dyn Fn(&str) -> Option<Value>>;

#[cfg(feature = "internal")]
pub(crate) fn set_debug_hook_callback(
    instance: &vtable::VRc<i_slint_core::item_tree::ItemTreeVTable, crate::instance::Instance>,
    func: Option<DebugHookCallback>,
) {
    *instance.globals.debug_hook_callback.borrow_mut() = func;
}

/// `Some` when the installed callback overrides the value, `None` to evaluate the binding.
pub(crate) fn trigger_debug_hook(ctx: &EvalContext, id: &SmolStr) -> Option<Value> {
    let globals = ctx.globals.upgrade()?;
    let callback = globals.debug_hook_callback.borrow();
    callback.as_ref().and_then(|callback| callback(id))
}

#[cfg(all(test, feature = "internal", feature = "internal-highlight"))]
pub(crate) mod tests {
    use super::*;
    use crate::{Compiler, ComponentInstance};
    use i_slint_compiler::source_path::SourcePath;
    use i_slint_core::{Property, graphics::ApproxEq};
    use std::{cell::RefCell, collections::HashMap, pin::Pin, rc::Rc};

    pub fn compile_with_debug_hooks(code: &str) -> ComponentInstance {
        i_slint_backend_testing::init_no_event_loop();

        let mut compiler = Compiler::default();
        compiler.compiler_configuration(i_slint_core::InternalToken).debug_hooks =
            Some(std::hash::RandomState::new());
        let compile_result = spin_on::spin_on(compiler.build_from_source_path(
            code.to_string(),
            test_path(),
            i_slint_core::InternalToken,
        ));
        assert!(!compile_result.has_errors(), "{:?}", compile_result.diagnostics);
        compile_result.components().next().unwrap().create().unwrap()
    }

    fn install_debug_hook_store(instance: &ComponentInstance) -> Store {
        let store: Store = Default::default();
        {
            let store = Rc::clone(&store);
            instance.set_debug_hook_callback(Some(Box::new(move |id: &str| -> Option<Value> {
                let mut m = (*store).borrow_mut();
                let p = m.entry(SmolStr::from(id)).or_insert_with(|| Box::pin(Property::new(None)));
                p.as_ref().get()
            })));
        }
        store
    }

    fn set_override(store: &Store, element_hash: u64, name: &str, value: Option<Value>) {
        let id = i_slint_compiler::passes::property_id(element_hash, &SmolStr::from(name));
        let mut store = (*store).borrow_mut();
        let override_property = store.entry(id).or_insert_with(|| Box::pin(Property::new(None)));
        (&**override_property).set(value);
    }

    // Make sure to not actually write this file, it's just a synthetic path
    pub fn test_path() -> SourcePath {
        SourcePath::new("/tmp/test.slint")
    }

    fn find_element_hash(instance: &ComponentInstance, code: &str, search_term: &str) -> u64 {
        let offset = code.find(search_term).unwrap() as u32;
        let (element, debug_index) = instance
            .element_node_at_source_code_position(&test_path(), offset)
            .first()
            .cloned()
            .expect("element resolved");
        let element_hash = element.borrow().debug[debug_index].element_hash;
        assert_ne!(element_hash, 0, "debug_hooks should populate element_hash");
        element_hash
    }

    fn geometry_at(
        instance: &ComponentInstance,
        code: &str,
        search_term: &str,
    ) -> i_slint_core::lengths::LogicalRect {
        let offset = code.find(search_term).unwrap() as u32;
        instance.component_positions(&test_path(), offset).first().expect("geometry").rect
    }

    // Editor-style override store + callback (must be installed before the first evaluation so
    // the hooked bindings register a dependency on the override properties while still `None`).
    type Store = Rc<RefCell<HashMap<SmolStr, Pin<Box<Property<Option<Value>>>>>>>;

    // Validates the "live drag" mechanism the visual editor relies on: with `debug_hooks`
    // enabled, a `set_debug_hook_callback` that reads a per-id `Property<Option<Value>>` lets the
    // editor reactively override a property's value (and revert it) without touching the source.
    // Setting the override property re-evaluates the hooked binding via Slint's dependency tracker.
    #[test]
    fn debug_hook_live_override() {
        let code = r#"
export component Win inherits Window {
    width: 300px;
    height: 300px;
    rect := Rectangle {
        x: 10px;
        y: 20px;
        width: 30px;
        height: 40px;
    }
}"#;

        let instance = compile_with_debug_hooks(code);

        let element_hash = find_element_hash(&instance, code, "Rectangle");

        let store = install_debug_hook_store(&instance);

        let base = geometry_at(&instance, code, "Rectangle");

        set_override(&store, element_hash, "x", Some(Value::Number(100.0)));
        set_override(&store, element_hash, "width", Some(Value::Number(70.0)));
        let after = geometry_at(&instance, code, "Rectangle");
        assert!(
            after.origin.x.approx_eq(&(base.origin.x + 90.0)),
            "x override should shift the element by 90px (base {}, after {})",
            base.origin.x,
            after.origin.x
        );
        assert!(
            after.size.width.approx_eq(&(base.size.width + 40.0)),
            "width override should grow the element by 40px (base {}, after {})",
            base.size.width,
            after.size.width
        );

        set_override(&store, element_hash, "x", None);
        set_override(&store, element_hash, "width", None);
        let reverted = geometry_at(&instance, code, "Rectangle");
        assert!(reverted.origin.x.approx_eq(&base.origin.x), "x should revert");
        assert!(reverted.size.width.approx_eq(&base.size.width), "width should revert");
    }

    #[test]
    fn debug_hook_component_instance_override() {
        let code = r#"
component Sub inherits Rectangle {
    in property <color> tint: blue;
    background: tint;
}
export component Win inherits Window {
    width: 300px;
    height: 300px;
    sub := Sub { x: 10px; y: 20px; width: 50px; height: 50px; }
    for _idx in 2: Sub { width: 10px; height: 10px; }
    out property <brush> sub-background: sub.background;
}"#;
        let instance = compile_with_debug_hooks(code);

        let store = install_debug_hook_store(&instance);

        let blue = Value::Brush(i_slint_core::Brush::SolidColor(i_slint_core::Color::from_rgb_u8(
            0, 0, 255,
        )));
        assert_eq!(instance.get_property("sub-background").unwrap(), blue);

        let element_hash = find_element_hash(&instance, code, "Sub {");

        let red = Value::Brush(i_slint_core::Brush::SolidColor(i_slint_core::Color::from_rgb_u8(
            255, 0, 0,
        )));
        set_override(&store, element_hash, "background", Some(red.clone()));
        assert_eq!(instance.get_property("sub-background").unwrap(), red);
        set_override(&store, element_hash, "background", None);
        assert_eq!(instance.get_property("sub-background").unwrap(), blue);

        let base = geometry_at(&instance, code, "Sub {");
        set_override(&store, element_hash, "x", Some(Value::Number(110.0)));
        let after = geometry_at(&instance, code, "Sub {");
        assert!(
            (after.origin.x - base.origin.x - 100.0).abs() < 0.5,
            "x override should shift the instance by 100px (base {}, after {})",
            base.origin.x,
            after.origin.x
        );
        set_override(&store, element_hash, "x", None);

        // Overriding the injected transform-rotation hook must be possible (the Transform
        // wrapper element is reified around the instance) and must not affect the geometry.
        set_override(&store, element_hash, "transform-rotation", Some(Value::Number(45.0)));
        let rotated = geometry_at(&instance, code, "Sub {");
        assert!(
            (rotated.origin.x - base.origin.x).abs() < 0.5,
            "rotation must not move the origin"
        );
        set_override(&store, element_hash, "transform-rotation", None);
    }

    #[test]
    fn debug_hook_forwards_live_private_state_per_instance() {
        let code = r#"
component Sub inherits Rectangle {
    in property <length> seed;
    in property <bool> active;
    in-out property <length> inherited-value: private-child.x;
    private-child := Rectangle { x: root.seed; }
    states [
        active when root.active: {
            private-child.x: 50px;
        }
    ]
}
export component Win inherits Window {
    in-out property <length> first-seed: 10px;
    in-out property <bool> first-active;
    first := Sub { seed: root.first-seed; active: root.first-active; }
    second := Sub { seed: 20px; }
    out property <length> first-value: first.inherited-value;
    out property <length> second-value: second.inherited-value;
}"#;
        let instance = compile_with_debug_hooks(code);
        let store = install_debug_hook_store(&instance);
        let first_hash = find_element_hash(&instance, code, "Sub { seed: root.first-seed");

        assert_eq!(instance.get_property("first-value").unwrap(), Value::Number(10.0));
        assert_eq!(instance.get_property("second-value").unwrap(), Value::Number(20.0));

        instance.set_property("first-seed", Value::Number(15.0)).unwrap();
        assert_eq!(instance.get_property("first-value").unwrap(), Value::Number(15.0));
        assert_eq!(instance.get_property("second-value").unwrap(), Value::Number(20.0));

        instance.set_property("first-active", Value::Bool(true)).unwrap();
        assert_eq!(instance.get_property("first-value").unwrap(), Value::Number(50.0));

        set_override(&store, first_hash, "inherited-value", Some(Value::Number(90.0)));
        instance.set_property("first-active", Value::Bool(false)).unwrap();
        instance.set_property("first-seed", Value::Number(25.0)).unwrap();
        assert_eq!(instance.get_property("first-value").unwrap(), Value::Number(90.0));
        assert_eq!(instance.get_property("second-value").unwrap(), Value::Number(20.0));

        set_override(&store, first_hash, "inherited-value", None);
        assert_eq!(instance.get_property("first-value").unwrap(), Value::Number(25.0));
        assert_eq!(instance.get_property("second-value").unwrap(), Value::Number(20.0));
    }

    // Regression test: debug hooks inject bindings for properties the element may not have
    // natively (geometry, transform-rotation). Every injected binding must end up on a property
    // that actually exists at runtime, for every kind of element — otherwise instantiation
    // aborts with "unknown property ... in ...". Exercise the special cases: the root element,
    // plain items, elements that become component roots later (PopupWindow — plain or through
    // component inheritance), non-item types (Timer), repeated and conditional elements,
    // layouts, menus, style widgets, and tooltips with custom content.
    #[test]
    fn debug_hooks_instantiate_special_elements() {
        let code = r#"
import { Button } from "std-widgets.slint";

component MyPopup inherits PopupWindow {
    Rectangle { background: yellow; }
}

export component Win inherits Window {
    width: 300px;
    height: 300px;

    MenuBar {
        Menu {
            title: "File";
            MenuItem { title: "Quit"; }
        }
    }

    rect := Rectangle {
        rotated := Rectangle { transform-rotation: 45deg; }
        scaled := Rectangle { transform-scale: 150%; }
        plain := Rectangle { }
    }

    covered := Rectangle {
        Tooltip {
            Rectangle { background: #222; }
        }
    }

    Button { text: "a widget"; }

    popup := PopupWindow {
        Text { text: "popup content"; }
    }
    my-popup := MyPopup { }
    callback show-the-popups();
    show-the-popups() => { popup.show(); my-popup.show(); }

    Timer { interval: 1s; running: false; }

    for _ in 3: Rectangle { width: 10px; }
    if true: Rectangle { height: 5px; }

    VerticalLayout {
        Rectangle { }
    }
}"#;

        let instance = compile_with_debug_hooks(code);

        // Showing the popups instantiates the popup components (their bindings are only set up then).
        instance.invoke("show-the-popups", &[]).unwrap();
    }

    // Enabling debug_hooks now also materializes hooked default bindings for unbound properties.
    // This must NOT change the rendered result when no override is set: wrapping default-geometry
    // bindings must preserve fill/implicit sizing, and injecting the type-default for unbound props
    // must equal their unbound value (e.g. the font sentinel that drives Window inheritance).
    #[test]
    fn debug_hooks_preserve_geometry() {
        i_slint_backend_testing::init_no_event_loop();

        let code = r#"
export component Win inherits Window {
    width: 300px;
    height: 200px;
    rect := Rectangle { }            // no explicit geometry -> fills the parent
    txt := Text { text: "Hello"; }   // implicit (font-dependent) size, inherited font
}"#;
        let geometries = |debug_hooks: bool| -> Vec<(f32, f32, f32, f32)> {
            let mut compiler = Compiler::default();
            if debug_hooks {
                compiler.compiler_configuration(i_slint_core::InternalToken).debug_hooks =
                    Some(std::hash::RandomState::new());
            }
            let r = spin_on::spin_on(compiler.build_from_source_path(
                code.to_string(),
                test_path(),
                i_slint_core::InternalToken,
            ));
            assert!(!r.has_errors(), "{:?}", r.diagnostics);
            let instance = r.components().next().unwrap().create().unwrap();
            [code.find("Rectangle").unwrap(), code.find("Text").unwrap()]
                .into_iter()
                .map(|offset| {
                    let geometry = instance
                        .component_positions(&test_path(), offset as u32)
                        .first()
                        .expect("geometry")
                        .rect;
                    (
                        geometry.origin.x,
                        geometry.origin.y,
                        geometry.size.width,
                        geometry.size.height,
                    )
                })
                .collect()
        };

        let without = geometries(false);
        let with = geometries(true);
        for (a, b) in without.iter().zip(with.iter()) {
            assert!(
                (a.0 - b.0).abs() < 0.5
                    && (a.1 - b.1).abs() < 0.5
                    && (a.2 - b.2).abs() < 0.5
                    && (a.3 - b.3).abs() < 0.5,
                "geometry differs with vs without debug_hooks: {a:?} vs {b:?}"
            );
        }
        // Sanity: the Rectangle actually filled the 300x200 window (so we know we compared real sizes).
        assert!((with[0].2 - 300.0).abs() < 0.5);
        assert!((with[0].3 - 200.0).abs() < 0.5);
    }
}