Makepad 2.0 App Structure

Makepad 2.0 App Structure Skill

Version: makepad-widgets (dev branch) | Last Updated: 2026-03-03

Overview

A Makepad 2.0 app combines Rust code with Splash scripting. The Rust side handles app lifecycle, event routing, and business logic. The Splash side defines UI structure, templates, and inline interactions.

Documentation

Refer to the local files for detailed documentation:

• ./references/app-boilerplate.md - Complete working app template with Cargo.toml
• ./references/rust-splash-integration.md - Rust ↔ Splash communication patterns

IMPORTANT: Documentation Completeness Check

Before answering questions, Claude MUST: 1. Read the relevant reference file(s) listed above 2. If file read fails, answer based on SKILL.md patterns + built-in knowledge

---

Minimal App Template

Cargo.toml

[package]
name = "my-app"
version = "0.1.0"
edition = "2024"

[dependencies]
makepad-widgets = { path = "../path/to/makepad/widgets" }

src/app.rs (or src/main.rs)

use makepad_widgets::*;

app_main!(App);

script_mod! {
    use mod.prelude.widgets.*

    let state = {
        counter: 0
    }
    mod.state = state

    startup() do #(App::script_component(vm)){
        ui: Root{
            on_startup: ||{
                ui.main_view.render()
            }
            main_window := Window{
                window.inner_size: vec2(420, 300)
                body +: {
                    main_view := View{
                        width: Fill height: Fill
                        flow: Down spacing: 12
                        align: Center
                        on_render: ||{
                            Label{
                                text: "Count: " + state.counter
                                draw_text.text_style.font_size: 24
                            }
                        }
                    }
                    increment_button := Button{
                        text: "Increment"
                    }
                }
            }
        }
    }
}

impl App {
    fn run(vm: &mut ScriptVm) -> Self {
        crate::makepad_widgets::script_mod(vm);
        App::from_script_mod(vm, self::script_mod)
    }
}

#[derive(Script, ScriptHook)]
pub struct App {
    #[live]
    ui: WidgetRef,
}

impl MatchEvent for App {
    fn handle_actions(&mut self, cx: &mut Cx, actions: &Actions) {
        if self.ui.button(cx, ids!(increment_button)).clicked(actions) {
            script_eval!(cx, {
                mod.state.counter += 1
                ui.main_view.render()
            });
        }
    }
}

impl AppMain for App {
    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
        self.match_event(cx, event);
        self.ui.handle_event(cx, event, &mut Scope::empty());
    }
}

---

Key Components Explained

1. app_main!(App)

Registers App as the application entry point. MUST be called at module level.

2. script_mod! { ... }

Defines the Splash script that runs at startup. Contains:

• use mod.prelude.widgets.* - Import widget definitions
• State definitions (let state = {...})
• Functions and templates
• startup() do #(App::script_component(vm)){...} - UI construction

3. App::run(vm) - Initialization Order

CRITICAL: Registration order matters!

fn run(vm: &mut ScriptVm) -> Self {
    // 1. Register theme (optional, for light/dark theme)
    crate::makepad_widgets::theme_mod(vm);
    script_eval!(vm, { mod.theme = mod.themes.light });

    // 2. Register base widgets
    crate::makepad_widgets::widgets_mod(vm);

    // 3. Register custom widget modules (if any)
    // crate::my_widgets::script_mod(vm);

    // 4. Build app from script module
    App::from_script_mod(vm, self::script_mod)
}

Simplified (without theme selection):

fn run(vm: &mut ScriptVm) -> Self {
    crate::makepad_widgets::script_mod(vm);   // Registers both theme + widgets
    App::from_script_mod(vm, self::script_mod)
}

4. #[derive(Script, ScriptHook)] on App struct

#[derive(Script, ScriptHook)]
pub struct App {
    #[live]
    ui: WidgetRef,    // The widget tree root
}

• Script - Enables Splash integration (replaces old Live)
• ScriptHook - Enables lifecycle hooks (replaces old LiveHook)
• #[live] - Field settable from DSL

5. MatchEvent for Action Handling

impl MatchEvent for App {
    fn handle_actions(&mut self, cx: &mut Cx, actions: &Actions) {
        // Check button clicks
        if self.ui.button(cx, ids!(my_button)).clicked(actions) {
            // Handle click
        }
        // Check text input changes
        if let Some(text) = self.ui.text_input(cx, ids!(my_input)).changed(actions) {
            log!("Input: {}", text);
        }
    }
}

6. AppMain for Event Dispatch

impl AppMain for App {
    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
        self.match_event(cx, event);  // MUST call for MatchEvent to work
        self.ui.handle_event(cx, event, &mut Scope::empty());
    }
}

---

Rust → Splash Communication

script_eval! - Update state and trigger renders

script_eval!(cx, {
    mod.state.counter += 1
    ui.main_view.render()
});

script_apply_eval! - Patch widget properties

script_apply_eval!(cx, self.ui, {
    title.text: "New Title"
    subtitle.draw_text.color: #f00
});

---

Splash → Rust Communication

Inline Event Handlers in script_mod!

Button{
    text: "Click"
    on_click: || {
        // Splash code runs here
        state.count += 1
        ui.display.render()
    }
}

TextInput{
    on_return: || {
        let text = ui.my_input.text()
        add_item(text)
        ui.my_input.set_text("")
    }
}

// Render callback
on_render: || {
    for i, item in items {
        ItemTemplate{label.text: item.name}
    }
}

---

Widget Access from Rust

// Buttons
self.ui.button(cx, ids!(button_name)).clicked(actions)

// Labels
self.ui.label(cx, ids!(label_name)).set_text(cx, "text")

// Text inputs
self.ui.text_input(cx, ids!(input_name)).text()

// Nested access
self.ui.label(cx, ids!(container.inner.title))

---

Running the App

# Development
cargo run -p my-app

# Development with hot reload (Splash changes apply without recompilation)
cargo run -p my-app -- --hot

# Release
cargo run -p my-app --release

# With cargo-makepad for mobile/web
cargo makepad run -p my-app

Command-Line Flags

---

Makepad Studio: Debugging Splash

Running Splash Scripts in Studio

Studio looks for a makepad.splash file in the project root. It can run Splash scripts directly via the Run List panel (uses start_script_run internally), without needing cargo run.

Debug Output

Use std.println() / std.print() inside Splash scripts — output appears in both Studio's Log View panel and terminal stdout:

// makepad.splash
std.println("debug: value = " + my_var);

Error Display

Script failures show in Studio's Log View with file path and error details:

script failed while evaluating makepad.splash: <error details>

Hub API (Studio-injected hub module)

When running under Studio, Splash scripts get a hub module:

Current Limitations

• No breakpoint debugging — Splash VM does not support breakpoints or stepping
• No AST dump flag — Inspecting parse results requires adding logs in Rust source (script/)
• Print-based debugging — std.println() is the primary debugging tool

---

Audio API (Rust-only, not exposed to Splash)

Makepad 2.0 provides native audio I/O via the CxMediaApi trait. Audio callbacks run on a separate real-time thread.

Audio Output

use makepad_widgets::*;

impl AppMain for App {
    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
        match event {
            Event::Startup => {
                cx.audio_output(0, move |_info, buffer: &mut AudioBuffer| {
                    for frame in 0..buffer.frame_count() {
                        let sample = /* generate sample */;
                        buffer.set(0, frame, sample);
                        buffer.set(1, frame, sample);
                    }
                });
            }
            _ => {}
        }
        self.match_event(cx, event);
        self.ui.handle_event(cx, event, &mut Scope::empty());
    }
}

Audio Input

cx.audio_input(0, move |info: AudioInfo, buffer: &AudioBuffer| {
    let sample_rate = info.sample_rate;
    for frame in 0..buffer.frame_count() {
        let sample = buffer.get(0, frame);
    }
});

Key Audio Types (platform/src/audio.rs)

Cross-Thread Data Flow Pattern (Audio → UI)

Audio callbacks run on a real-time thread. Use atomics to pass data to the UI thread:

use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;

let amplitude = Arc::new(AtomicU64::new(0));
let amp_clone = amplitude.clone();

cx.audio_output(0, move |_info, buffer: &mut AudioBuffer| {
    let mut sum = 0.0f32;
    for frame in 0..buffer.frame_count() {
        let s = buffer.get(0, frame);
        sum += s * s;
    }
    let rms = (sum / buffer.frame_count() as f32).sqrt();
    amp_clone.store(rms.to_bits() as u64, Ordering::Relaxed);
});

// UI thread: read on NextFrame
let rms = f32::from_bits(amplitude.load(Ordering::Relaxed) as u32);

IMPORTANT: Audio is NOT exposed to Splash scripting. All audio processing must happen in Rust.

Platform Support

Reference: TeamTalk Example

examples/teamtalk/ demonstrates full P2P audio chat with cx.audio_input()/cx.audio_output(), resampling, and UDP streaming.

---

Best Practices

1. Registration order - Theme → Base widgets → Custom widgets → App module 2. Use `script_eval!` to bridge Rust actions to Splash state updates 3. Call `self.match_event(cx, event)` in handle_event (required for MatchEvent) 4. Use `on_render` for dynamic content, call .render() to trigger updates 5. Keep business logic in Rust, keep UI declarations in Splash 6. Use `mod.state` for app-wide state accessible from both Rust and Splash 7. Audio processing in Rust only - Use atomics for audio→UI data flow

---

macOS System Integration Patterns (learned 2026-03-31)

NSStatusBar (Menu Bar Icon)

Makepad has no built-in NSStatusBar API. Use makepad_objc_sys (same ObjC runtime as Makepad) for system tray integration:

use makepad_objc_sys::{msg_send, class, sel, sel_impl};
use makepad_objc_sys::runtime::{Object, Sel, YES, NO};

// Create status bar item
let status_bar: ObjcId = msg_send![class!(NSStatusBar), systemStatusBar];
let item: ObjcId = msg_send![status_bar, statusItemWithLength: -1.0f64];
let button: ObjcId = msg_send![item, button];
let () = msg_send![button, setTitle: str_to_nsstring("MIC")];

Critical gotchas:

• Do NOT use `objc2` crate — it creates a separate NSApplication instance that conflicts with Makepad's
• `show_in_dock(false)` hides NSStatusItem — use LSUIElement=true in Info.plist instead
• Menu target objects get autoreleased — use a global singleton target + sender.tag() for action dispatch
• Do NOT call `CGEventTapEnable(tap, true)` — CGEvent taps are enabled by default on creation; calling Enable actually disables them

Audio Input — Device ID Required

cx.use_audio_inputs(&[]) means stop recording, not "use default device". Must get device ID from AudioDevicesEvent:

impl MatchEvent for App {
    fn handle_audio_devices(&mut self, _cx: &mut Cx, e: &AudioDevicesEvent) {
        // Save default device ID
        self.default_input = e.default_input().into_iter().next();
    }
}

// When starting recording:
if let Some(device_id) = self.default_input {
    cx.use_audio_inputs(&[device_id]);  // Start capture with specific device
}

// When stopping:
cx.use_audio_inputs(&[]);  // Empty = stop all audio input

CGEvent Tap — Global Hotkey

For global keyboard shortcuts (e.g., press-to-talk):

// CGEventGetFlags returns 0x80000 for Option key (not 0x20 as some docs suggest)
let key_mask: u64 = 0x080000; // kCGEventFlagMaskAlternate

// Use CFRunLoopCommonModes (not DefaultMode)
CFRunLoopAddSource(run_loop, source, kCFRunLoopCommonModes);

// Do NOT call CGEventTapEnable — it's already enabled
// CGEventTapEnable(tap, true);  // WRONG — this actually breaks it

// CFRunLoopRun blocks forever — put in dedicated thread
CFRunLoopRun();

Cross-Thread Communication Pattern

macos-sys (CFRunLoop thread) → crossbeam channel → Makepad timer poll (main thread)
Audio callback (RT thread)   → Arc<AtomicU64>    → NextFrame handler (main thread)
HTTP response               → MatchEvent handler → UI update via script_eval!

Timer poll pattern for receiving ObjC callbacks:

// In handle_timer (10ms interval):
let events: Vec<u64> = self.menu_rx.as_ref()
    .map(|rx| rx.try_iter().collect())
    .unwrap_or_default();
for action_id in events {
    self.handle_menu_action(cx, action_id);
}

Minimal App Template (Cargo.toml):

[package]
name = "makepad-example-myapp"
version = "0.1.0"
edition = "2021"

[dependencies]
makepad-widgets = { path = "../../widgets" }

Minimal App (app.rs) - Counter Pattern:

use makepad_widgets::*;

app_main!(App);

script_mod! {
    use mod.prelude.widgets.*

    let state = { counter: 0 }
    mod.state = state

    startup() do #(App::script_component(vm)){
        ui: Root{
            on_startup: ||{
                ui.main_view.render()
            }
            main_window := Window{
                window.inner_size: vec2(420, 220)
                body +: {
                    main_view := View{
                        width: Fill height: Fill
                        flow: Down spacing: 12
                        align: Center
                        on_render: ||{
                            counter_label := Label{
                                text: "Count: " + state.counter
                                draw_text.text_style.font_size: 24
                            }
                        }
                    }
                    increment_button := Button{
                        text: "Increment"
                    }
                }
            }
        }
    }
}

impl App {
    fn run(vm: &mut ScriptVm) -> Self {
        crate::makepad_widgets::script_mod(vm);
        App::from_script_mod(vm, self::script_mod)
    }
}

#[derive(Script, ScriptHook)]
pub struct App {
    #[live] ui: WidgetRef,
}

impl MatchEvent for App {
    fn handle_actions(&mut self, cx: &mut Cx, actions: &Actions) {
        if self.ui.button(cx, ids!(increment_button)).clicked(actions) {
            script_eval!(cx, {
                mod.state.counter += 1
                ui.main_view.render()
            });
        }
    }
}

impl AppMain for App {
    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
        self.match_event(cx, event);
        self.ui.handle_event(cx, event, &mut Scope::empty());
    }
}

Key Components:

1. app_main!(App) - Entry point macro 2. script_mod!{...} - UI definition in Splash 3. App::run(vm) - Script module registration 4. App::from_script_mod(vm, self::script_mod) - Create app from script 5. #[derive(Script, ScriptHook)] - App struct derives 6. #[live] ui: WidgetRef - UI reference field 7. MatchEvent - Action handling trait 8. AppMain - Event dispatch trait

Theme Selection (Light/Dark):

impl App {
    fn run(vm: &mut ScriptVm) -> Self {
        crate::makepad_widgets::theme_mod(vm);
        script_eval!(vm, {
            mod.theme = mod.themes.light  // or mod.themes.dark
        });
        crate::makepad_widgets::widgets_mod(vm);
        App::from_script_mod(vm, self::script_mod)
    }
}

Widget Reference Pattern:

// Named widget in Splash
my_button := Button{text: "Click"}
my_input := TextInput{empty_text: "Type here"}

// Access in Rust
self.ui.button(cx, ids!(my_button)).clicked(actions)
self.ui.text_input(ids!(my_input)).text()

Running the app:

RUST_BACKTRACE=1 cargo run -p makepad-example-myapp --release

Rust -> Splash Communication:

1. script_eval!(cx, {...}) - Execute Splash code from Rust:

script_eval!(cx, {
    mod.state.counter += 1
    ui.main_view.render()
});

2. script_apply_eval!(cx, item, {...}) - Apply properties to widget at runtime:

script_apply_eval!(cx, item, {
    height: #(height)
    draw_bg: {is_even: #(if is_even {1.0} else {0.0})}
});

Use #(expr) for Rust expression interpolation.

Splash -> Rust Communication:

Script callbacks drive widget behavior:

// In Splash
todo_input := TextInput{
    on_return: || ui.add_button.on_click()
}
add_button := Button{
    on_click: ||{
        let text = ui.todo_input.text()
        if text != "" {
            add_todo(text, "")
            ui.todo_input.set_text("")
        }
    }
}

Rust side reads actions:

impl MatchEvent for App {
    fn handle_actions(&mut self, cx: &mut Cx, actions: &Actions) {
        if self.ui.button(cx, ids!(my_button)).clicked(actions) {
            // Business logic
        }
    }
}

Multi-Module Pattern:

// lib.rs - aggregate all widget modules
pub fn script_mod(vm: &mut ScriptVm) {
    crate::module_a::script_mod(vm);
    crate::module_b::script_mod(vm);
}

// app.rs - register in correct order
impl App {
    fn run(vm: &mut ScriptVm) -> Self {
        crate::makepad_widgets::script_mod(vm);  // 1. Base
        crate::script_mod(vm);                    // 2. Custom widgets
        crate::app_ui::script_mod(vm);            // 3. UI
        App::from_script_mod(vm, self::script_mod)
    }
}

Custom Widget Registration:

#[derive(Script, ScriptHook, Widget)]
pub struct MyWidget {
    #[source] source: ScriptObjectRef,  // REQUIRED
    #[walk] walk: Walk,
    #[layout] layout: Layout,
    #[redraw] #[live] draw_bg: DrawQuad,
    #[live] draw_text: DrawText,
    #[rust] my_state: i32,  // Runtime-only field
}

// With animations:
#[derive(Script, ScriptHook, Widget, Animator)]
pub struct AnimatedWidget {
    #[source] source: ScriptObjectRef,
    #[apply_default] animator: Animator,
    // ...
}

State Management Pattern:

• Splash state: mod.state = {...} for UI state
• Rust state: #[rust] field: Type for business logic
• Update flow: Rust event -> script_eval! update mod.state -> ui.view.render()

GC Best Practices:

• Large static templates: mod.gc.set_static(template) then mod.gc.run()
• Reduces GC pressure for long-lived UI templates
• Manual GC: mod.gc.run() / mod.gc.run_status()

main.rs:

fn main() {
    makepad_widgets::app_main!(App);
}

Or typically combined with app.rs in single file.