Struct AnyVar 

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

Variable of any type.

Implementations

impl AnyVar

Value.

pub fn with<O>(&self, visitor: impl FnOnce(&dyn AnyVarValue) -> O) -> O

Visit a reference to the current value.

pub fn get(&self) -> BoxAnyVarValue

Get a clone of the current value.

pub fn get_debug(&self, alternate: bool) -> Txt

Debug format the current value.

pub fn is_new(&self) -> bool

Gets if the value updated.

Returns true if the last_update is the current one. Note that this will only work reliably in UI code that is synchronized with app updates, prefer wait_update in async code.

pub fn get_new(&self) -> Option<BoxAnyVarValue>

Gets a clone of the current value if it is_new.

pub fn with_new<O>( &self, visitor: impl FnOnce(&dyn AnyVarValue) -> O, ) -> Option<O>

Visit a reference to the current value if it is_new.

pub fn try_set( &self, new_value: BoxAnyVarValue, ) -> Result<(), VarIsReadOnlyError>

Schedule new_value to be assigned next update, if the variable is not read-only.

Panics if the value type does not match.

pub fn set(&self, new_value: BoxAnyVarValue)

Schedule new_value to be assigned next update.

If the variable is read-only this is ignored and a DEBUG level log is recorded. Use try_set to get an error for read-only vars.

pub fn try_update(&self) -> Result<(), VarIsReadOnlyError>

Schedule an update notification, without actually changing the value, if the variable is not read-only.

pub fn update(&self)

Show variable value as new next update, without actually changing the value.

If the variable is read-only this is ignored and a DEBUG level log is recorded. Use try_update to get an error for read-only vars.

pub fn try_modify( &self, modify: impl FnOnce(&mut AnyVarModify<'_>) + Send + 'static, ) -> Result<(), VarIsReadOnlyError>

Schedule modify to be called on the value for the next update, if the variable is not read-only.

If the AnyVarModify closure input is deref_mut the variable will notify an update.

pub fn modify( &self, modify: impl FnOnce(&mut AnyVarModify<'_>) + Send + 'static, )

Schedule modify to be called on the value for the next update, if the variable is not read-only.

If the AnyVarModify closure input is deref_mut the variable will notify an update.

If the variable is read-only this is ignored and a DEBUG level log is recorded. Use try_modify to get an error for read-only vars.

pub fn try_set_from(&self, other: &AnyVar) -> Result<(), VarIsReadOnlyError>

Schedule a new value for the variable, it will be set in the end of the current app update to the updated value of other, so if the other var has already scheduled an update, the updated value will be used.

This can be used just before creating a binding to start with synchronized values.

pub fn set_from(&self, other: &AnyVar)

Schedule a new value for the variable, it will be set in the end of the current app update to the updated value of other, so if the other var has already scheduled an update, the updated value will be used.

This can be used just before creating a binding to start with synchronized values.

If the variable is read-only this is ignored and a DEBUG level log is recorded. Use try_set_from to get an error for read-only vars.

pub fn try_set_from_map( &self, other: &AnyVar, map: impl FnOnce(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, ) -> Result<(), VarIsReadOnlyError>

Like try_set_from, but uses map to produce the new value from the updated value of other.

pub fn set_from_map( &self, other: &AnyVar, map: impl FnOnce(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, )

Like set_from, but uses map to produce the new value from the updated value of other.

If the variable is read-only this is ignored and a DEBUG level log is recorded. Use try_set_from_map to get an error for read-only vars.

pub fn hook( &self, on_update: impl FnMut(&AnyVarHookArgs<'_>) -> bool + Send + 'static, ) -> VarHandle

Setups a callback for just after the variable value update is applied, the closure runs in the root app context, just like the modify closure. The closure must return true to be retained and false to be dropped.

If you modify another variable in the closure modification applies in the same update, variable mapping and binding is implemented using hooks.

The variable store a weak reference to the callback if it has the MODIFY or CAPS_CHANGE capabilities, otherwise the callback is discarded and VarHandle::dummy returned.

pub fn wait_match( &self, predicate: impl Fn(&dyn AnyVarValue) -> bool + Send + Sync, ) -> impl Future<Output = ()> + Send + Sync

Awaits for a value that passes the predicate, including the current value.

pub fn wait_next(&self) -> impl Future<Output = BoxAnyVarValue> + Send + Sync

Awaits for an update them get the value.

pub fn last_update(&self) -> VarUpdateId

Last update ID a variable was modified.

If the ID equals VARS.update_id the variable is_new.

pub fn wait_update(&self) -> impl Future<Output = VarUpdateId> + Send + Sync

Awaits for the last_update to change.

Note that is_new will be true when the future elapses only when polled in sync with the UI, but it will elapse in any thread when the variable updates after the future is instantiated.

Note that outside of the UI tree there is no variable synchronization across multiple var method calls, so a sequence of get(); wait_update().await; get(); can miss a value between get and wait_update. The returned future captures the last_update at the moment this method is called, this can be leveraged by double-checking to avoid race conditions, see the wait_match default implementation for more details.

pub fn trace_value<S: Send + 'static>( &self, enter_value: impl FnMut(&AnyVarHookArgs<'_>) -> S + Send + 'static, ) -> VarHandle

Debug helper for tracing the lifetime of a value in this variable.

See trace_value for more details.

impl AnyVar

Value mapping.

pub fn map_any( &self, map: impl FnMut(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, value_type: TypeId, ) -> AnyVar

Create a mapping variable from any to any.

The map closure must only output values of value_type, this type is validated in debug builds and is necessary for contextualizing variables.

See map for more details about mapping variables.

pub fn map<O: VarValue>( &self, map: impl FnMut(&dyn AnyVarValue) -> O + Send + 'static, ) -> Var<O>

Create a strongly typed mapping variable.

The map closure must produce a strongly typed value for every update of this variable.

See map for more details about mapping variables.

pub fn map_debug(&self, alternate: bool) -> Var<Txt>

Create a mapping variable that contains the debug formatted value from this variable.

See map for more details about mapping variables.

pub fn filter_map_any( &self, map: impl FnMut(&dyn AnyVarValue) -> Option<BoxAnyVarValue> + Send + 'static, fallback_init: impl Fn() -> BoxAnyVarValue + Send + 'static, value_type: TypeId, ) -> AnyVar

Create a mapping variable that can skip updates.

The map closure is called for every update this variable and if it returns a new value the mapping variable updates.

If the map closure does not produce a value on init the fallback_init closure is called.

See filter_map for more details about mapping variables.

pub fn filter_map<O: VarValue>( &self, map: impl FnMut(&dyn AnyVarValue) -> Option<O> + Send + 'static, fallback_init: impl Fn() -> O + Send + 'static, ) -> Var<O>

Create a strongly typed mapping variable that can skip updates.

The map closure is called for every update this variable and if it returns a new value the mapping variable updates.

If the map closure does not produce a value on init the fallback_init closure is called.

See filter_map for more details about mapping variables.

pub fn map_bidi_any( &self, map: impl FnMut(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, map_back: impl FnMut(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, value_type: TypeId, ) -> AnyVar

Create a bidirectional mapping variable.

The map closure must only output values of value_type, predefining this type is is necessary for contextualizing variables.

The map_back closure must produce values of the same type as this variable, this variable will panic if map back value is not the same.

See map_bidi for more details about bidirectional mapping variables.

pub fn map_bidi_modify_any( &self, map: impl FnMut(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, modify_back: impl FnMut(&dyn AnyVarValue, &mut AnyVarModify<'_>) + Send + 'static, value_type: TypeId, ) -> AnyVar

Create a bidirectional mapping variable that modifies the source variable on change, instead of mapping back.

The map closure must only output values of value_type, predefining this type is is necessary for contextualizing variables.

The modify_back closure is called to modify the source variable with the new output value.

See map_bidi_modify for more details about bidirectional mapping variables.

pub fn filter_map_bidi_any( &self, map: impl FnMut(&dyn AnyVarValue) -> Option<BoxAnyVarValue> + Send + 'static, map_back: impl FnMut(&dyn AnyVarValue) -> Option<BoxAnyVarValue> + Send + 'static, fallback_init: impl Fn() -> BoxAnyVarValue + Send + 'static, value_type: TypeId, ) -> AnyVar

Create a bidirectional mapping variable that can skip updates.

The map closure must only output values of value_type, predefining this type is is necessary for contextualizing variables.

The map_back closure must produce values of the same type as this variable, this variable will panic if map back value is not the same.

See filter_map_bidi for more details about bidirectional mapping variables.

pub fn flat_map_any( &self, map: impl FnMut(&dyn AnyVarValue) -> AnyVar + Send + 'static, value_type: TypeId, ) -> AnyVar

Create a mapping variable from any to any that unwraps an inner variable.

See flat_map for more details about flat mapping variables.

pub fn flat_map<O: VarValue>( &self, map: impl FnMut(&dyn AnyVarValue) -> Var<O> + Send + 'static, ) -> Var<O>

Create a strongly typed flat mapping variable.

See flat_map for more details about mapping variables.

impl AnyVar

Binding

pub fn bind(&self, other: &AnyVar) -> VarHandle

Bind other to receive the new values from this variable.

See bind for more details about variable bindings.

pub fn set_bind(&self, other: &AnyVar) -> VarHandle

Like bind but also sets other to the current value.

See set_bind for more details.

pub fn bind_map_any( &self, other: &AnyVar, map: impl FnMut(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, ) -> VarHandle

Bind other to receive the new values mapped from this variable.

See bind_map for more details about variable bindings.

pub fn bind_modify_any( &self, other: &AnyVar, modify: impl FnMut(&dyn AnyVarValue, &mut AnyVarModify<'_>) + Send + 'static, ) -> VarHandle

Bind other to be modified when this variable updates.

See bind_modify for more details about modify bindings.

pub fn set_bind_map_any( &self, other: &AnyVar, map: impl FnMut(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, ) -> VarHandle

Like bind_map_any but also sets other to the current value.

See set_bind_map for more details.

pub fn bind_map<O: VarValue>( &self, other: &Var<O>, map: impl FnMut(&dyn AnyVarValue) -> O + Send + 'static, ) -> VarHandle

Bind strongly typed other to receive the new values mapped from this variable.

See bind_map for more details about variable bindings.

pub fn bind_modify<O: VarValue>( &self, other: &Var<O>, modify: impl FnMut(&dyn AnyVarValue, &mut VarModify<'_, '_, O>) + Send + 'static, ) -> VarHandle

Bind other to be modified when this variable updates.

See bind_modify for more details about modify bindings.

pub fn set_bind_map<O: VarValue>( &self, other: &Var<O>, map: impl FnMut(&dyn AnyVarValue) -> O + Send + 'static, ) -> VarHandle

Like bind_map_any but also sets other to the current value.

See set_bind_map for more details.

pub fn bind_bidi(&self, other: &AnyVar) -> VarHandles

Bind other to receive the new values from this variable and this variable to receive new values from other.

See bind_bidi for more details about variable bindings.

pub fn bind_map_bidi_any( &self, other: &AnyVar, map: impl FnMut(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, map_back: impl FnMut(&dyn AnyVarValue) -> BoxAnyVarValue + Send + 'static, ) -> VarHandles

Bind other to receive the new mapped values from this variable and this variable to receive new mapped values from other.

See bind_bidi for more details about variable bindings.

pub fn bind_modify_bidi_any( &self, other: &AnyVar, modify: impl FnMut(&dyn AnyVarValue, &mut AnyVarModify<'_>) + Send + 'static, modify_back: impl FnMut(&dyn AnyVarValue, &mut AnyVarModify<'_>) + Send + 'static, ) -> VarHandles

Bind other to be modified when this variable updates and this variable to be modified when other updates.

See bind_modify_bidi for more details about modify bindings.

pub fn bind_modify_bidi<O: VarValue>( &self, other: &Var<O>, modify: impl FnMut(&dyn AnyVarValue, &mut VarModify<'_, '_, O>) + Send + 'static, modify_back: impl FnMut(&O, &mut AnyVarModify<'_>) + Send + 'static, ) -> VarHandles

Bind other to be modified when this variable updates and this variable to be modified when other updates.

See bind_modify_bidi for more details about modify bindings.

pub fn bind_filter_map_any( &self, other: &AnyVar, map: impl FnMut(&dyn AnyVarValue) -> Option<BoxAnyVarValue> + Send + 'static, ) -> VarHandle

Bind other to receive the new values filtered mapped from this variable.

See bind_filter_map for more details about variable bindings.

pub fn bind_filter_map<O: VarValue>( &self, other: &AnyVar, map: impl FnMut(&dyn AnyVarValue) -> Option<O> + Send + 'static, ) -> VarHandle

Bind strongly typed other to receive the new values filtered mapped from this variable.

See bind_filter_map for more details about variable bindings.

pub fn bind_filter_map_bidi_any( &self, other: &AnyVar, map: impl FnMut(&dyn AnyVarValue) -> Option<BoxAnyVarValue> + Send + 'static, map_back: impl FnMut(&dyn AnyVarValue) -> Option<BoxAnyVarValue> + Send + 'static, ) -> VarHandles

Bind other to receive the new filtered mapped values from this variable and this variable to receive new filtered mapped values from other.

See bind_filter_map_bidi for more details about variable bindings.

impl AnyVar

Animation

pub fn animate( &self, animate: impl FnMut(&Animation, &mut AnyVarModify<'_>) + Send + 'static, ) -> AnimationHandle

Schedule an animation that targets this variable.

See animate for more details.

pub fn sequence( &self, animate: impl FnMut(AnyVar) -> AnimationHandle + Send + 'static, ) -> VarHandle

Schedule animations started by animate, the closure is called once at the start to begin, then again every time the variable stops animating.

See sequence for more details.

pub fn is_animating(&self) -> bool

If the variable current value was set by an active animation.

The variable is_new when this changes to true, but it may not be new when the value changes to false. If the variable is not updated at the last frame of the animation that has last set it, it will not update just because that animation has ended. You can use hook_animation_stop to get a notification when the last animation stops, or use wait_animation to get a future that is ready when is_animating changes from true to false.

pub fn modify_importance(&self) -> usize

Gets the minimum importance clearance that is needed to modify this variable.

Direct modify/set requests always apply, but requests made from inside an animation only apply if the animation importance is greater or equal this value.This is the mechanism that ensures that only the latest animation has control of the variable value.

pub fn hook_animation_stop( &self, handler: impl FnOnce() + Send + 'static, ) -> VarHandle

Register a handler to be called when the current animation stops.

Note that the handler is owned by the animation, not the variable, it will only be called/dropped when the animation stops.

Returns the VarHandle::is_dummy if the variable is not animating. Note that if you are interacting with the variable from a non-UI thread the variable can stops animating between checking is_animating and registering the hook, in this case the dummy is returned as well.

pub fn wait_animation(&self) -> impl Future<Output = ()> + Send + Sync

Awaits for is_animating to change from true to false.

If the variable is not animating at the moment of this call the future will await until the animation starts and stops.

impl AnyVar

Value type.

pub fn downcast<T: VarValue>(self) -> Result<Var<T>, AnyVar>

Returns the strongly typed variable, if its of of value type T.

pub fn downcast_or<T: VarValue, F: Into<Var<T>>>( self, fallback_var: impl FnOnce(AnyVar) -> F, ) -> Var<T>

Returns downcast or fallback_var.

pub fn value_type(&self) -> TypeId

Gets the value type.

pub fn value_type_name(&self) -> &'static str

Gets the value type name.

Note that this string is not stable and should be used for debug only.

pub fn value_is<T: VarValue>(&self) -> bool

Gets if the value type is T.

impl AnyVar

Variable type.

pub fn capabilities(&self) -> VarCapability

Flags that indicate what operations the variable is capable of in this update.

pub fn strong_count(&self) -> usize

Current count of strong references to this variable.

If this variable is SHARE cloning the variable only clones a reference to the variable. If this variable is local this is always 1 as it clones the value.

pub fn downgrade(&self) -> WeakAnyVar

Create a weak reference to this variable.

If this variable is SHARE returns a weak reference to the variable that can be upgraded to the variable it it is still alive. If this variable is local returns a dummy weak reference that cannot upgrade.

pub fn var_eq(&self, other: &AnyVar) -> bool

Gets if this variable is the same as other.

If this variable is SHARE compares the pointer. If this variable is local this is always false.

pub fn var_instance_tag(&self) -> VarInstanceTag

Copy ID that identifies this variable instance.

The ID is only unique if this variable is SHARE and only while the variable is alive. This can be used with VarModify::push_tag and AnyVarHookArgs::contains_tag to avoid cyclic updates in custom bidirectional bindings.

pub fn read_only(&self) -> AnyVar

Gets a clone of the var that is always read-only.

The returned variable can still update if self is modified, but it does not have the MODIFY capability.

pub fn cow(&self) -> AnyVar

Create a var that redirects to this variable until the first value update, then it disconnects as a separate variable.

The return variable is clone-on-write and has the MODIFY capability independent of the source capabilities, when a modify request is made the source value is cloned and offered for modification, if modified the source variable is dropped, if the modify closure does not update the source variable is retained.

pub fn perm(&self)

Hold the variable in memory until the app exit.

Note that this is different from std::mem::forget, if the app is compiled with "multi_app" feature the variable will be dropped before the new app instance in the same process.

pub fn hold(&self, thing: impl Any + Send) -> VarHandle

Hold arbitrary thing for the lifetime of this variable or the return handle.

pub fn current_context(&self) -> AnyVar

Gets the underlying var in the current calling context.

If this variable is CONTEXT returns a clone of the inner variable, otherwise returns a clone of this variable.

Trait Implementations

impl Clone for AnyVar

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AnyVar

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

Formats the value using the given formatter.

impl<T: VarValue> From<ContextVar<T>> for AnyVar

fn from(v: ContextVar<T>) -> Self

Converts to this type from the input type.

impl<T: VarValue> From<ResponderVar<T>> for AnyVar

fn from(var: ResponderVar<T>) -> Self

Converts to this type from the input type.

impl<T: VarValue> From<ResponseVar<T>> for AnyVar

fn from(var: ResponseVar<T>) -> Self

Converts to this type from the input type.

impl<T: VarValue> From<Var<T>> for AnyVar

fn from(var: Var<T>) -> Self

Converts to this type from the input type.

impl<T: VarValue> TryFrom<AnyVar> for Var<T>

type Error = AnyVar

The type returned in the event of a conversion error.

fn try_from(var: AnyVar) -> Result<Self, Self::Error>

Performs the conversion.