Makepad Event/Action Skill

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

Check for updates: https://crates.io/crates/makepad-widgets

You are an expert at Makepad event and action handling. Help users by:

• Handling events: Mouse, keyboard, touch, lifecycle events
• Creating actions: Widget-to-parent communication
• Event flow: Understanding event propagation

When to Use

• You need to handle input, lifecycle, or UI interaction events in Makepad.
• The task involves handle_event, Event variants, Hit processing, or widget action propagation.
• You need to design or debug Makepad event/action flow between widgets and parents.

Documentation

Refer to the local files for detailed documentation:

• ./references/event-system.md - Event enum and handling
• ./references/action-system.md - Action trait and patterns

IMPORTANT: Documentation Completeness Check

Before answering questions, Claude MUST:

1. Read the relevant reference file(s) listed above
2. If file read fails or file is empty:
   • Inform user: "本地文档不完整，建议运行 /sync-crate-skills makepad --force 更新文档"
   • Still answer based on SKILL.md patterns + built-in knowledge
3. If reference file exists, incorporate its content into the answer

Event Enum (Key Variants)

rust
1pub enum Event {
2    // Lifecycle
3    Startup,
4    Shutdown,
5    Foreground,
6    Background,
7    Resume,
8    Pause,
9
10    // Drawing
11    Draw(DrawEvent),
12    LiveEdit,
13
14    // Window
15    WindowGotFocus(WindowId),
16    WindowLostFocus(WindowId),
17    WindowGeomChange(WindowGeomChangeEvent),
18    WindowClosed(WindowClosedEvent),
19
20    // Mouse
21    MouseDown(MouseDownEvent),
22    MouseMove(MouseMoveEvent),
23    MouseUp(MouseUpEvent),
24    Scroll(ScrollEvent),
25
26    // Touch
27    TouchUpdate(TouchUpdateEvent),
28
29    // Keyboard
30    KeyDown(KeyEvent),
31    KeyUp(KeyEvent),
32    TextInput(TextInputEvent),
33    TextCopy(TextClipboardEvent),
34
35    // Timer
36    Timer(TimerEvent),
37    NextFrame(NextFrameEvent),
38
39    // Network
40    HttpResponse(HttpResponse),
41
42    // Widget Actions
43    Actions(ActionsBuf),
44}

Handling Events in Widgets

rust
1impl Widget for MyWidget {
2    fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
3        // Check if event hits this widget's area
4        match event.hits(cx, self.area()) {
5            Hit::FingerDown(fe) => {
6                // Mouse/touch down on this widget
7                cx.action(MyWidgetAction::Pressed);
8            }
9            Hit::FingerUp(fe) => {
10                if fe.is_over {
11                    // Released while still over widget = click
12                    cx.action(MyWidgetAction::Clicked);
13                }
14            }
15            Hit::FingerHoverIn(_) => {
16                self.animator_play(cx, id!(hover.on));
17            }
18            Hit::FingerHoverOut(_) => {
19                self.animator_play(cx, id!(hover.off));
20            }
21            Hit::KeyDown(ke) => {
22                if ke.key_code == KeyCode::Return {
23                    cx.action(MyWidgetAction::Submitted);
24                }
25            }
26            _ => {}
27        }
28    }
29}

Hit Enum

rust
1pub enum Hit {
2    // Finger/Mouse
3    FingerDown(FingerDownEvent),
4    FingerUp(FingerUpEvent),
5    FingerMove(FingerMoveEvent),
6    FingerHoverIn(FingerHoverEvent),
7    FingerHoverOver(FingerHoverEvent),
8    FingerHoverOut(FingerHoverEvent),
9    FingerLongPress(FingerLongPressEvent),
10
11    // Keyboard
12    KeyDown(KeyEvent),
13    KeyUp(KeyEvent),
14    KeyFocus,
15    KeyFocusLost,
16    TextInput(TextInputEvent),
17    TextCopy,
18
19    // Nothing
20    Nothing,
21}

Action System

Defining Actions

rust
1#[derive(Clone, Debug, DefaultNone)]
2pub enum ButtonAction {
3    None,
4    Clicked,
5    Pressed,
6    Released,
7}
8
9// DefaultNone derives Default returning None variant

Emitting Actions

rust
1// From main thread (in handle_event)
2cx.action(ButtonAction::Clicked);
3
4// From any thread (thread-safe)
5Cx::post_action(MyAction::DataLoaded(data));

Handling Actions

rust
1fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
2    // Handle child widget actions
3    let actions = cx.capture_actions(|cx| {
4        self.button.handle_event(cx, event, scope);
5    });
6
7    // Check for specific action
8    if self.button(id!(my_button)).clicked(&actions) {
9        // Button was clicked
10    }
11
12    // Or iterate actions
13    for action in actions.iter() {
14        if let Some(ButtonAction::Clicked) = action.downcast_ref() {
15            // Handle click
16        }
17    }
18}

Widget Action Helpers

rust
1// Common widget action checks
2impl ButtonRef {
3    fn clicked(&self, actions: &ActionsBuf) -> bool;
4    fn pressed(&self, actions: &ActionsBuf) -> bool;
5    fn released(&self, actions: &ActionsBuf) -> bool;
6}
7
8impl TextInputRef {
9    fn changed(&self, actions: &ActionsBuf) -> Option<String>;
10    fn returned(&self, actions: &ActionsBuf) -> Option<String>;
11}

Event Flow

1. Event arrives from platform layer
2. Root widget receives event first
3. Propagates down to children via handle_event
4. Widgets emit actions via cx.action()
5. Parent captures actions via cx.capture_actions()
6. App handles remaining actions

Timer and NextFrame

rust
1// Start a timer
2let timer = cx.start_timer(1.0); // 1 second
3
4// In handle_event
5if let Event::Timer(te) = event {
6    if te.timer_id == self.timer {
7        // Timer fired
8    }
9}
10
11// Request next frame callback
12let next_frame = cx.new_next_frame();
13
14// In handle_event
15if let Event::NextFrame(ne) = event {
16    if ne.frame_id == self.next_frame {
17        // Next frame arrived
18    }
19}

When Answering Questions

1. Use event.hits(cx, area) to check if event targets a widget
2. Actions flow UP from child to parent (unlike events which flow DOWN)
3. Use cx.capture_actions() to intercept child actions
4. Cx::post_action() is thread-safe for async operations
5. DefaultNone derive macro auto-implements Default for enums