GPUI

https://matinaniss.github.io/gpui-book
Admin
GPUI is a fast, productive, and versatile GPU-accelerated UI framework for Rust, featuring a hybrid...
Tokens:15,118
Snippets:210
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install create-gpui-app CLI

Source: https://matinaniss.github.io/gpui-book/getting-started/create-gpui-app.html

Installs the official CLI tool for scaffolding GPUI applications via Cargo.

```bash
cargo install create-gpui-app
```

--------------------------------

### Basic Div Implementation

Source: https://matinaniss.github.io/gpui-book/elements/div.html

A minimal example showing how to render a single empty div element within a GPUI view.

```rust
use gpui::{AppContext, Application, Context, IntoElement, Render, Window, WindowOptions, div};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Implement a stateful counter in GPUI

Source: https://matinaniss.github.io/gpui-book/examples/counter.html

This example defines a RootView struct to track count state and implements the Render trait to build the UI with interactive buttons.

```rust
use gpui::{
    AppContext, Application, ClickEvent, Context, InteractiveElement, IntoElement, ParentElement,
    Render, StatefulInteractiveElement, Styled, Window, WindowOptions, black, div, green, red,
    white,
};

struct RootView {
    count: isize,
}

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .flex()
            .items_center()
            .justify_center()
            .gap_5()
            .bg(white())
            .child(
                div()
                    .id("decrement_button")
                    .cursor_pointer()
                    .flex()
                    .items_center()
                    .justify_center()
                    .size_8()
                    .rounded_md()
                    .border_1()
                    .border_color(black())
                    .child("-")
                    .hover(|style| style.bg(red()))
                    .on_click(cx.listener(Self::decrement)),
            )
            .child(
                div()
                    .min_w_16()
                    .text_3xl()
                    .text_center()
                    .child(self.count.to_string()),
            )
            .child(
                div()
                    .id("increment_button")
                    .cursor_pointer()
                    .flex()
                    .items_center()
                    .justify_center()
                    .size_8()
                    .rounded_md()
                    .border_1()
                    .border_color(black())
                    .child("+")
                    .hover(|style| style.bg(green()))
                    .on_click(cx.listener(Self::increment)),
            )
    }
}

impl RootView {
    fn increment(&mut self, _event: &ClickEvent, _window: &mut Window, cx: &mut Context<Self>) {
        self.count += 1;
        cx.notify();
    }

    fn decrement(&mut self, _event: &ClickEvent, _window: &mut Window, cx: &mut Context<Self>) {
        self.count -= 1;
        cx.notify();
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView { count: 0 })
        })
        .unwrap();
    });
}
```

--------------------------------

### Implement Hello World in main.rs

Source: https://matinaniss.github.io/gpui-book/getting-started/manual-project.html

Define a basic GPUI component and initialize the application window.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, SharedString, Styled,
    Window, WindowOptions, div, white,
};

struct HelloWorld {
    text: SharedString,
}

impl Render for HelloWorld {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .bg(white())
            .flex()
            .justify_center()
            .items_center()
            .text_3xl()
            .child(format!("Hello, {}!", &self.text))
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| HelloWorld {
                text: SharedString::new_static("World"),
            })
        })
        .unwrap();
    });
}
```

--------------------------------

### Create a standard GPUI application

Source: https://matinaniss.github.io/gpui-book/getting-started/create-gpui-app.html

Scaffolds a new GPUI project and navigates into the directory.

```bash
create-gpui-app --name my-app
cd my-app
```

--------------------------------

### Create a Hello World application in GPUI

Source: https://matinaniss.github.io/gpui-book/examples/hello-world.html

Defines a RootView struct that renders centered text and initializes the application window.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, Styled, Window,
    WindowOptions, div, white,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .flex()
            .items_center()
            .justify_center()
            .bg(white())
            .child("Hello World!")
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Initialize a Manual GPUI Project

Source: https://matinaniss.github.io/gpui-book/print.html

Create a new Rust project and add GPUI dependencies manually.

```bash
cargo new my-app
cd my-app
```

```bash
cargo add gpui
```

```bash
cargo add gpui --git https://github.com/zed-industries/zed
```

--------------------------------

### Initialize a new Rust project

Source: https://matinaniss.github.io/gpui-book/getting-started/manual-project.html

Create a new directory and initialize a standard Rust project structure.

```bash
cargo new my-app
cd my-app
```

--------------------------------

### Open a new window with App

Source: https://matinaniss.github.io/gpui-book/architecture/app.html

Initializes a new GPUI application and opens a window using WindowOptions.

```rust
use gpui::{Application, WindowOptions};

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |window, app| {
            // Return root view
        })
        .unwrap();
    });
}
```

--------------------------------

### Initialize a GPUI Application

Source: https://matinaniss.github.io/gpui-book/architecture/application.html

Creates a new instance of the GPUI Application.

```rust
use gpui::Application;

fn main() {
    let application = Application::new();
}
```

--------------------------------

### Application::new

Source: https://matinaniss.github.io/gpui-book/architecture/application.html

Creates a new instance of the GPUI Application.

```APIDOC
## Application::new

### Description
Creates a new instance of the GPUI Application, serving as the entry point for the application.

### Signature
`Application::new()`

### Example
```rust
use gpui::Application;

fn main() {
    let application = Application::new();
}
```
```

--------------------------------

### Create a workspace-based GPUI application

Source: https://matinaniss.github.io/gpui-book/getting-started/create-gpui-app.html

Scaffolds a new GPUI project using a workspace structure.

```bash
create-gpui-app --workspace --name my-app
cd my-app
```

--------------------------------

### Implementing RenderOnce for a component

Source: https://matinaniss.github.io/gpui-book/rendering/render-once.html

Demonstrates defining a component using RenderOnce and integrating it into a RootView that implements the Render trait.

```rust
use gpui::{
    App, AppContext, Application, Context, IntoElement, ParentElement, Render, RenderOnce, Window,
    WindowOptions, div,
};

#[derive(IntoElement)]
struct SomeComponent;

impl RenderOnce for SomeComponent {
    fn render(self, _window: &mut Window, _cx: &mut App) -> impl IntoElement {
        div()
    }
}

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().child(SomeComponent)
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Application::run

Source: https://matinaniss.github.io/gpui-book/architecture/application.html

Consumes the Application and executes the provided callback once the application has finished loading.

```APIDOC
## Application::run

### Description
Consumes the Application instance and accepts a callback function. This callback is triggered once the application has finished loading and provides a mutable reference to the App, allowing for window management and other application control.

### Signature
`application.run(|app| { ... })`

### Example
```rust
use gpui::Application;

fn main() {
    let application = Application::new();

    application.run(|_app| {
        // Entry point
    });
}
```
```

--------------------------------

### Run a GPUI Application

Source: https://matinaniss.github.io/gpui-book/architecture/application.html

Consumes the application instance and executes a callback once the application has finished loading.

```rust
use gpui::Application;

fn main() {
    let application = Application::new();

    application.run(|_app| {
        // Entry point
    });
}
```

--------------------------------

### Initialize a basic GPUI Animation

Source: https://matinaniss.github.io/gpui-book/animations/animation.html

Creates a new animation instance with a specified duration.

```rust
use std::time::Duration;

use gpui::Animation;

fn main() {
    Animation::new(Duration::from_secs(1));
}
```

--------------------------------

### Standard project file structure

Source: https://matinaniss.github.io/gpui-book/getting-started/create-gpui-app.html

The directory layout generated for a standard GPUI application.

```text
my-app
├── src
│   └── main.rs
├── Cargo.toml
└── README.md
```

--------------------------------

### Create a basic Animation

Source: https://matinaniss.github.io/gpui-book/print.html

Initializes a new animation with a specified duration.

```rust

use std::time::Duration;

use gpui::Animation;

fn main() {
    Animation::new(Duration::from_secs(1));
}
```

--------------------------------

### Style elements using utility methods

Source: https://matinaniss.github.io/gpui-book/styling/index.html

Uses shorthand CSS-like utility functions to apply styles concisely.

```rust
impl Render for SomeView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().flex().flex_col().child("Hello").child("World")
    }
}
```

--------------------------------

### Add GPUI dependency

Source: https://matinaniss.github.io/gpui-book/getting-started/manual-project.html

Add the GPUI crate to your project using either the crates.io registry or the official Git repository.

```bash
cargo add gpui
```

```bash
cargo add gpui --git https://github.com/zed-industries/zed
```

--------------------------------

### Configure GPUI dependencies in Cargo.toml

Source: https://matinaniss.github.io/gpui-book/getting-started/index.html

Add the GPUI crate to your project using either a versioned release or the latest development version from the Zed repository.

```toml
gpui = { version = "*" } # Specify a specific version
# OR
gpui = { git = "https://github.com/zed-industries/zed" }
```

--------------------------------

### Bind global actions with App

Source: https://matinaniss.github.io/gpui-book/architecture/app.html

Registers a global action and binds a key shortcut to trigger it within the application context.

```rust
use gpui::{
    AppContext, Application, Context, Empty, IntoElement, Render, Window, WindowOptions, actions,
};

actions!(actions_namespace, [Enter]);

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        Empty
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.bind_keys([gpui::KeyBinding::new("enter", Enter, None)]);
            app.on_action(|&Enter, _app| println!("Enter key hit!"));

            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Bind Keys to Actions

Source: https://matinaniss.github.io/gpui-book/interactivity/keyboard.html

Create a KeyBinding struct and register it with the application using bind_keys.

```rust
use gpui::{Application, actions};

actions!(actions_namespace, [Enter]);

fn main() {
    Application::new().run(|app| {
        app.bind_keys([gpui::KeyBinding::new("enter", Enter, None)]);
    });
}
```

--------------------------------

### Render text with a string literal in GPUI

Source: https://matinaniss.github.io/gpui-book/elements/text.html

Demonstrates the basic implementation of a RootView that renders a static string literal.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, Styled, Window,
    WindowOptions, div, rgb,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .bg(rgb(0xFFFFFF))
            .flex()
            .justify_center()
            .items_center()
            .text_3xl()
            .child("Hello")
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Applying an animation to a GPUI element

Source: https://matinaniss.github.io/gpui-book/animations/with_animation.html

Demonstrates using with_animation to animate the size of a div element using a repeating ease-in-out animation.

```rust
use std::time::Duration;

use gpui::{
    Animation, AnimationExt, AppContext, Application, Context, IntoElement, ParentElement, Render,
    Styled, Window, WindowOptions, blue, div, ease_in_out, rems, white,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .bg(white())
            .size_full()
            .flex()
            .items_center()
            .justify_center()
            .child(
                div().bg(blue()).with_animation(
                    "animation",
                    Animation::new(Duration::from_secs(1))
                        .repeat()
                        .with_easing(ease_in_out),
                    |this, delta| this.size(rems(delta * 5.)),
                ),
            )
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Define GPUI Actions

Source: https://matinaniss.github.io/gpui-book/interactivity/keyboard.html

Use the actions! macro to define a namespace and a list of unit structs representing application actions.

```rust
use gpui::actions;

actions!(actions_namespace, [Enter]);
```

--------------------------------

### Create a new Entity in GPUI

Source: https://matinaniss.github.io/gpui-book/state-management/entity.html

Initializes an Entity with the provided state within the application context.

```rust
use gpui::{AppContext, Application};

pub struct SomeState {
    some_value: bool,
}

fn main() {
    Application::new().run(|app| {
        let entity = app.new(|_cx| SomeState { some_value: true });
    });
}
```

--------------------------------

### Configure a repeating GPUI Animation

Source: https://matinaniss.github.io/gpui-book/animations/animation.html

Sets an animation to repeat indefinitely using the repeat method.

```rust
use std::time::Duration;

use gpui::Animation;

fn main() {
    Animation::new(Duration::from_secs(1)).repeat();
}
```

--------------------------------

### Render text with a String in GPUI

Source: https://matinaniss.github.io/gpui-book/elements/text.html

Shows rendering using a standard String, noting that this causes heap allocations on every re-render.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, Styled, Window,
    WindowOptions, div, rgb,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .bg(rgb(0xFFFFFF))
            .flex()
            .justify_center()
            .items_center()
            .text_3xl()
            .child(String::from("Hello"))
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Workspace project file structure

Source: https://matinaniss.github.io/gpui-book/getting-started/create-gpui-app.html

The directory layout generated for a workspace-based GPUI application.

```text
my-app
├── Cargo.toml
├── crates
│   └── my-app
│       ├── Cargo.toml
│       └── src
│           └── main.rs
└── README.md
```

--------------------------------

### Spawn asynchronous tasks with App

Source: https://matinaniss.github.io/gpui-book/architecture/app.html

Enqueues an asynchronous task on the main thread using the spawn method.

```rust
use gpui::Application;

fn main() {
    Application::new().run(|app| {
        app.spawn(async |app| {
            // Some asynchronous work
        })
        .detach();
    });
}
```

--------------------------------

### Handle Actions with Focus

Source: https://matinaniss.github.io/gpui-book/interactivity/keyboard.html

Use track_focus on an element and bind a callback with on_action to respond to dispatched actions when the element is focused.

```rust
use gpui::{
    AppContext, Application, Context, FocusHandle, InteractiveElement, IntoElement, Render, Window,
    WindowOptions, actions, div,
};

actions!(actions_namespace, [Enter]);

struct RootView {
    focus_handle: FocusHandle,
}

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .track_focus(&self.focus_handle)
            .on_action(|&Enter, _window, _app| {
                println!("Enter key hit!");
            })
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |window, app| {
            app.bind_keys([gpui::KeyBinding::new("enter", Enter, None)]);

            let focus_handle = app.focus_handle();
            focus_handle.focus(window);

            app.new(|_cx| RootView { focus_handle })
        })
        .unwrap();
    });
}
```

--------------------------------

### Adding Multiple Children

Source: https://matinaniss.github.io/gpui-book/elements/div.html

Shows how to add multiple child elements to a div using the children method with an array.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, Window, WindowOptions,
    div,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().children([div(), div()])
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Render an image using a file path in GPUI

Source: https://matinaniss.github.io/gpui-book/elements/img.html

Uses the CARGO_MANIFEST_DIR environment variable to locate and render an image file within a GPUI view.

```rust
use std::path::Path;

use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, Styled, Window,
    WindowOptions, div, img,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .child(img(Path::new(env!("CARGO_MANIFEST_DIR")).join("image.png")).size_full())
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Retrieve Window Bounds

Source: https://matinaniss.github.io/gpui-book/architecture/window.html

Accesses the origin and size of the platform window using the bounds method.

```rust
use gpui::{AppContext, Application, Context, Empty, IntoElement, Render, Window, WindowOptions};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        Empty
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |window, app| {
            println!("{:?}", window.bounds());

            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Using Background Timers

Source: https://matinaniss.github.io/gpui-book/async/background-executor.html

Creates a task that completes after a specified duration, which can be awaited within an asynchronous block.

```rust
use std::time::Duration;

use gpui::Application;

fn main() {
    Application::new().run(|app| {
        let timer = app.background_executor().timer(Duration::from_secs(10));

        app.background_executor()
            .spawn(async {
                timer.await;
                println!("Timer Finished!");
            })
            .detach();
    });
}
```

--------------------------------

### Handle click events with on_click

Source: https://matinaniss.github.io/gpui-book/interactivity/mouse.html

Bind a callback to the left-click release event using the on_click method on a stateful element.

```rust
use gpui::{
    AppContext, Application, Context, InteractiveElement, IntoElement, ParentElement, Render,
    StatefulInteractiveElement, Styled, Window, WindowOptions, div, red, white,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .flex()
            .items_center()
            .justify_center()
            .child(
                div()
                    .id("some_id")
                    .bg(red())
                    .text_color(white())
                    .h_6()
                    .child("Click Here")
                    .on_click(|event, _window, _app| {
                        println!("{event:#?}");
                    }),
            )
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### spawn(Future)

Source: https://matinaniss.github.io/gpui-book/async/background-executor.html

Enqueues a future to run on a background thread, returning a Task that can be detached or awaited.

```APIDOC
## spawn(future)

### Description
Takes a `Future` and enqueues it to run on a background thread. Returns a `Task<T>`. If the task is dropped, it is cancelled immediately; use `detach()` to allow it to run to completion.

### Signature
`fn spawn<T>(&self, future: impl Future<Output = T> + Send + 'static) -> Task<T>`
```

--------------------------------

### Observe Global State Changes

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Registers a callback to be executed whenever the specified global state is updated.

```rust
use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let subscription = app.observe_global::<SomeState>(|_app| {
            // Global update callback
        });

        // OR

        app.observe_global::<SomeState>(|_app| {
            // Global update callback
        })
        .detach();
    });
}
```

--------------------------------

### Nesting a Single Child

Source: https://matinaniss.github.io/gpui-book/elements/div.html

Demonstrates how to add a single child element to a div using the child method.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, Window, WindowOptions,
    div,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().child(div())
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### timer(Duration)

Source: https://matinaniss.github.io/gpui-book/async/background-executor.html

Creates a task that completes after the specified duration.

```APIDOC
## timer(duration)

### Description
Takes a `Duration` and returns a `Task<()>` that completes after the elapsed duration. This task can be awaited in a future.

### Signature
`fn timer(&self, duration: Duration) -> Task<()>`
```

--------------------------------

### Spawning Background Tasks

Source: https://matinaniss.github.io/gpui-book/async/background-executor.html

Enqueues a future to run on a background thread. Use detach to ensure the task runs to completion instead of being cancelled when dropped.

```rust
use gpui::Application;

fn main() {
    Application::new().run(|app| {
        app.background_executor()
            .spawn(async {
                // Some asynchronous work
            })
            .detach();
    });
}
```

--------------------------------

### Spawning Tasks on the Foreground Executor

Source: https://matinaniss.github.io/gpui-book/async/foreground-executor.html

Enqueues a future to run on the main thread and uses detach to ensure the task runs to completion.

```rust
use gpui::Application;

fn main() {
    Application::new().run(|app| {
        app.foreground_executor()
            .spawn(async {
                // Some asynchronous work
            })
            .detach();
    });
}
```

--------------------------------

### Configure repeating Animation

Source: https://matinaniss.github.io/gpui-book/print.html

Configures an animation to repeat indefinitely.

```rust

use std::time::Duration;

use gpui::Animation;

fn main() {
    Animation::new(Duration::from_secs(1)).repeat();
}
```

--------------------------------

### Animation::new(duration: Duration)

Source: https://matinaniss.github.io/gpui-book/animations/animation.html

Creates a new Animation instance with a specified duration.

```APIDOC
## Animation::new(duration: Duration)

### Description
Initializes a new animation with the provided duration.

### Signature
`Animation::new(duration: Duration) -> Animation`

### Parameters
- **duration** (Duration) - Required - The length of time the animation should run.
```

--------------------------------

### Animation::repeat()

Source: https://matinaniss.github.io/gpui-book/animations/animation.html

Configures the animation to repeat indefinitely.

```APIDOC
## Animation::repeat()

### Description
Sets the animation to repeat indefinitely.

### Signature
`Animation::repeat(&mut self) -> &mut Self`
```

--------------------------------

### Basic Deferred Element Usage

Source: https://matinaniss.github.io/gpui-book/elements/deferred.html

Wraps a child element in a Deferred element to delay its layout and paint.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, Window, WindowOptions,
    deferred, div,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().child(deferred(div()))
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### background_executor()

Source: https://matinaniss.github.io/gpui-book/async/background-executor.html

Retrieves a reference to the platform's BackgroundExecutor from the application context.

```APIDOC
## background_executor()

### Description
Returns a reference to the platform `BackgroundExecutor`.

### Signature
`fn background_executor(&self) -> BackgroundExecutor`
```

--------------------------------

### Initialize Default Global State

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Retrieves a mutable reference to the global, initializing it with the type's Default implementation if it is not already set.

```rust
use gpui::{Application, Global};

#[derive(Default)]
pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        app.default_global::<SomeState>();
    });
}
```

--------------------------------

### Try Access Global State

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Retrieves a reference to the global state wrapped in an Option, avoiding panics if the global is not set.

```rust
use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let some_state = app.try_global::<SomeState>();
    });
}
```

--------------------------------

### Handle hover events with on_hover

Source: https://matinaniss.github.io/gpui-book/interactivity/mouse.html

Bind a callback to hover entry and exit events using the on_hover method, which provides a boolean indicating the hover state.

```rust
use gpui::{
    AppContext, Application, Context, InteractiveElement, IntoElement, ParentElement, Render,
    StatefulInteractiveElement, Styled, Window, WindowOptions, div, red, white,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .flex()
            .items_center()
            .justify_center()
            .child(
                div()
                    .id("some_id")
                    .bg(red())
                    .text_color(white())
                    .h_6()
                    .child("Hover Here")
                    .on_hover(|hovered, _window, _app| {
                        println!(
                            "{}",
                            if *hovered {
                                "Hover started"
                            } else {
                                "Hover ended"
                            }
                        );
                    }),
            )
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Render text with SharedString in GPUI

Source: https://matinaniss.github.io/gpui-book/elements/text.html

Uses SharedString to avoid heap allocations during re-renders by utilizing an immutable, cheaply cloneable string type.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, SharedString, Styled,
    Window, WindowOptions, div, rgb,
};

struct RootView {
    text: SharedString,
}

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .bg(rgb(0xFFFFFF))
            .flex()
            .justify_center()
            .items_center()
            .text_3xl()
            .child(self.text.clone())
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView {
                text: SharedString::new_static("Hello"),
            })
        })
        .unwrap();
    });
}
```

--------------------------------

### Accessing the Background Executor

Source: https://matinaniss.github.io/gpui-book/async/background-executor.html

Retrieves a reference to the platform's background executor from the application context.

```rust
use gpui::{AppContext, Application};

fn main() {
    Application::new().run(|app| {
        let background_executor = app.background_executor();
    });
}
```

--------------------------------

### Accessing the Foreground Executor

Source: https://matinaniss.github.io/gpui-book/async/foreground-executor.html

Retrieves a reference to the platform's foreground executor from the application context.

```rust
use gpui::{AppContext, Application};

fn main() {
    Application::new().run(|app| {
        let foreground_executor = app.foreground_executor();
    });
}
```

--------------------------------

### Apply easing to Animation

Source: https://matinaniss.github.io/gpui-book/print.html

Applies an easing function to modify the animation delta over time.

```rust

use std::time::Duration;

use gpui::{Animation, ease_in_out};

fn main() {
    Animation::new(Duration::from_secs(1)).with_easing(ease_in_out);
}
```

--------------------------------

### Retrieve Mouse Position

Source: https://matinaniss.github.io/gpui-book/architecture/window.html

Retrieves the x and y coordinates of the mouse relative to the window.

```rust
use gpui::{AppContext, Application, Context, Empty, IntoElement, Render, Window, WindowOptions};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        Empty
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |window, app| {
            println!("{:?}", window.mouse_position());

            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Render StyledText with TextRuns

Source: https://matinaniss.github.io/gpui-book/elements/text.html

Use StyledText to apply different styles to specific ranges of text using TextRun objects. This is only necessary when the text requires multiple styles within a single component.

```rust
use gpui::{
    AppContext, Application, Context, Font, FontFeatures, FontStyle, FontWeight, IntoElement,
    ParentElement, Render, SharedString, StrikethroughStyle, Styled, StyledText, TextRun,
    UnderlineStyle, Window, WindowOptions, div, hsla, px, rgb,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .bg(rgb(0xFFFFFF))
            .flex()
            .justify_center()
            .items_center()
            .text_3xl()
            .child(StyledText::new("Text").with_runs(vec![
                TextRun {
                    len: 2,
                    font: Font {
                        family: SharedString::new_static(".SystemUIFont"),
                        features: FontFeatures::default(),
                        fallbacks: None,
                        weight: FontWeight::default(),
                        style: FontStyle::default(),
                    },
                    color: hsla(0., 1., 0.5, 1.),
                    background_color: None,
                    underline: None,
                    strikethrough: Some(StrikethroughStyle {
                        thickness: px(1.),
                        color: Some(hsla(0., 1., 0.5, 1.)),
                    }),
                },
                TextRun {
                    len: 3,
                    font: Font {
                        family: SharedString::new_static(".SystemUIFont"),
                        features: FontFeatures::default(),
                        fallbacks: None,
                        weight: FontWeight::default(),
                        style: FontStyle::default(),
                    },
                    color: hsla(240. / 360., 1., 0.5, 1.),
                    background_color: None,
                    underline: Some(UnderlineStyle {
                        thickness: px(1.),
                        color: Some(hsla(240. / 360., 1., 0.5, 1.)),
                        wavy: true,
                    }),
                    strikethrough: None,
                },
            ]))
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Animation::with_easing(easing: impl Fn(f32) -> f32)

Source: https://matinaniss.github.io/gpui-book/animations/animation.html

Applies an easing function to the animation to modify the progression delta.

```APIDOC
## Animation::with_easing(easing: impl Fn(f32) -> f32)

### Description
Applies a custom easing function to the animation. GPUI provides built-in functions like `linear`, `quadratic`, `ease_in_out`, and `ease_out_quint`.

### Signature
`Animation::with_easing(&mut self, easing: impl Fn(f32) -> f32) -> &mut Self`

### Parameters
- **easing** (impl Fn(f32) -> f32) - Required - A closure that takes a delta (f32) and returns a modified delta (f32).
```

--------------------------------

### Apply easing to a GPUI Animation

Source: https://matinaniss.github.io/gpui-book/animations/animation.html

Modifies the animation delta using a closure or built-in easing functions like ease_in_out.

```rust
use std::time::Duration;

use gpui::{Animation, ease_in_out};

fn main() {
    Animation::new(Duration::from_secs(1)).with_easing(ease_in_out);
}
```

--------------------------------

### Style elements using the Style struct

Source: https://matinaniss.github.io/gpui-book/styling/index.html

Modifies the underlying Style struct directly for more verbose but explicit control.

```rust
impl Render for SomeView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        let mut element = div().child("Hello").child("World");

        let style = element.style();
        style.display = Some(Display::Flex);
        style.flex_direction = Some(FlexDirection::Column);

        element
    }
}
```

--------------------------------

### Check Global Existence

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Verifies whether a global has been set for the specified type.

```rust
use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let is_set_bool = app.has_global::<SomeState>();
    });
}
```

--------------------------------

### Update Global State

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Updates the global state using a closure.

```rust
use gpui::{Application, BorrowAppContext, Global, UpdateGlobal};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        app.update_global::<SomeState, _>(|some_state, _app| {
            some_state.some_value = false;
        });

        // OR

        SomeState::update_global(app, |some_state, _app| {
            some_state.some_value = false;
        });
    });
}
```

--------------------------------

### Read Global State

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Retrieves a reference to the global state. Accessing a non-existent global will cause a panic.

```rust
use gpui::{Application, Global, ReadGlobal};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let some_state = app.global::<SomeState>();

        // OR

        let some_state = SomeState::global(app);
    });
}
```

--------------------------------

### Apply Animation to an element

Source: https://matinaniss.github.io/gpui-book/print.html

Uses with_animation to apply an animation to an element, utilizing a closure to style the element based on the animation delta.

```rust

use std::time::Duration;

use gpui::{
    Animation, AnimationExt, AppContext, Application, Context, IntoElement, ParentElement, Render,
    Styled, Window, WindowOptions, blue, div, ease_in_out, rems, white,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .bg(white())
            .size_full()
            .flex()
            .items_center()
            .justify_center()
            .child(
                div().bg(blue()).with_animation(
                    "animation",
                    Animation::new(Duration::from_secs(1))
                        .repeat()
                        .with_easing(ease_in_out),
                    |this, delta| this.size(rems(delta * 5.)),
                ),
            )
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Implement Global Marker Trait

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Types must implement the Global marker trait before they can be registered as global state.

```rust
use gpui::Global;

pub struct SomeState {
    some_value: bool,
}

// Global marker trait
impl Global for SomeState {}
```

--------------------------------

### Notify an Entity of Updates in GPUI

Source: https://matinaniss.github.io/gpui-book/architecture/context.html

Use the notify method within an entity update block to signal that the state has changed and observers should be notified.

```rust
use gpui::{AppContext, Application};

pub struct SomeState {
    some_value: bool,
}

fn main() {
    Application::new().run(|app| {
        let entity = app.new(|_cx| SomeState { some_value: true });

        entity.update(app, |this, cx| {
            this.some_value = false;

            cx.notify();
        });
    });
}
```

--------------------------------

### Downgrade Entity to WeakEntity

Source: https://matinaniss.github.io/gpui-book/state-management/entity.html

Converts an Entity into a WeakEntity to create a weak pointer reference.

```rust
use gpui::{AppContext, Application};

pub struct SomeState {
    some_value: bool,
}

fn main() {
    Application::new().run(|app| {
        let entity = app.new(|_cx| SomeState { some_value: true });

        let weak_entity = entity.downgrade();
    });
}
```

--------------------------------

### Read Entity state

Source: https://matinaniss.github.io/gpui-book/state-management/entity.html

Retrieves a reference to the state stored within an Entity.

```rust
use gpui::{AppContext, Application};

pub struct SomeState {
    some_value: bool,
}

fn main() {
    Application::new().run(|app| {
        let entity = app.new(|_cx| SomeState { some_value: true });

        let some_state = entity.read(app);
    });
}
```

--------------------------------

### Deferred Element with Priority

Source: https://matinaniss.github.io/gpui-book/elements/deferred.html

Sets a priority value to control the painting order relative to other deferred elements, where higher values are drawn on top.

```rust
use gpui::{
    AppContext, Application, Context, IntoElement, ParentElement, Render, Window, WindowOptions,
    deferred, div,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().child(deferred(div()).with_priority(10))
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Set Global State

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Registers a global instance for a specific type. The type must implement the Global trait.

```rust
use gpui::{Application, Global, UpdateGlobal};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        // OR

        SomeState::set_global(app, SomeState { some_value: true });
    });
}
```

--------------------------------

### Render InteractiveText with event listeners

Source: https://matinaniss.github.io/gpui-book/elements/text.html

Use InteractiveText to attach click or hover listeners to specific text ranges. The component requires a unique ElementId that remains consistent across frames.

```rust
use gpui::{
    AppContext, Application, Context, InteractiveText, IntoElement, ParentElement, Render, Styled,
    StyledText, Window, WindowOptions, div, rgb,
};

struct RootView;

impl Render for RootView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .size_full()
            .bg(rgb(0xFFFFFF))
            .flex()
            .justify_center()
            .items_center()
            .text_3xl()
            .child(
                InteractiveText::new("interactive_text_id", StyledText::new("Text")).on_click(
                    vec![1..3],
                    |_range_index, _window, _app| {
                        println!("Clicked");
                    },
                ),
            )
    }
}

fn main() {
    Application::new().run(|app| {
        app.open_window(WindowOptions::default(), |_window, app| {
            app.new(|_cx| RootView)
        })
        .unwrap();
    });
}
```

--------------------------------

### Mutate Global State

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Retrieves a mutable reference to the global state. Accessing a non-existent global will cause a panic.

```rust
use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let some_state = app.global_mut::<SomeState>();
        some_state.some_value = false;
    });
}
```

--------------------------------

### Update Entity state

Source: https://matinaniss.github.io/gpui-book/state-management/entity.html

Modifies the state held by an Entity using the update method.

```rust
use gpui::{AppContext, Application};

pub struct SomeState {
    some_value: bool,
}

fn main() {
    Application::new().run(|app| {
        let entity = app.new(|_cx| SomeState { some_value: true });

        entity.update(app, |some_state, _cx| {
            some_state.some_value = false;
        });
    });
}
```

--------------------------------

### Remove Global State

Source: https://matinaniss.github.io/gpui-book/state-management/global.html

Removes the global instance associated with the given type.

```rust
use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        app.remove_global::<SomeState>();
    });
}
```
Tokens:
Raw