Struct AsyncWindowContext 

pub struct AsyncWindowContext { /* private fields */ }

A handle to the app and one window, for use across .await points.

Get one from Context::spawn_in or Window::spawn. It derefs to AsyncApp, so the methods of AsyncApp are available on it too. The window methods on this type return an error once the window has closed.

Use it inside a future when you need the window and not only the app. See contexts.

Examples

use gpui::{Context, Render, TestApp, Window, div, prelude::*};

struct Panel {
    updates: usize,
}

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

let mut app = TestApp::new();
let mut window = app.open_window(|_window, _cx| Panel { updates: 0 });

window.update(|panel, window, cx| {
    cx.spawn_in(window, async move |panel, cx| {
        panel
            .update(cx, |panel, cx| {
                panel.updates += 1;
                cx.notify();
            })
            .ok();
    })
    .detach();
});

app.run_until_parked();
window.read(|panel, _cx| assert_eq!(panel.updates, 1));

Implementations

impl AsyncWindowContext

pub fn window_handle(&self) -> AnyWindowHandle

Returns the handle of the window this context is for.

pub fn update<R>( &mut self, update: impl FnOnce(&mut Window, &mut App) -> R, ) -> Result<R>

Runs update with the window and the app, and returns its result.

Effects queued by update are flushed before this returns.

Errors

Returns an error if the window has closed, or if the app is quitting or already borrowed.

pub fn update_root<R>( &mut self, update: impl FnOnce(AnyView, &mut Window, &mut App) -> R, ) -> Result<R>

Like AsyncWindowContext::update, but also passes the window’s root view.

Errors

Returns an error under the same conditions as AsyncWindowContext::update.

pub fn on_next_frame(&mut self, f: impl FnOnce(&mut Window, &mut App) + 'static)

Runs f before the window draws its next frame. Does nothing if the window has closed.

Schedules the callback like Window::on_next_frame, but tolerates a window that has already been closed.

pub fn read_global<G: Global, R>( &mut self, read: impl FnOnce(&G, &Window, &App) -> R, ) -> Result<R>

Calls read with the global of type G, the window and the app, and returns its result.

Errors

Returns an error if the window has closed.

Panics

Panics if no global of type G has been set.

pub fn update_global<G, R>( &mut self, update: impl FnOnce(&mut G, &mut Window, &mut App) -> R, ) -> Result<R>

where G: Global,

Updates the global of type G with update, and returns its result.

The global is taken out of the app while update runs, as with AsyncApp::update_global.

Errors

Returns an error if the window has closed.

Panics

Panics if no global of type G has been set.

pub fn spawn<AsyncFn, R>(&self, f: AsyncFn) -> Task<R>

where AsyncFn: AsyncFnOnce(&mut AsyncWindowContext) -> R + 'static, R: 'static,

Runs the future returned by f on the main thread, with an AsyncWindowContext for this window, and returns a task for its result.

Dropping the returned Task cancels the future. Store it, await it or call Task::detach.

pub fn prompt<T>( &mut self, level: PromptLevel, message: &str, detail: Option<&str>, answers: &[T], ) -> Receiver<usize>

where T: Clone + Into<PromptButton>,

Shows a platform alert with one button for each entry in answers.

The receiver resolves to the index of the button the user clicked. If the window has closed, the receiver is canceled, so awaiting it returns an error. See Window::prompt for level and detail.

Methods from Deref<Target = AsyncApp>

pub fn refresh(&self)

Schedules a redraw of every window.

The windows draw on the next frame. This doesn’t draw anything itself.

pub fn background_executor(&self) -> &BackgroundExecutor

Returns the BackgroundExecutor, for running work on other threads.

pub fn is_test(&self) -> bool

Whether this app runs on the deterministic test scheduler. See BackgroundExecutor::is_test.

pub fn foreground_executor(&self) -> &ForegroundExecutor

Returns the ForegroundExecutor, for running futures on the main thread.

pub fn update<R>(&self, f: impl FnOnce(&mut App) -> R) -> R

Runs f with the app and returns its result.

Effects queued by f, such as notifications, are flushed before this returns.

Panics

Panics if the app has been released, or if it is already borrowed, such as when called from inside another update.

pub fn subscribe<T, Event>( &mut self, entity: &Entity<T>, on_event: impl FnMut(Entity<T>, &Event, &mut App) + 'static, ) -> Subscription

where T: 'static + EventEmitter<Event>, Event: 'static,

Calls on_event each time entity emits an Event.

The callback receives the emitting entity, the event and the app. The subscription stays active while you hold it. Dropping it unsubscribes, and Subscription::detach keeps the subscription for as long as the entity lives. Inside an entity’s own context, Context::subscribe is the usual choice.

pub fn open_window<V>( &self, options: WindowOptions, build_root_view: impl FnOnce(&mut Window, &mut App) -> Entity<V>, ) -> Result<WindowHandle<V>>

where V: 'static + Render,

Opens a window with options and returns a handle to it.

build_root_view creates the window’s root view. The method returns an error if the app is quitting.

Panics

Panics if the app has been released, or if it is already borrowed.

pub fn spawn<AsyncFn, R>(&self, f: AsyncFn) -> Task<R>

where AsyncFn: AsyncFnOnce(&mut AsyncApp) -> R + 'static, R: 'static,

Runs the future returned by f on the main thread, and returns a task for its result.

f receives an &mut AsyncApp. Dropping the returned Task cancels the future, so store it, await it or call Task::detach.

pub fn has_global<G: Global>(&self) -> bool

Returns whether a global of type G has been set.

pub fn read_global<G: Global, R>(&self, read: impl FnOnce(&G, &App) -> R) -> R

Calls read with the global of type G and the app, and returns its result.

Use AsyncApp::try_read_global if the global may not be set.

Panics

Panics if no global of type G has been set, or if the app has been released.

pub fn try_read_global<G: Global, R>( &self, read: impl FnOnce(&G, &App) -> R, ) -> Option<R>

Like AsyncApp::read_global, but returns None instead of panicking when no global of type G is set, or when the app is quitting.

pub fn read_default_global<G: Global + Default, R>( &self, read: impl FnOnce(&G, &App) -> R, ) -> R

Like AsyncApp::read_global, but first sets a G::default() if no global of type G has been set.

pub fn update_global<G: Global, R>( &self, update: impl FnOnce(&mut G, &mut App) -> R, ) -> R

Updates the global of type G with update, and returns its result.

While update runs, the global is taken out of the app. Reading it through the app from inside update panics, so change the global through the &mut G that update receives.

Panics

Panics if no global of type G has been set, or if the app has been released.

pub fn on_drop<T: 'static, Callback: FnOnce(&mut T, &mut Context<'_, T>) + 'static>( &self, entity: &WeakEntity<T>, f: Callback, ) -> Deferred<impl FnOnce() + use<T, Callback>>

Returns a guard that calls f with entity when the guard is dropped.

f doesn’t run if the entity has been released by then. Hold the guard in a variable. A guard that is dropped at once runs f immediately.

Examples

use gpui::{AppContext, TestApp};

let mut app = TestApp::new();
let log = app.update(|cx| cx.new(|_| Vec::<&'static str>::new()));
let guard = app.update(|cx| {
    cx.to_async().on_drop(&log.downgrade(), |log, cx| {
        log.push("finished");
        cx.notify();
    })
});
drop(guard);
app.read(|cx| assert_eq!(*log.read(cx), vec!["finished"]));

Trait Implementations

impl AppContext for AsyncWindowContext

fn new<T>( &mut self, build_entity: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Entity<T>

where T: 'static,

Creates an entity from build_entity, and returns a handle to it.

fn reserve_entity<T: 'static>(&mut self) -> Reservation<T>

Reserves an entity slot, and returns a Reservation for it.

fn insert_entity<T: 'static>( &mut self, reservation: Reservation<T>, build_entity: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Entity<T>

Creates the entity for a Reservation from AppContext::reserve_entity.

fn update_entity<T: 'static, R>( &mut self, handle: &Entity<T>, update: impl FnOnce(&mut T, &mut Context<'_, T>) -> R, ) -> R

Runs update with the entity and a Context for it, and returns the result.

fn as_mut<'a, T>(&'a mut self, _: &Entity<T>) -> GpuiBorrow<'a, T>

where T: 'static,

Borrows the entity mutably, without a closure.

fn read_entity<T, R>( &self, handle: &Entity<T>, read: impl FnOnce(&T, &App) -> R, ) -> R

where T: 'static,

Reads the entity with a shared borrow, and returns the result of read.

fn notify(&mut self, entity_id: EntityId)

Tells GPUI that the entity with entity_id changed. Its observers run and windows that show it redraw.

fn emit<EntityType, EventType>( &mut self, entity: &Entity<EntityType>, event: EventType, )

where EntityType: EventEmitter<EventType>, EventType: 'static,

Emits event from entity.

fn update_window<T, F>( &mut self, window: AnyWindowHandle, update: F, ) -> Result<T>

where F: FnOnce(AnyView, &mut Window, &mut App) -> T,

Runs f with the window’s root view, the window and the app, and returns the result.

fn with_window<R>( &mut self, entity_id: EntityId, f: impl FnOnce(&mut Window, &mut App) -> R, ) -> Option<R>

Runs f with the window that most recently rendered the entity entity_id, and returns the result.

fn read_window<T, R>( &self, window: &WindowHandle<T>, read: impl FnOnce(Entity<T>, &App) -> R, ) -> Result<R>

where T: 'static,

Reads the root view of window with the app, and returns the result.

fn background_spawn<R>( &self, future: impl Future<Output = R> + Send + 'static, ) -> Task<R>

where R: Send + 'static,

Runs future on the background executor and returns a task for its result.

fn read_global<G, R>(&self, callback: impl FnOnce(&G, &App) -> R) -> R

where G: Global,

Calls callback with the global of type G and the app, and returns the result.

fn insert_global_entity<T: 'static>(&mut self, entity: Entity<T>)

Keeps entity alive without a handle to it.

fn remove_global_entity<T: 'static>(&mut self, entity: &Entity<T>)

Stops keeping entity alive. It’s dropped once no other handle refers to it.

fn global_entities<T: 'static>(&self) -> impl Iterator<Item = Entity<T>>

Returns the entities stored with AppContext::insert_global_entity whose type is T.

impl Clone for AsyncWindowContext

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Deref for AsyncWindowContext

type Target = AsyncApp

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for AsyncWindowContext

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl VisualContext for AsyncWindowContext

type Result<T> = Result<T, Error>

The return type of window operations.

fn window_handle(&self) -> AnyWindowHandle

Returns the handle of the window this context works in.

fn new_window_entity<T: 'static>( &mut self, build_entity: impl FnOnce(&mut Window, &mut Context<'_, T>) -> T, ) -> Result<Entity<T>>

Creates an entity with access to the window.

fn update_window_entity<T: 'static, R>( &mut self, view: &Entity<T>, update: impl FnOnce(&mut T, &mut Window, &mut Context<'_, T>) -> R, ) -> Result<R>

Runs update with the entity, its window and a Context for the entity, and returns the result, wrapped in VisualContext::Result.

fn replace_root_view<V>( &mut self, build_view: impl FnOnce(&mut Window, &mut Context<'_, V>) -> V, ) -> Result<Entity<V>>

where V: 'static + Render,

Replaces the root view of the window with the view that build_view creates, and returns a handle to the new view.

fn focus<V>(&mut self, view: &Entity<V>) -> Result<()>

where V: Focusable,

Moves keyboard focus to entity, using its Focusable::focus_handle.