Struct Entity 

pub struct Entity<T> { /* private fields */ }

A handle to state owned by the App.

An Entity<T> keeps its value alive while any handle to it exists. Read the value with Entity::read, change it with Entity::update, and call Entity::downgrade for a WeakEntity that doesn’t keep it alive.

Cloning is cheap. The clone is another handle to the same value, and two handles compare equal when they refer to the same entity.

When the last strong handle is dropped, GPUI releases the value at the end of the current update. See ownership and data flow for the model.

Examples

struct Counter {
    count: usize,
}

let counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
let same = counter.clone();

same.update(cx, |counter, _cx| counter.count += 1);
assert_eq!(counter.read(cx).count, 1);

Implementations

impl<T: 'static> Entity<T>

pub fn entity_id(&self) -> EntityId

Returns the id of the entity.

Two handles have the same id exactly when they refer to the same entity.

pub fn downgrade(&self) -> WeakEntity<T>

Returns a WeakEntity to the same value.

A weak handle doesn’t keep the value alive. Use it for back-references, and for callbacks that may run after the entity is released.

pub fn into_any(self) -> AnyEntity

Converts this handle into an AnyEntity. The result keeps the value alive, without its type.

pub fn read<'a>(&self, cx: &'a App) -> &'a T

Returns a shared reference to the value, borrowed from the app.

The reference borrows cx, so you can’t update the app while you hold it. Copy out what you need, or work inside a single Entity::update.

Panics

Panics if this entity is currently being updated, for example when you read it from inside its own Entity::update closure. Use the &mut T that the closure received instead.

Examples

let name = cx.new(|_cx| String::from("GPUI"));

let len = name.read(cx).len();
name.update(cx, |name, _cx| name.push_str("!"));

assert_eq!(len, 4);
assert_eq!(name.read(cx), "GPUI!");

pub fn read_with<R, C: AppContext>( &self, cx: &C, f: impl FnOnce(&T, &App) -> R, ) -> R

Calls read with the value and the app, and returns what read returns.

Use this when the callback needs the app as well as the value. It works with any AppContext, including Context and AsyncApp. It panics in the same cases as Entity::read.

pub fn update<R, C: AppContext>( &self, cx: &mut C, update: impl FnOnce(&mut T, &mut Context<'_, T>) -> R, ) -> R

Changes the value, and returns what update returns.

update receives a &mut T and a Context<T> for this entity. Use it for every change to an entity. Call Context::notify inside the closure when anything that depends on the value has changed. Effects queued by the closure, such as notifications and events, run when the outermost update finishes.

Pass any AppContext as cx: &mut App, a Context of another entity, or an AsyncApp inside a task.

Panics

Panics if this entity is already being updated. Updating it from inside its own closure is the usual cause; use the &mut T you were given instead. Updating other entities is fine.

Examples

struct Counter {
    count: usize,
}

let counter = cx.new(|_cx| Counter { count: 0 });

let count = counter.update(cx, |counter, cx| {
    counter.count += 1;
    cx.notify();
    counter.count
});

assert_eq!(count, 1);

pub fn as_mut<'a, C: AppContext>(&self, cx: &'a mut C) -> GpuiBorrow<'a, T>

Returns a guard that dereferences to the value, so you can change it with * or with methods.

The guard borrows cx for as long as it lives. When the guard is dropped, the entity is notified, as if you had called Context::notify. Use Entity::update when the change needs a Context.

pub fn write<C: AppContext>(&self, cx: &mut C, value: T)

Replaces the value with value, and notifies observers.

Examples

let name = cx.new(|_cx| String::from("draft"));
name.write(cx, String::from("published"));
assert_eq!(name.read(cx), "published");

pub fn update_in<R, C: VisualContext>( &self, cx: &mut C, update: impl FnOnce(&mut T, &mut Window, &mut Context<'_, T>) -> R, ) -> C::Result<R>

Like Entity::update, but also passes the Window that the entity is shown in.

Use it from a VisualContext, which is a context that has a window. Returns an error if the window has been closed.

impl<T: 'static> Entity<T>

pub fn next_event<Event>( &self, cx: &mut TestAppContext, ) -> impl Future<Output = Event>

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

Returns a future that resolves with the next event self emits.

The subscription is made when you call this, not when you await the future, so an event emitted in between is still received.

Panics

Panics if the entity is released before it emits an event.

impl<V: 'static> Entity<V>

pub fn next_notification( &self, advance_clock_by: Duration, cx: &TestAppContext, ) -> impl Future<Output = ()>

Returns a future that resolves on the entity’s next notification.

This advances the simulated clock by advance_clock_by as soon as you call it, before the future is awaited. Use it when the notification comes from a timer that the advance will fire.

Panics

Panics if the entity is released while the future waits.

impl<V> Entity<V>

pub fn condition<Evt>( &self, cx: &TestAppContext, predicate: impl FnMut(&V, &App) -> bool, ) -> impl Future<Output = ()>

where Evt: 'static, V: EventEmitter<Evt>,

Returns a future that resolves when predicate returns true for this entity.

The predicate is checked when the future is first polled, then again after each notification or event from the entity.

Panics

Panics if the entity is released while the future waits.

impl<T: Render> Entity<T>

pub fn cached(self, style: StyleRefinement) -> ViewElement<Entity<T>>

Returns this entity as an element laid out at a fixed root style.

An entity passed directly as a child already keeps its output while nothing it read has changed, and sizes itself from its content. Use cached when the parent should decide the view’s root style instead: the view is laid out at style, and its content is laid out within the bounds that style produces. See retained rendering.

Methods from Deref<Target = AnyEntity>

pub fn entity_id(&self) -> EntityId

Returns the id of the entity.

pub fn entity_type(&self) -> TypeId

Returns the TypeId of the type the entity was created with.

pub fn downgrade(&self) -> AnyWeakEntity

Returns a type-erased weak handle to the same entity. It doesn’t keep the entity alive.

Trait Implementations

impl<T> Clone for Entity<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Entity<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Deref for Entity<T>

type Target = AnyEntity

The resulting type after dereferencing.

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

Dereferences the value.

impl<T> DerefMut for Entity<T>

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

Mutably dereferences the value.

impl<T> Eq for Entity<T>

impl<V: Focusable> Focusable for Entity<V>

fn focus_handle(&self, cx: &App) -> FocusHandle

Returns the focus handle for this view.

impl<I: ImageCache> From<Entity<I>> for AnyImageCache

fn from(image_cache: Entity<I>) -> Self

Converts to this type from the input type.

impl<T> From<Entity<T>> for AnyEntity

fn from(entity: Entity<T>) -> Self

Converts to this type from the input type.

impl<V: Render> From<Entity<V>> for AnyView

fn from(value: Entity<V>) -> Self

Converts to this type from the input type.

impl<T> Hash for Entity<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: ImageCache> ImageCacheProvider for Entity<T>

fn provide(&mut self, _window: &mut Window, _cx: &mut App) -> AnyImageCache

Returns the cache for the children of an image_cache element.

impl<V: 'static + Render> IntoElement for Entity<V>

type Element = ViewElement<Entity<V>>

The element type that this type converts into.

fn into_element(self) -> Self::Element

Converts self into an Element.

fn into_any_element(self) -> AnyElement

Converts self into an AnyElement, with its concrete type erased.

impl<T: 'static> Ord for Entity<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl<T> PartialEq for Entity<T>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T> PartialEq<Entity<T>> for WeakEntity<T>

fn eq(&self, other: &Entity<T>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T> PartialEq<WeakEntity<T>> for Entity<T>

fn eq(&self, other: &WeakEntity<T>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T: 'static> PartialOrd for Entity<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: UniformListDecoration + 'static> UniformListDecoration for Entity<T>

fn compute( &self, visible_range: Range<usize>, bounds: Bounds<Pixels>, scroll_offset: Point<Pixels>, item_height: Pixels, item_count: usize, window: &mut Window, cx: &mut App, ) -> AnyElement

Returns the element to draw, given the rows in view and the list’s geometry.

impl<T: Render> View for Entity<T>

An entity that renders itself (Render) is a View keyed by its own id.

fn entity_id(&self) -> Option<EntityId>

Returns the entity that identifies this view, or None for a stateless view.

fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement

Renders this view into elements. Takes self by value, so the view is used up.