Trait AppContext 

pub trait AppContext {
    // Required methods
    fn new<T: 'static>(
        &mut self,
        build_entity: impl FnOnce(&mut Context<'_, T>) -> T,
    ) -> Entity<T>;
    fn reserve_entity<T: 'static>(&mut self) -> Reservation<T>;
    fn insert_entity<T: 'static>(
        &mut self,
        reservation: Reservation<T>,
        build_entity: impl FnOnce(&mut Context<'_, T>) -> T,
    ) -> Entity<T>;
    fn update_entity<T, R>(
        &mut self,
        handle: &Entity<T>,
        update: impl FnOnce(&mut T, &mut Context<'_, T>) -> R,
    ) -> R
       where T: 'static;
    fn as_mut<'a, T>(&'a mut self, handle: &Entity<T>) -> GpuiBorrow<'a, T>
       where T: 'static;
    fn read_entity<T, R>(
        &self,
        handle: &Entity<T>,
        read: impl FnOnce(&T, &App) -> R,
    ) -> R
       where T: 'static;
    fn notify(&mut self, entity_id: EntityId);
    fn emit<EntityType, EventType>(
        &mut self,
        entity: &Entity<EntityType>,
        event: EventType,
    )
       where EntityType: EventEmitter<EventType>,
             EventType: 'static;
    fn update_window<T, F>(
        &mut self,
        window: AnyWindowHandle,
        f: F,
    ) -> Result<T>
       where F: FnOnce(AnyView, &mut Window, &mut App) -> T;
    fn with_window<R>(
        &mut self,
        entity_id: EntityId,
        f: impl FnOnce(&mut Window, &mut App) -> R,
    ) -> Option<R>;
    fn read_window<T, R>(
        &self,
        window: &WindowHandle<T>,
        read: impl FnOnce(Entity<T>, &App) -> R,
    ) -> Result<R>
       where T: 'static;
    fn background_spawn<R>(
        &self,
        future: impl Future<Output = R> + Send + 'static,
    ) -> Task<R> 
       where R: Send + 'static;
    fn read_global<G, R>(&self, callback: impl FnOnce(&G, &App) -> R) -> R
       where G: Global;
    fn insert_global_entity<T: 'static>(&mut self, entity: Entity<T>);
    fn remove_global_entity<T: 'static>(&mut self, entity: &Entity<T>);
    fn global_entities<T: 'static>(&self) -> impl Iterator<Item = Entity<T>>;
}

Operations shared by GPUI’s app, entity and async contexts.

Write a helper against this trait when it needs only entities, globals or the app. Operations that need a window are on VisualContext. See contexts.

Examples

use gpui::{AppContext, Entity};

fn reset<C: AppContext>(count: &Entity<u64>, cx: &mut C) {
    count.update(cx, |count, cx| {
        *count = 0;
        cx.notify();
    });
}

Required Methods

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

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

build_entity receives a Context for the new entity, so it can subscribe to other entities or start work of its own. The entity lives as long as a handle to it exists, or as long as it’s stored with AppContext::insert_global_entity.

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

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

The reservation’s EntityId is known now, so you can refer to the entity before it exists. Create the entity later with AppContext::insert_entity.

Examples

use gpui::{AppContext, TestApp};

let mut app = TestApp::new();
app.update(|cx| {
    let reservation = cx.reserve_entity::<u32>();
    let id = reservation.entity_id();
    let number = cx.insert_entity(reservation, |_| 7);
    assert_eq!(number.entity_id(), id);
    assert_eq!(*number.read(cx), 7);
});

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.

The entity gets the reservation’s EntityId, and build_entity runs with a Context for it.

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

where T: 'static,

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

Effects queued by update, such as notifications, run when the outermost update finishes.

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

where T: 'static,

Borrows the entity mutably, without a closure.

The returned GpuiBorrow dereferences to the entity. Dropping it notifies observers of the entity. Prefer AppContext::update_entity, which ends the borrow when its closure returns. Use this when you need to hold the borrow across several statements.

Panics

Panics in AsyncApp and AsyncWindowContext, which can’t hold a borrow of the app across an .await. Call update there instead.

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.

read also receives the app, so it can read other state at the same time.

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.

Inside an entity’s update, Context::notify is more convenient.

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

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

Emits event from entity.

Subscribers registered with Context::subscribe or AsyncApp::subscribe receive it when the current update finishes. Inside an entity’s update, Context::emit is more convenient.

fn update_window<T, F>(&mut self, window: AnyWindowHandle, f: 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.

Errors

Returns an error if the window has closed. Async contexts also return an error when the app is already borrowed.

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.

Returns None if no window has rendered the entity, or if that window isn’t available.

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.

Errors

Returns an error if the window has closed.

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.

Native builds use worker threads; single-threaded web builds use the browser’s main thread. The future and its result must be Send + 'static. No app context is supplied, so return to a foreground task to update entities. Dropping the task cancels the future. See BackgroundExecutor::spawn and the executor concept.

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.

Panics

Panics if no global of type G has been set.

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

Keeps entity alive without a handle to it.

The entity stays alive until the app is dropped, or until AppContext::remove_global_entity removes it and no other handle refers 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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl AppContext for App

impl AppContext for AsyncApp

impl AppContext for AsyncWindowContext

impl AppContext for HeadlessAppContext

impl AppContext for TestAppContext

impl AppContext for VisualTestContext

impl<T> AppContext for Context<'_, T>