Struct ambient_element::Hooks

pub struct Hooks<'a> { /* private fields */ }

Hooks are a way to hook into the state and lifecycle of an Element.

They are inspired by React hooks.

Using hooks, you can store state, interact with the world, and generally do operations that go beyond the pure rendering of an Element.

Implementations

impl<'a> Hooks<'a>

pub fn use_state<T: Clone + Debug + Send + 'static>( &mut self, init: T ) -> (T, Setter<T>)

Preserve state between rerenders.

The state can be mutated by the setter, which will re-render the origin Element.

Note: The new value set by the returned setter won’t be visible until the next re-render.

let (value, setter) = hooks.use_state(5);

setter(7);

println!("{value}"); // Prints 5

pub fn use_state_with<T: Clone + Debug + Send + 'static, F: FnOnce(&mut World) -> T>( &mut self, init: F ) -> (T, Setter<T>)

The same as Hooks::use_state, but with a function that returns the initial value.

This can be used to avoid cloning the initial value each time the Element is re-rendered.

pub fn use_rerender_signal(&mut self) -> Cb<dyn Fn() + Sync + Send>

Provides a function that, when called, will cause this Element to be re-rendered.

pub fn provide_context<T: Clone + Debug + Send + Sync + 'static>( &mut self, default_value: impl FnOnce() -> T ) -> Setter<T>

Provide a value which is accessible to all children further down the tree.

Note: This hook does not rely on order, and is therefore safe to use inside conditionals.

pub fn consume_context<T: Clone + Debug + Sync + Send + 'static>( &mut self ) -> Option<(T, Setter<T>)>

Consume a context of type T provided further up the tree.

To provide context, use Self::provide_context.

pub fn use_spawn<F: FnOnce(&mut World) -> R + Sync + Send + 'static, R: FnOnce(&mut World) + Sync + Send + 'static>( &mut self, func: F )

Execute a function when the Element is mounted/rendered for the first time.

The function should return another function; that function will be called when the Element is unmounted.

pub fn use_runtime_message<T: RuntimeMessage>( &mut self, func: impl Fn(&mut World, &T) + Sync + Send + 'static )

Register a function to be called when a [RuntimeMessage] is received.

The subscription will be automatically cancelled when this Element is unmounted.

pub fn use_task<Fut: Future<Output = ()> + Send + 'static>( &mut self, task: impl FnOnce(&mut World) -> Fut + Send + Sync + 'static )

Spawns the provided future as a task.

The task is aborted when this Element is removed.

pub fn use_async<T, U>( &mut self, future: impl FnOnce(&mut World) -> T + Send + Sync + 'static ) -> Option<U>where T: Future<Output = U> + Send + 'static, U: Debug + ComponentValue,

Use a value provided by a future.

Returns None until the future completes.

Automatically triggers a re-render on this Element when the future completes.

pub fn use_memo_async<T, F, D, U>(&mut self, deps: D, init: F) -> Option<T>where F: FnOnce(&mut World, D) -> U, U: 'static + Future<Output = T> + Send, T: ComponentValue, D: PartialEq + ComponentValue,

Use memoized state dependent on a future

pub fn use_frame<F: Fn(&mut World) + Sync + Send + 'static>( &mut self, on_frame: F )

Executes a function each frame.

pub fn use_ref_with<T: Send + Debug + 'static>( &mut self, init: impl FnOnce(&mut World) -> T ) -> Arc<Mutex<T>>

Provides internally mutable state that is preserved between re-renders.

This should be used over Self::use_state when reference semantics are required for the state as opposed to value semantics.

Note: Locking the mutex and modifying the value won’t cause a re-render. To re-render the element, use Self::use_rerender_signal.

pub fn use_memo_with<T: Clone + ComponentValue + Debug + Sync + Send + 'static, D: PartialEq + Clone + Sync + Send + Debug + 'static>( &mut self, dependencies: D, compute: impl FnOnce(&mut World, &D) -> T ) -> T

A computation that runs once on spawn, and when dependencies change. The computation is not re-run if the dependencies are the same - that is, the computation is memoized.

Note: using external captures for the create function will not cause the memoized value to be recalculated when the captures change.

Prefer to route as much as possible through the dependencies; these dependencies are available as arguments to compute.

pub fn use_effect<D: PartialEq + Debug + Sync + Send + 'static, R: FnOnce(&mut World) + Sync + Send + 'static>( &mut self, dependencies: D, run: impl FnOnce(&mut World, &D) -> R + Sync + Send )

Run a function for its side effects each time a dependency changes.

The function should return another function; that function will be called when the Element is unmounted.

pub fn use_system<'b, R: ComponentQuery<'b> + Clone + 'static, F: Fn(&TypedReadQuery<R>, &mut World, Option<&mut QueryState>, &FrameEvent) + Send + Sync + 'static>( &mut self, query: TypedReadQuery<R>, run: F )

Run a native system each frame

pub fn use_interval<F: Fn() + Sync + Send + 'static>( &mut self, seconds: f32, cb: F )

Run cb every seconds seconds.

If your cb depends on some state, consider using Self::use_interval_deps instead. This function will capture the state at the time it is called, and will not update if the state changes.

pub fn use_interval_deps<D>( &mut self, duration: Duration, run_immediately: bool, dependencies: D, func: impl 'static + Send + Sync + FnMut(&D) )where D: 'static + Send + Sync + Clone + Debug + PartialEq,

Run cb every duration, passing in the current value of dependencies.

This should be used when the callback depends on some value that can change over time.

pub fn instance_id(&self) -> &str

Instance ID is a unique ID for this instance of the component. It is used to identify the component for updates. It is not the same as the entity ID.