| AppMain, handle_event, handle_actions, ScriptVm, from_script_mod, makepad boilerplate, makepad new project, makepad cargo, Cargo.toml setup, hot reload, --hot, live reload, wasm deploy, cargo makepad, media plugin, audio_output, audio_input, AudioBuffer, cx.audio, makepad audio, 音频, 应用结构, 入门, 新项目, 脚手架, 启动, 热重载, 部署
npx skills add https://github.com/ZhangHanDong/makepad-skills --skill makepad-2.0-app-structure
> Version: makepad-widgets (dev branch) | Last Updated: 2026-03-03
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.
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 patternsBefore answering questions, Claude MUST:
[package]
name = "my-app"
version = "0.1.0"
edition = "2024"
[dependencies]
makepad-widgets = { path = "../path/to/makepad/widgets" }
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());
}
}
app_main!(App)Registers App as the application entry point. MUST be called at module level.
script_mod! { ... }Defines the Splash script that runs at startup. Contains:
use mod.prelude.widgets.* - Import widget definitionslet state = {...})startup() do #(App::script_component(vm)){...} - UI constructionApp::run(vm) - Initialization OrderCRITICAL: 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)
}
#[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 DSLMatchEvent for Action Handlingimpl 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);
}
}
}
AppMain for Event Dispatchimpl 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());
}
}
script_eval!(cx, {
mod.state.counter += 1
ui.main_view.render()
});
script_apply_eval!(cx, self.ui, {
title.text: "New Title"
subtitle.draw_text.color: #f00
});
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}
}
}
// 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))
# 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
| Flag | Description |
|------|-------------|
| --hot | Enable hot reload: watches script_mod! source files and auto-refreshes UI on save. Only affects Splash DSL; Rust code changes still need recompilation. |
| --stdin-loop | Studio mode: communicates with Makepad Studio via stdin/websocket. Used internally by Studio, not for manual use. |
| --linux-backend=<x11\|wayland> | (Linux only) Select windowing backend. |
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.
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);
Script failures show in Studio's Log View with file path and error details:
script failed while evaluating makepad.splash: <error details>
hub module)When running under Studio, Splash scripts get a hub module:
| API | Description |
|-----|-------------|
| hub.run(env, cmd, args) | Launch subprocess from Splash |
| hub.set_run_items(items) | Register runnable items in Studio's Run List |
| hub.studio_ip | Studio's WebSocket address |
script/)std.println() is the primary debugging toolMakepad 2.0 provides native audio I/O via the CxMediaApi trait. Audio callbacks run on a separate real-time thread.
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());
}
}
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);
}
});
platform/src/audio.rs)| Type | Description |
|------|-------------|
| AudioBuffer | Multichannel sample container (f32) |
| AudioInfo | Device ID, sample rate, timing |
| AudioDeviceDesc | Device metadata (name, type, channels) |
| AudioStreamSender/Receiver | Decoupled audio routing with adaptive buffering |
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 | Audio Output | Audio Input | Implementation |
|----------|-------------|-------------|----------------|
| macOS/iOS | AudioUnit | AVCapture | apple_media.rs |
| Windows | WASAPI | WASAPI | windows_media.rs |
| Linux | ALSA/PulseAudio | ALSA | linux_media.rs |
| Web/WASM | WebAudio | MediaDevices | web_media.rs |
| Android | AAudio | NDK Camera2 | android_media.rs |
examples/teamtalk/ demonstrates full P2P audio chat with cx.audio_input()/cx.audio_output(), resampling, and UDP streaming.
script_eval! to bridge Rust actions to Splash state updatesself.match_event(cx, event) in handle_event (required for MatchEvent)on_render for dynamic content, call .render() to trigger updatesmod.state for app-wide state accessible from both Rust and SplashMakepad 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:
objc2 crate — it creates a separate NSApplication instance that conflicts with Makepad'sshow_in_dock(false) hides NSStatusItem — use LSUIElement=true in Info.plist insteadsender.tag() for action dispatchCGEventTapEnable(tap, true) — CGEvent taps are enabled by default on creation; calling Enable actually disables themcx.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
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();
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);
}
Assess Kubernetes workloads and cluster configuration for AKS Automatic compatibility. Identifies incompatibilities, generates fixes, and guides migration from AKS Standard to AKS Automatic. WHEN: migrate to AKS Automatic, check AKS Automatic readiness, validate manifests for Automatic, assess cluster for Automatic compatibility, fix deployment for Automatic compatibility, identify AKS Automatic migration blockers, is my cluster ready for AKS Automatic.
Discovers available Azure OpenAI model capacity across regions and projects. Analyzes quota limits, compares availability, and recommends optimal deployment locations based on capacity requirements. USE FOR: find capacity, check quota, where can I deploy, capacity discovery, best region for capacity, multi-project capacity search, quota analysis, model availability, region comparison, check TPM availability. DO NOT USE FOR: actual deployment (hand off to preset or customize after discovery), quota increase requests (direct user to Azure Portal), listing existing deployments.
Interactive guided deployment flow for Azure OpenAI models with full customization control. Step-by-step selection of model version, SKU (GlobalStandard/Standard/ProvisionedManaged), capacity, RAI policy (content filter), and advanced options (dynamic quota, priority processing, spillover). USE FOR: custom deployment, customize model deployment, choose version, select SKU, set capacity, configure content filter, RAI policy, deployment options, detailed deployment, advanced deployment, PTU deployment, provisioned throughput. DO NOT USE FOR: quick deployment to optimal region (use preset).
Unified Azure OpenAI model deployment skill with intelligent intent-based routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI policy), and capacity discovery across regions and projects. USE FOR: deploy model, deploy gpt, create deployment, model deployment, deploy openai model, set up model, provision model, find capacity, check model availability, where can I deploy, best region for model, capacity analysis. DO NOT USE FOR: listing existing deployments (use foundry_models_deployments_list MCP tool), deleting deployments, agent creation (use agent/create), project creation (use project/create).
Intelligently deploys Azure OpenAI models to optimal regions by analyzing capacity across all available regions. Automatically checks current region first and shows alternatives if needed. USE FOR: quick deployment, optimal region, best region, automatic region selection, fast setup, multi-region capacity check, high availability deployment, deploy to best location. DO NOT USE FOR: custom SKU selection (use customize), specific version selection (use customize), custom capacity configuration (use customize), PTU deployments (use customize).
This skill should be used when working with LaminDB, an open-source data framework for biology that makes data queryable, traceable, reproducible, and FAIR. Use when managing biological datasets (scRNA-seq, spatial, flow cytometry, etc.), tracking computational workflows, curating and validating data with biological ontologies, building data lakehouses, or ensuring data lineage and reproducibility in biological research. Covers data management, annotation, ontologies (genes, cell types, diseases, tissues), schema validation, integrations with workflow managers (Nextflow, Snakemake) and MLOps platforms (W&B, MLflow), and deployment strategies.
Latch platform for bioinformatics workflows. Build pipelines with Latch SDK, @workflow/@task decorators, deploy serverless workflows, LatchFile/LatchDir, Nextflow/Snakemake integration.
Run Python code in the cloud with serverless containers, GPUs, and autoscaling. Use when deploying ML models, running batch processing jobs, scheduling compute-intensive tasks, or serving APIs that require GPU acceleration or dynamic scaling.
Take zhanghandong/makepad-2.0-app-structure from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.