Agent skill

gpui-event

Event handling and subscriptions in GPUI. Use when implementing events, observers, or event-driven patterns. Supports custom events, entity observations, and event subscriptions for coordinating between components.

View SKILL.md on GitHub Repository
Stars 10,844
Forks 537

Install this agent skill to your Project

npx add-skill https://github.com/longbridge/gpui-component/tree/main/.claude/skills/gpui-event

SKILL.md

Overview

GPUI provides event system for component coordination:

Event Mechanisms:

  • Custom Events: Define and emit type-safe events
  • Observations: React to entity state changes
  • Subscriptions: Listen to events from other entities
  • Global Events: App-wide event handling

Quick Start

Define and Emit Events

rust
#[derive(Clone)]
enum MyEvent {
    DataUpdated(String),
    ActionTriggered,
}

impl MyComponent {
    fn update_data(&mut self, data: String, cx: &mut Context<Self>) {
        self.data = data.clone();

        // Emit event
        cx.emit(MyEvent::DataUpdated(data));
        cx.notify();
    }
}

Subscribe to Events

rust
impl Listener {
    fn new(source: Entity<MyComponent>, cx: &mut App) -> Entity<Self> {
        cx.new(|cx| {
            // Subscribe to events
            cx.subscribe(&source, |this, emitter, event: &MyEvent, cx| {
                match event {
                    MyEvent::DataUpdated(data) => {
                        this.handle_update(data.clone(), cx);
                    }
                    MyEvent::ActionTriggered => {
                        this.handle_action(cx);
                    }
                }
            }).detach();

            Self { source }
        })
    }
}

Observe Entity Changes

rust
impl Observer {
    fn new(target: Entity<Target>, cx: &mut App) -> Entity<Self> {
        cx.new(|cx| {
            // Observe entity for any changes
            cx.observe(&target, |this, observed, cx| {
                // Called when observed.update() calls cx.notify()
                println!("Target changed");
                cx.notify();
            }).detach();

            Self { target }
        })
    }
}

Common Patterns

1. Parent-Child Communication

rust
// Parent emits events
impl Parent {
    fn notify_children(&mut self, cx: &mut Context<Self>) {
        cx.emit(ParentEvent::Updated);
        cx.notify();
    }
}

// Children subscribe
impl Child {
    fn new(parent: Entity<Parent>, cx: &mut App) -> Entity<Self> {
        cx.new(|cx| {
            cx.subscribe(&parent, |this, parent, event, cx| {
                this.handle_parent_event(event, cx);
            }).detach();

            Self { parent }
        })
    }
}

2. Global Event Broadcasting

rust
struct EventBus {
    listeners: Vec<WeakEntity<dyn Listener>>,
}

impl EventBus {
    fn broadcast(&mut self, event: GlobalEvent, cx: &mut Context<Self>) {
        self.listeners.retain(|weak| {
            weak.update(cx, |listener, cx| {
                listener.on_event(&event, cx);
            }).is_ok()
        });
    }
}

3. Observer Pattern

rust
cx.observe(&entity, |this, observed, cx| {
    // React to any state change
    let state = observed.read(cx);
    this.sync_with_state(state, cx);
}).detach();

Best Practices

✅ Detach Subscriptions

rust
// ✅ Detach to keep alive
cx.subscribe(&entity, |this, source, event, cx| {
    // Handle event
}).detach();

✅ Clean Event Types

rust
#[derive(Clone)]
enum AppEvent {
    DataChanged { id: usize, value: String },
    ActionPerformed(ActionType),
    Error(String),
}

❌ Avoid Event Loops

rust
// ❌ Don't create mutual subscriptions
entity1.subscribe(entity2) → emits event
entity2.subscribe(entity1) → emits event → infinite loop!

Reference Documentation

  • API Reference: See api-reference.md

    • Event definition, emission, subscriptions
    • Observations, global events
    • Subscription lifecycle

  • Patterns: See patterns.md

    • Event-driven architectures
    • Communication patterns
    • Best practices and pitfalls

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

longbridge/gpui-component

gpui-test

Writing tests for GPUI applications. Use when testing components, async operations, or UI behavior.

10,844 537
Explore
longbridge/gpui-component

gpui-async

Async operations and background tasks in GPUI. Use when working with async, spawn, background tasks, or concurrent operations. Essential for handling async I/O, long-running computations, and coordinating between foreground UI updates and background work.

10,844 537
Explore
longbridge/gpui-component

gpui-action

Action definitions and keyboard shortcuts in GPUI. Use when implementing actions, keyboard shortcuts, or key bindings.

10,844 537
Explore
longbridge/gpui-component

github-pull-request-description

Write a description to description GitHub Pull Request.

10,844 537
Explore
longbridge/gpui-component

gpui-layout-and-style

Layout and styling in GPUI. Use when styling components, layout systems, or CSS-like properties.

10,844 537
Explore
longbridge/gpui-component

gpui-context

Context management in GPUI including App, Window, and AsyncApp. Use when working with contexts, entity updates, or window operations. Different context types provide different capabilities for UI rendering, entity management, and async operations.

10,844 537
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results