Struct Application 

pub struct Application(/* private fields */);

The entry point for a GPUI application. Configure it, then call Application::run.

Get one from gpui_platform::application(), which picks the platform for the current target. Configure it with the with_* and on_* builder methods, then call Application::run from main. The callback you pass to run receives the App once the platform has finished launching. That is where you open windows, bind keys and set globals.

The with_* methods take the application by value and return it, so you can chain them. Call them before Application::run.

run blocks until the app quits on native platforms, so anything after it in main runs only after the app exits. Once the app is running, you use App instead of Application.

Examples

use gpui::{App, Window, WindowOptions, div, prelude::*};

struct HelloWorld;

impl Render for HelloWorld {
    fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
        div().child("Hello, world!")
    }
}

fn main() {
    gpui_platform::application().run(|cx: &mut App| {
        cx.open_window(WindowOptions::default(), |_, cx| cx.new(|_| HelloWorld))
            .unwrap();
    });
}

See the start a project guide for a complete app. TestApp runs app code without a display, and is available with the test-support feature.

Implementations

impl Application

pub fn with_platform(platform: Rc<dyn Platform>) -> Self

Creates an application that uses a platform implementation you provide.

Most apps should use gpui_platform::application(), which chooses the platform for you. Use this when you want a custom or test platform. The app starts with an empty AssetRegistry, an HTTP client that fails every request, and QuitMode::Default.

Panics

Panics if called from a thread other than the main thread.

pub fn new_inaccessible(platform: Rc<dyn Platform>) -> Self

Builds an app with accessibility (AccessKit) integration forcibly disabled.

In this mode, accessibility APIs (e.g. div().role()) silently no-op.

See the accessibility guide for the features this disables.

pub fn with_accessibility_forced(self) -> Self

Build every window’s accessibility tree every frame, even when no assistive technology is connected.

For automation and tree inspection: crate::Window::debug_a11y_tree_json otherwise reports nothing until a screen reader activates the platform adapter. Application::new_inaccessible still wins when both are set.

pub fn with_assets(self, assets: impl Into<AssetRegistry>) -> Self

Sets the source of assets (images, fonts and SVGs) that the app loads by path.

The registry is returned by App::assets, and the SVG renderer is rebuilt to read from it. Set it before you open windows that load assets.

pub fn with_restart_arguments(self, arguments: Vec<OsString>) -> Self

Sets the command-line arguments that App::restart passes to the new process.

pub fn with_http_client(self, http_client: Arc<dyn HttpClient>) -> Self

Sets the HTTP client that App::http_client returns.

The default fails every request. Pass a real client to let the app fetch URLs, for example for remote images.

pub fn with_quit_mode(self, mode: QuitMode) -> Self

Sets when the app quits on its own. See QuitMode for the choices.

Defaults to QuitMode::Default. You can also change it at runtime with App::set_quit_mode.

pub fn with_windowing(self, request: WindowingRequest) -> Self

Starts the event loop and calls on_finish_launching once the app has launched.

The callback runs on the main thread with the App, and runs once. Open your first window there. On native platforms this method blocks until the app quits, so code after it runs only after the app exits. On the web it returns right away, and the app keeps running in the page.

See the Application example for a complete main. Sets the windowing mode the app starts in. See App::request_windowing.

Defaults to windowed. On Linux, the default environment is the process’s own, and the app starts headless if that names no allowed display server. On macOS, headless means the app starts without a Dock icon or menu bar (ActivationPolicy::Accessory). Has no effect on other platforms.

pub fn run<F>(self, on_finish_launching: F)

where F: 'static + FnOnce(&mut App),

Start the application. The provided callback will be called once the app is fully launched.

On WebAssembly, this returns immediately and retains the app for the lifetime of the Wasm instance. Use Self::run_embedded to control its lifetime explicitly.

pub fn run_embedded<F>(self, on_finish_launching: F) -> ApplicationHandle

where F: 'static + FnOnce(&mut App),

Start the application for an embedder that drives the run loop itself.

On ordinary platforms Platform::run blocks for the lifetime of the app, and the app state is kept alive by Application::run’s stack frame. Embedded platforms — where the run loop belongs to someone else, e.g. GPUI compiled into a Wasm guest, or a GPUI view hosted inside a foreign native application — implement Platform::run to invoke the launch callback and return immediately. This method supports that shape: it returns an ApplicationHandle that keeps the app alive and lets the embedder re-enter it whenever the external run loop yields control.

pub fn on_open_urls<F>(&self, callback: F) -> &Self

where F: 'static + FnMut(Vec<String>),

Registers a handler for URLs that the user asks the app to open.

The handler receives the URLs as strings. Register a scheme with App::register_url_scheme so the platform routes links with that scheme to the app.

pub fn on_reopen<F>(&self, callback: F) -> &Self

where F: 'static + FnMut(&mut App),

Registers a handler for a second launch while the app is already running.

On macOS this happens when the user clicks the app icon in the Dock or in Finder. A common response is to open a window if none is visible. The handler receives the App.

pub fn background_executor(&self) -> BackgroundExecutor

Returns the executor for Send futures. See BackgroundExecutor for platform behavior.

pub fn foreground_executor(&self) -> ForegroundExecutor

Returns the executor for futures that run on the foreground thread.

pub fn text_system(&self) -> Arc<TextSystem>

Returns a shared handle to the app’s TextSystem, which shapes and rasterizes text.

pub fn path_for_auxiliary_executable(&self, name: &str) -> Result<PathBuf>

Returns the path to a helper executable named name that ships with the app.

Use this to launch a companion binary, such as a CLI or a helper process. It returns an error if the platform cannot find the executable.