GPUI-CE Documentation

GPUI provides different levels of context depending on the scope of your operation:

• App: The root context. It owns all entities' data and provides access to the application's global state. Use it to read or update data referenced by any Entity<T>.
• Context<T>: A specialized context provided when interacting with a specific Entity<T>. It includes methods specific to that entity, such as notifying observers and emitting events.

Key Relationship: Context<T> dereferences into App. This means any function that accepts an &App can also accept a &Context<T>.

GPUI provides three primary layers for building applications:

• State Management (Entities): Use Entitys to store application state that needs to be shared across different parts of the app. Entities are owned by GPUI and accessed via owned smart pointers (similar to Rc). See app::context for details.
• High-level Declarative UI (Views): A View is an Entity that implements the Render trait. GPUI calls the render method on the root view every frame. Views build a tree of elements using a Tailwind-style API. The div element is a versatile tool for rendering.
• Low-level Imperative UI (Elements): Elements are the fundamental building blocks. They provide an imperative API for maximum control, useful for high-performance needs like custom layouts for code editors or efficient large lists. See the element module for details.

GPUI separates the handles to state from the state itself using Window and Entity<T>:

• Entity<T>: A handle to a structure that requires state. The actual data is owned by the App. You access and modify this data via context references. If T implements Render, the entity is considered a view. Entities support observation: you can register a closure to be called when notify is called on the entity's Context.
• Window: Provides access to an application window's state. A window has a root view (an Entity implementing Render).

Note: Window is not a context. To read or update a window's root view, you must pass a &mut App (or a context that dereferences to it) to the relevant functions. You can obtain a Window from a WindowHandle by calling WindowHandle::update.

GPUI provides several specialized services to handle common application tasks:

• Actions: Define user-defined structs to map keystrokes to logical UI operations (e.g., mapping cmd-q to a quit action). See the action module.
• Platform Services: Access methods on app::App to perform system-level tasks like quitting the application or opening a URL.
• Async Executor: An executor integrated with the platform's event loop for handling asynchronous tasks. See the executor module.
• Testing: Use the [gpui::test] macro for application testing. Tests can use TestAppContext to simulate platform inputs. See app::test_context and test modules.

GPUI uses context parameters (conventionally named cx) to provide access to application state, services, and entities. Contexts act as references passed to functions to enable interaction with the global state, windows, and system services.

There are two primary types of contexts:

1. Synchronous Contexts: Passed as references (e.g., &mut App or &mut Context<T>). These are used for immediate state access and updates.
2. Asynchronous Contexts: Created by calling .to_async() on a synchronous context. These have a 'static lifetime, allowing them to be held across .await points. Because an async context might outlive the window or app it originated from, interactions using an async context are fallible.

Since GPUI-CE is a drop-in replacement for the mainline GPUI, you can use Cargo's [patch] mechanism to force existing libraries (like gpui-component) to use GPUI-CE instead of the original version.

Use [patch.crates-io] if the dependency is coming from crates.io, or [patch."URL"] if it is coming from a specific git remote.

# If they're using the crates release
[patch.crates-io]
gpui = { git = "https://github.com/gpui-ce/gpui-ce", package = "gpui-ce" }

# If they're using the git remote
[patch."https://github.com/zed-industries/zed.git"]
gpui = { git = "https://github.com/gpui-ce/gpui-ce" }

You can add GPUI-CE to your project using either the crates release or the git version.

Using the crates release: Use the gpui-ce package and the gpui_platform git dependency.

Using the git version: Use the gpui package pointing directly to the gpui-ce repository.

After adding the dependencies, use gpui::{import} as normal in your code.

# Using the crates release
[dependencies]
gpui = { package = "gpui-ce", version = "0.3" }
gpui_platform = { git = "https://github.com/gpui-ce/gpui-ce" }

# For test support
[dev-dependencies]
gpui = { package = "gpui-ce", version = "0.3", features = ["test-support"] }

# Using the git version
gpui = { package = "gpui", git = "https://github.com/gpui-ce/gpui-ce" }

Every GPUI application begins with an Application. The lifecycle follows this pattern:

1. Initialize the application using Application::new().
2. Start the application loop by calling Application::run() and passing a callback.
3. Inside the run callback, use App::open_window() to create a window.
4. Register a root view within that window to begin rendering.

For a complete implementation, refer to the gpui.rs example in the repository.

// Conceptual workflow
Application::new().run(|app| {
    app.open_window(WindowSettings::default(), |window: &mut Window| {
        window.set_root_view(|_| MyRootView::new());
    });
});

GPUI uses Metal for rendering on macOS. To ensure a working environment, follow these steps:

1. Install Xcode: Download from the macOS App Store or the Apple Developer website. Launch Xcode after installation to ensure macOS components are installed.
2. Install Xcode Command Line Tools:

   xcode-select --install

3. Configure Xcode path: Ensure the command line tools point to your Xcode installation:

   sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

GPUI is a hybrid immediate and retained mode, GPU-accelerated UI framework for Rust. It is currently in active development (pre-1.0) and requires the latest version of stable Rust. It is supported on macOS and Linux.

To add GPUI to your project, include it in your Cargo.toml:

gpui = { version = "*" }