pinkpixel-dev GPUI Fundamentals
This skill covers the core concepts of GPUI framework for building desktop UI applications in Rust.
Overview
GPUI is a UI framework that provides:
- Entities: Handles to state with lifecycle management
- Contexts: Access to global state, windows, and system services
- Elements: Composable UI building blocks
- Rendering:
Rendertrait for creating element trees - Concurrency: Async primitives for background work
Context Types
Context types allow interaction with global state, windows, entities, and system services. They are passed as the argument named cx.
App
App is the root context type, providing access to global state and read/update of entities.
fn do_something(cx: &mut App) {
// Access global state
// Read/update entities
}
Context
Provided when updating an Entity<T>. This context dereferences into App, so functions which take &App can also take &Context<T>.
struct MyView {
count: usize,
}
impl MyView {
fn increment(&mut self, cx: &mut Context<Self>) {
self.count += 1;
cx.notify(); // Tell GPUI to re-render
}
}
AsyncApp and AsyncWindowContext
Provided by cx.spawn() for async operations. These can be held across await points.
fn start_async_work(&mut self, cx: &mut Context<Self>) {
cx.spawn(async move |this, cx| {
// this: WeakEntity<Self>
// cx: &mut AsyncApp
// Do async work
Ok(())
}).detach();
}
Window
Window provides access to the state of an application window. It is passed as an argument named window and comes before cx when present.
impl Render for MyView {
fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
div().child("Hello")
}
}
Used for:
- Managing focus
- Dispatching actions
- Directly drawing
- Getting user input state
Entities
An Entity<T> is a handle to state of type T. Entities enable:
- Shared ownership of UI state
- Automatic lifecycle management
- Safe concurrent access
Creating Entities
app.run(move |cx| {
cx.spawn(async move |cx| {
cx.open_window(WindowOptions::default(), |window, cx| {
// Create an entity
cx.new(|_cx| MyView { count: 0 })
})?;
Ok::<_, anyhow::Error>(())
}).detach();
});
Entity Operations
// Given: thing: Entity<MyView>
// Get entity ID
let id = thing.entity_id();
// Downgrade to weak reference
let weak = thing.downgrade();
// Read (immutable access)
let value = thing.read(cx);
println!("Count: {}", value.count);
// Read with closure
let count = thing.read_with(cx, |view, cx| view.count);
// Update (mutable access)
thing.update(cx, |view, cx| {
view.count += 1;
cx.notify();
});
// Update with window access
thing.update_in(cx, |view, window, cx| {
view.count += 1;
window.dispatch_action(SomeAction.boxed_clone(), cx);
cx.notify();
});
Important Rules
- Use inner cx: Within closures, use the inner
cxprovided to the closure, not the outercx
// ❌ WRONG
entity.update(cx, |view, inner_cx| {
view.count += 1;
cx.notify(); // Using outer cx - WRONG!
});
// ✅ CORRECT
entity.update(cx, |view, inner_cx| {
view.count += 1;
inner_cx.notify(); // Using inner cx
});
- Avoid update-while-updating: Never update an entity while it's already being updated (causes panic)
// ❌ WRONG - will panic
entity.update(cx, |view, cx| {
entity.update(cx, |view2, cx2| { // Nested update - PANIC!
// ...
});
});
Elements
The Render trait is used to render state into an element tree with flexbox layout.
Render Trait
use gpui::*;
struct MyView {
text: SharedString,
}
impl Render for MyView {
fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
div()
.flex()
.flex_col()
.gap_2()
.child(self.text.clone())
.child("More text")
}
}
RenderOnce Trait
For components constructed just to be turned into elements:
use gpui::*;
#[derive(IntoElement)]
struct Card {
title: SharedString,
content: SharedString,
}
impl RenderOnce for Card {
fn render(self, _window: &mut Window, _cx: &mut App) -> impl IntoElement {
div()
.p_4()
.bg(rgb(0x1a1a1a))
.rounded(px(8.0))
.child(
div().font_bold().child(self.title)
)
.child(
div().text_sm().child(self.content)
)
}
}
// Usage
impl Render for MyView {
fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
div().child(Card {
title: "Hello".into(),
content: "World".into(),
})
}
}
SharedString
Use SharedString to avoid copying strings. It's either &'static str or Arc<str>.
use gpui::*;
struct MyView {
// Efficient string storage
title: SharedString,
}
impl MyView {
fn new() -> Self {
Self {
title: "Hello".into(), // From &str
}
}
fn set_title(&mut self, title: String) {
self.title = title.into(); // From String
}
}
// SharedString implements IntoElement
impl Render for MyView {
fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
div().child(self.title.clone())
}
}
Element Composition
Basic Composition
div()
.child("Text")
.child(div().child("Nested"))
.child(another_element())
Conditional Rendering
Use .when() for conditional attributes/children:
div()
.when(is_active, |this| {
this.bg(rgb(0x3b82f6))
})
.when_some(maybe_text, |this, text| {
this.child(text)
})
Multiple Children
div()
.children(vec![
div().child("Item 1"),
div().child("Item 2"),
div().child("Item 3"),
])
Application Lifecycle
Basic Application
use gpui::*;
struct AppView;
impl Render for AppView {
fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
div().size_full().child("My App")
}
}
fn main() {
let app = Application::new();
app.run(move |cx| {
cx.spawn(async move |cx| {
cx.open_window(WindowOptions::default(), |window, cx| {
cx.new(|_| AppView)
})?;
Ok::<_, anyhow::Error>(())
})
.detach();
});
}
Window Options
use gpui::*;
let options = WindowOptions {
window_bounds: Some(WindowBounds::Windowed(Bounds {
origin: Point { x: px(100.0), y: px(100.0) },
size: Size { width: px(1024.0), height: px(768.0) },
})),
titlebar: Some(TitlebarOptions {
title: Some("My Application".into()),
appears_transparent: false,
..Default::default()
}),
focus: true,
show: true,
..Default::default()
};
cx.open_window(options, |window, cx| {
cx.new(|_| MyView::new())
})?;
Common Patterns
State Update with Notify
When state changes in a way that affects rendering:
struct Counter {
count: usize,
}
impl Counter {
fn increment(&mut self, cx: &mut Context<Self>) {
self.count += 1;
cx.notify(); // Trigger re-render
}
}
Event Handlers
impl Render for Counter {
fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
div()
.child(format!("Count: {}", self.count))
.child(
div()
.child("Increment")
.on_click(cx.listener(|this, _event, _window, cx| {
this.increment(cx);
}))
)
}
}
Using cx.listener
The cx.listener() method creates event handlers that receive &mut Self:
.on_click(cx.listener(|this: &mut Self, event, window, cx| {
// this: mutable reference to the entity
// event: the click event
// window: window reference
### Todo List with Entity Management
```rust
use gpui::*;
#[derive(Clone)]
struct TodoItem {
id: usize,
text: String,
completed: bool,
}
struct TodoList {
items: Vec<TodoItem>,
next_id: usize,
input_text: SharedString,
}
impl TodoList {
fn new() -> Self {
Self {
items: Vec::new(),
next_id: 1,
input_text: "".into(),
}
}
fn add_item(&mut self, cx: &mut Context<Self>) {
if !self.input_text.is_empty() {
self.items.push(TodoItem {
id: self.next_id,
text: self.input_text.to_string(),
completed: false,
});
self.next_id += 1;
self.input_text = "".into();
cx.notify();
}
}
fn toggle_item(&mut self, id: usize, cx: &mut Context<Self>) {
if let Some(item) = self.items.iter_mut().find(|i| i.id == id) {
item.completed = !item.completed;
cx.notify();
}
}
fn remove_item(&mut self, id: usize, cx: &mut Context<Self>) {
self.items.retain(|item| item.id != id);
cx.notify();
}
}
impl Render for TodoList {
fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
div()
.size_full()
.p_6()
.bg(rgb(0x0f0f0f))
.flex()
.flex_col()
.gap_4()
.child(
div()
.text_2xl()
.font_bold()
.text_color(rgb(0xffffff))
.child("Todo List")
)
.child(
div()
.flex()
.gap_2()
.child(
div()
.flex_1()
.px_3()
.py_2()
.bg(rgb(0x1a1a1a))
.border_1()
.border_color(rgb(0x4a4a4a))
.rounded_md()
.child(self.input_text.clone())
)
.child(
div()
.px_4()
.py_2()
.bg(rgb(0x3b82f6))
.rounded_md()
.cursor_pointer()
.child("Add")
.on_click(cx.listener(|this, _event, _window, cx| {
this.add_item(cx);
}))
)
)
.child(
div()
.flex()
.flex_col()
.gap_2()
.children(
self.items.iter().map(|item| {
let id = item.id;
div()
.flex()
.items_center()
.gap_2()
.p_3()
.bg(rgb(0x1a1a1a))
.rounded_md()
.child(
div()
.w(px(20.0))
.h(px(20.0))
.border_2()
.border_color(rgb(0x3b82f6))
.rounded(px(4.0))
.cursor_pointer()
.when(item.completed, |this| {
this.bg(rgb(0x3b82f6))
})
.on_click(cx.listener(move |this, _event, _window, cx| {
this.toggle_item(id, cx);
}))
)
.child(
div()
.flex_1()
.text_color(if item.completed {
rgb(0x6b7280)
} else {
rgb(0xffffff)
})
.when(item.completed, |this| {
this.line_through()
})
.child(&item.text)
)
.child(
div()
.px_3()
.py_1()
.bg(rgb(0xef4444))
.rounded(px(4.0))
.cursor_pointer()
.child("×")
.on_click(cx.listener(move |this, _event, _window, cx| {
this.remove_item(id, cx);
}))
)
})
)
)
}
}
Performance Tips
1. Minimize Entity Updates
// ❌ BAD - Multiple updates
entity.update(cx, |view, cx| { view.x = 10; cx.notify(); });
entity.update(cx, |view, cx| { view.y = 20; cx.notify(); });
entity.update(cx, |view, cx| { view.z = 30; cx.notify(); });
// ✅ GOOD - Single update
entity.update(cx, |view, cx| {
view.x = 10;
view.y = 20;
view.z = 30;
cx.notify();
});
2. Use WeakEntity for Callbacks
// ❌ BAD - Strong reference can leak
struct Parent {
child: Entity<Child>,
}
// ✅ GOOD - Weak reference prevents leaks
struct Callback {
target: WeakEntity<Target>,
}
3. Batch Notifications
struct BatchUpdate {
needs_notify: bool,
}
impl BatchUpdate {
fn update_multiple(&mut self, cx: &mut Context<Self>) {
self.field1 = value1;
self.field2 = value2;
self.field3 = value3;
// Single notify at the end
cx.notify();
}
}
4. Avoid Unnecessary Clones
// ❌ BAD - Unnecessary clone
div().child(self.text.clone().to_string())
// ✅ GOOD - Use SharedString directly
div().child(self.text.clone())
Common Mistakes
| Mistake | Fix |
|---|---|
Using outer cx in update closure |
Use the inner cx provided to closure |
| Nested entity updates | Restructure to avoid updating entity while updating |
Forgetting cx.notify() |
Call after state changes that affect rendering |
Not using SharedString |
Use SharedString for text to avoid copies |
Update without window in Render |
Use Context methods that don't need Window |
Calling .unwrap() on entity operations |
Use ? or handle errors properly |
Not storing Subscription |
Store in struct field to keep subscription alive |
Using smol::Timer in tests |
Use cx.background_executor.timer() |
Summary
- Entities (
Entity<T>): Handles to shared state - Contexts (
App,Context<T>): Access to framework services - Window: Window-specific operations
- Elements: Built with
div()and styled with methods - Render: Trait for converting state to UI
- SharedString: Efficient string type for UI text
References