gpui-action
🎯Skillfrom longbridge/gpui-component
|Defines and manages keyboard-driven actions and key bindings for declarative UI interactions in GPUI applications.
Installation
npx skills add https://github.com/longbridge/gpui-component --skill gpui-actionSkill Details
Action definitions and keyboard shortcuts in GPUI. Use when implementing actions, keyboard shortcuts, or key bindings.
Overview
Actions provide declarative keyboard-driven UI interactions in GPUI.
Key Concepts:
- Define actions with
actions!macro or#[derive(Action)] - Bind keys with
cx.bind_keys() - Handle with
.on_action()on elements - Context-aware via
key_context()
Quick Start
Simple Actions
```rust
use gpui::actions;
actions!(editor, [MoveUp, MoveDown, Save, Quit]);
const CONTEXT: &str = "Editor";
pub fn init(cx: &mut App) {
cx.bind_keys([
KeyBinding::new("up", MoveUp, Some(CONTEXT)),
KeyBinding::new("down", MoveDown, Some(CONTEXT)),
KeyBinding::new("cmd-s", Save, Some(CONTEXT)),
KeyBinding::new("cmd-q", Quit, Some(CONTEXT)),
]);
}
impl Render for Editor {
fn render(&mut self, _: &mut Window, cx: &mut Context
div()
.key_context(CONTEXT)
.on_action(cx.listener(Self::move_up))
.on_action(cx.listener(Self::move_down))
.on_action(cx.listener(Self::save))
}
}
impl Editor {
fn move_up(&mut self, _: &MoveUp, cx: &mut Context
// Handle move up
cx.notify();
}
fn move_down(&mut self, _: &MoveDown, cx: &mut Context
cx.notify();
}
fn save(&mut self, _: &Save, cx: &mut Context
// Save logic
cx.notify();
}
}
```
Actions with Parameters
```rust
#[derive(Clone, PartialEq, Action, Deserialize)]
#[action(namespace = editor)]
pub struct InsertText {
pub text: String,
}
#[derive(Action, Clone, PartialEq, Eq, Deserialize)]
#[action(namespace = editor, no_json)]
pub struct Digit(pub u8);
cx.bind_keys([
KeyBinding::new("0", Digit(0), Some(CONTEXT)),
KeyBinding::new("1", Digit(1), Some(CONTEXT)),
// ...
]);
impl Editor {
fn on_digit(&mut self, action: &Digit, cx: &mut Context
self.insert_digit(action.0, cx);
}
}
```
Key Formats
```rust
// Modifiers
"cmd-s" // Command (macOS) / Ctrl (Windows/Linux)
"ctrl-c" // Control
"alt-f" // Alt
"shift-tab" // Shift
"cmd-ctrl-f" // Multiple modifiers
// Keys
"a-z", "0-9" // Letters and numbers
"f1-f12" // Function keys
"up", "down", "left", "right"
"enter", "escape", "space", "tab"
"backspace", "delete"
"-", "=", "[", "]", etc. // Special characters
```
Action Naming
Prefer verb-noun pattern:
```rust
actions!([
OpenFile, // ✅ Good
CloseWindow, // ✅ Good
ToggleSidebar, // ✅ Good
Save, // ✅ Good (common exception)
]);
```
Context-Aware Bindings
```rust
const EDITOR_CONTEXT: &str = "Editor";
const MODAL_CONTEXT: &str = "Modal";
// Same key, different contexts
cx.bind_keys([
KeyBinding::new("escape", CloseModal, Some(MODAL_CONTEXT)),
KeyBinding::new("escape", ClearSelection, Some(EDITOR_CONTEXT)),
]);
// Set context on element
div()
.key_context(EDITOR_CONTEXT)
.child(editor_content)
```
Best Practices
✅ Use Contexts
```rust
// ✅ Good: Context-aware
div()
.key_context("MyComponent")
.on_action(cx.listener(Self::handle))
```
✅ Name Actions Clearly
```rust
// ✅ Good: Clear intent
actions!([
SaveDocument,
CloseTab,
TogglePreview,
]);
```
✅ Handle with Listeners
```rust
// ✅ Good: Proper handler naming
impl MyComponent {
fn on_action_save(&mut self, _: &Save, cx: &mut Context
// Handle save
cx.notify();
}
}
div().on_action(cx.listener(Self::on_action_save))
```
Reference Documentation
- Complete Guide: See [reference.md](references/reference.md)
- Action definition, keybinding, dispatch
- Focus-based routing, best practices
- Performance, accessibility
More from this repository10
Enforces consistent GPUI component design patterns by providing a comprehensive style guide for creating and reviewing Rust UI components.
Enables asynchronous operations and background tasks in GPUI, allowing seamless coordination between UI updates and concurrent computations.
Provides CSS-like layout and styling for Rust GPUI components using type-safe, chainable methods for flexbox, sizing, colors, and spacing.
Manages application state through safe, concurrent entities with read, update, and weak reference capabilities for reactive and async-friendly state handling in GPUI.
Enables keyboard-driven focus management and navigation between focusable elements in GPUI user interfaces.
Enables type-safe event handling, subscriptions, and observations for coordinating component interactions in GPUI applications.
gpui-context skill from longbridge/gpui-component
Enables comprehensive testing of GPUI applications with deterministic, single-threaded test execution for UI components and async operations.
Enables low-level, performance-critical custom UI element creation with precise control over layout, painting, and interaction phases in GPUI.
Manages global application state and configuration in GPUI, enabling centralized data access and sharing across components.