Struct VarEq 

pub struct VarEq<T: VarValue>(pub Var<T>);

Represents a Var<T> as a value inside another variable.

Variable values must implement PartialEq + Debug + Clone + Send + Sync + Any. Variable types implement all of those except PartialEq, this type wraps a variable and adds equality using Var::var_eq.

Variables cannot be be values directly because that breaks the IntoVar<T> blanket implementation for value types, as variables also implement IntoVar<T>. This could be solved with the default impl Rust feature, but it is not yet stable. This type is a workaround that limitation, it derefs to the wrapped var so it should require minimal refactoring as a drop-in replacement for Var<T> in struct fields.

Tuple Fields

0: Var<T>

Methods from Deref<Target = Var<T>>

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

Visit a reference to the current value.

pub fn get(&self) -> T

Get a clone of the current value.

pub fn get_into(&self, value: &mut T)

Get a clone of the current value into value.

This uses Clone::clone_from to reuse the value memory if supported.

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

Visit a reference to the current value if it is_new.

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

Gets a clone of the current value if it is_new.

pub fn get_new_into(&self, value: &mut T) -> bool

Gets a clone of the current value into value if it is_new.

This uses Clone::clone_from to reuse the value memory if supported.

pub fn try_set(&self, new_value: impl Into<T>) -> Result<(), VarIsReadOnlyError>

Schedule new_value to be assigned next update.

pub fn set(&self, new_value: impl Into<T>)

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_modify( &self, modify: impl FnOnce(&mut VarModify<'_, '_, T>) + Send + 'static, ) -> Result<(), VarIsReadOnlyError>

Schedule modify to be called on the value for the next update.

If the VarModify value is deref mut the variable will notify an update.

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

Schedule modify to be called on the value for the next update.

If the VarModify value 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: &Var<T>) -> 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: &Var<T>)

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<O: VarValue>( &self, other: &Var<O>, map: impl FnOnce(&O) -> T + 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<O: VarValue>( &self, other: &Var<O>, map: impl FnOnce(&O) -> T + 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(&VarHookArgs<'_, T>) -> 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(&T) -> 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 = T> + Send + Sync

Awaits for an update them get the value.

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

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

The enter_value closure is called every time the variable updates, it can return an implementation agnostic scope or span S that is only dropped when the variable updates again.

The enter_value is also called immediately when this method is called to start tracking the first value.

Returns a VarHandle that can be used to stop tracing.

If this variable can never update the span is immediately dropped and a dummy handle is returned.

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

Create a read-only mapping variable.

The map closure must produce a mapped value from this variable’s value.

Examples

Basic usage:

let n_var = var(0u32);
let n_10_var = n_var.map(|n| *n * 10);
let txt_var = n_10_var.map(|n| if *n < 100 { formatx!("{n}!") } else { formatx!("Done!") });

In the example above the txt_var will update every time the n_var updates.

Capabilities

If this variable is static the map closure is called immediately and dropped, the mapping variable is also static.

If this variable is a shared reference the map closure is called immediately to init the mapping variable and is called again for every update of this variable. The mapping variable is another shared reference and it holds a strong reference to this variable.

If this variable is contextual the initial map call is deferred until first usage of the mapping variable. The mapping variable is also contextual and will init for every context it is used in.

The mapping variable is read-only, see map_bidi for read-write mapping.

If the map closure produce an equal value the mapping variable will not update, see also filter_map to skip updating for some input values.

pub fn map_into<O>(&self) -> Var<O>

where O: VarValue, T: Into<O>,

Create a map that converts from T to O using Into<O>.

pub fn map_to_txt(&self) -> Var<Txt>

where T: ToTxt,

Create a map that converts from T to Txt using ToTxt.

pub fn map_deref<O>(&self) -> Var<O>

where O: VarValue, T: Deref<Target = O>,

Create a map that references and clones O from T using std::ops::Deref<Target = O>.

The mapping variable is read-only, see map_deref_mut for mutable referencing.

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

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.

Examples

Basic usage:

let n_var = var(100u32);
let txt_var = n_var.filter_map(|n| if *n < 100 { Some(formatx!("{n}!")) } else { None }, || "starting...".into());

In the example above the txt_var will update every time the n_var updates with value n < 100. Because the n_var initial value does not match the filter the fallback value "starting..." is used.

Capabilities

If this variable is static the closures are called immediately and dropped, the mapping variable is also static.

If this variable is a shared reference the closures are called immediately to init the mapping variable and are called again for every update of this variable. The mapping variable is another shared reference and it holds a strong reference to this variable.

If this variable is contextual the initial closures call is deferred until first usage of the mapping variable. The mapping variable is also contextual and will init for every context it is used in.

The mapping variable is read-only, see filter_map_bidi for read-write mapping.

pub fn filter_try_into<O, I>(&self, fallback_init: I) -> Var<O>

where O: VarValue, T: TryInto<O>, I: Fn() -> O + Send + Sync + 'static,

Create a filter_map that tries to convert from T to O using TryInto<O>.

pub fn filter_parse<O, I>(&self, fallback_init: I) -> Var<O>

where O: VarValue + FromStr, T: AsRef<str>, I: Fn() -> O + Send + Sync + 'static,

Create a filter_map that tries to convert from T to O using FromStr.

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

Create a bidirectional mapping variable.

Examples

Basic usage:

let n_var = var(0u32);
let n_100_var = n_var.map_bidi(|n| n * 100, |n_100| n_100 / 100);

In the example above the n_100_var will update every time the n_var updates and the n_var will update every time the n_100_var updates.

Capabilities

If this variable is static the map closure is called immediately and dropped, the mapping variable is also static, the map_back closure is ignored.

If this variable is a shared reference the map closure is called immediately to init the mapping variable. The mapping variable is another shared reference and it holds a strong reference to this variable. The map closure is called again for every update of this variable that is not caused by the mapping variable. The map_back closure is called for every update of the mapping variable that was not caused by this variable.

If this variable is contextual the initial map call is deferred until first usage of the mapping variable. The mapping variable is also contextual and will init for every context it is used in.

pub fn map_bidi_modify<O: VarValue>( &self, map: impl FnMut(&T) -> O + Send + 'static, modify_back: impl FnMut(&O, &mut VarModify<'_, '_, T>) + Send + 'static, ) -> Var<O>

Create a bidirectional mapping variable that modifies back instead of mapping back.

Examples

Basic usage:

let list_var = var(vec!['a', 'b', 'c']);
let first_var = list_var.map_bidi_modify(
    // map:
    |l| l.first().copied().unwrap_or('_'),
    // modify_back:
    |c, l| if l.is_empty() { l.push(*c) } else { l[0] = *c },
);

In the example above the first_var represents the first item on the vector in list_var. Note that the map closure works the same as in map_bidi, but the modify_back closure modifies the list. This is not a mapping that can be declared with map_bidi as the mapping variable does not have the full list to map back.

Capabilities

If this variable is static the map closure is called immediately and dropped, the mapping variable is also static, the modify_back closure is ignored.

If this variable is a shared reference the map closure is called immediately to init the mapping variable. The mapping variable is another shared reference and it holds a strong reference to this variable. The map closure is called again for every update of this variable that is not caused by the mapping variable. The modify_back closure is called for every update of the mapping variable that was not caused by this variable.

If this variable is contextual the initial map call is deferred until first usage of the mapping variable. The mapping variable is also contextual and will init for every context it is used in.

Like other mappings and bindings cyclic updates are avoided automatically, if the modify_back closure touches/updates the value a var instance tag is inserted after the closure returns, you do not need to mark it manually.

pub fn map_into_bidi<O>(&self) -> Var<O>

where O: VarValue + Into<T>, T: Into<O>,

Create a map_bidi that converts between T and O using Into.

pub fn map_deref_mut<O>(&self) -> Var<O>

where O: VarValue, T: Deref<Target = O> + DerefMut<Target = O>,

Create a map_bidi_modify that references and clones O from T using std::ops::Deref<Target = O> and modifies back using std::ops::DerefMut<Target = O>.

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

Create a bidirectional mapping variable that can skip updates.

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

Examples

Basic usage:

let n_var = var(0u32);
let n_100_var = n_var.filter_map_bidi(
    |n| Some(n * 100),
    |n_100| {
        let r = n_100 / 100;
        if r < 100 { Some(r) } else { None }
    },
    || 0,
);

In the example above the n_100_var will update every time the n_var updates with any value and the n_var will update every time the n_100_var updates with a value that (n_100 / 100) < 100.

Capabilities

If this variable is static the map closure is called immediately and dropped, the mapping variable is also static, the map_back closure is ignored.

If this variable is a shared reference the map closure is called immediately to init the mapping variable. The mapping variable is another shared reference and it holds a strong reference to this variable. The map closure is called again for every update of this variable that is not caused by the mapping variable. The map_back closure is called for every update of the mapping variable that was not caused by this variable.

If this variable is contextual the initial map call is deferred until first usage of the mapping variable. The mapping variable is also contextual and will init for every context it is used in.

pub fn filter_try_into_bidi<O, I>(&self, fallback_init: I) -> Var<O>

where O: VarValue + TryInto<T>, T: TryInto<O>, I: Fn() -> O + Send + Sync + 'static,

Create a filter_map_bidi that tries to convert between T to O using TryInto.

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

Create a flat mapping variable that unwraps an inner variable stored in the the value of this variable.

Capabilities

If this variable is static the map closure is called immediately and dropped and the inner variable is returned.

If this variable is a shared reference the map closure is called immediately to init the mapping variable and is called again for every update of this variable. The mapping variable is another shared reference and it holds a strong reference to this variable and to the inner variable.

If this variable is contextual the initial map call is deferred until first usage of the mapping variable. The mapping variable is also contextual and will init for every context it is used in.

The mapping variable has the same capabilities of the inner variable, plus MODIFY_CHANGES. When the inner variable is writeable the return variable is too.

pub fn bind(&self, other: &Var<T>) -> VarHandle

Bind other to receive the new values from this variable.

Examples

Basic usage:

let a = var(10);
let b = var(0);

a.bind(&b).perm();

In the example above the variable b will be set every time the variable a updates. Note that the current value is not propagated, only updates. You can use set_bind to assign the current value and bind.

Capabilities

If this variable is const or the other variable is always read-only does nothing and returns a dummy handle.

If any variable is contextual the binding is set on the current context inner variable.

Neither variable holds the other, only a weak reference is used, if either variable or the handle is dropped the binding is dropped.

pub fn set_bind(&self, other: &Var<T>) -> VarHandle

Like bind but also sets other to the current value.

Basic usage:

let a = var(10);
let b = var(0);

a.set_bind(&b).perm();

In the example above the variable b will be set to the current value of a and every time the variable a updates.

Capabilities

If this variable is const or the other variable is always read-only does nothing and returns a dummy handle.

If any variable is contextual the binding is set on the current context inner variable.

Neither variable holds the other, only a weak reference is used, if either variable or the handle is dropped the binding is dropped.

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

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

This has the same capabilities as bind, but the map closure is called to produce the new value for other.

Examples

Basic usage:

let a = var(10);
let b = var(Txt::from(""));

a.bind_map(&b, |&a| formatx!("{:?}", a * 2)).perm();

In the example above every time the variable a updates the variable b will be set to the text representation of the value times two.

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

Like bind_map but also sets other to the current value.

This has the same capabilities as set_bind, but the map closure is called to produce the new value for other.

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

Bind other to be modified when this variable updates.

This has the same capabilities as bind, but the modify closure is called to modify other using a reference to the new value.

Examples

Basic usage:

let a = var(10);
let b = var(vec![1, 2, 3]);
a.bind_modify(&b, |&a, b| {
    if b.is_empty() {
        b.push(a);
    } else {
        b[0] = a;
    }
})
.perm();

In the example above the variable b first element is set to the updated value of a.

pub fn bind_bidi(&self, other: &Var<T>) -> VarHandles

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

Capabilities

This has the same capabilities as bind, it is equivalent of setting two bindings.

The bindings are protected against cyclic updates, like all other mappings and bindings.

pub fn bind_map_bidi<O: VarValue>( &self, other: &Var<O>, map: impl FnMut(&T) -> O + Send + 'static, map_back: impl FnMut(&O) -> T + Send + 'static, ) -> VarHandles

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

This has the same capabilities as bind_bidi, but the map closure is called to produce the new value for other and map_back is called to produce the new value for this variable.

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

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

This has the same capabilities as bind_bidi, but the modify closure is called to modify other and modify_back is called to modify this variable.

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

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

This has the same capabilities as bind_map, except that other will only receive a new value if map returns a value.

pub fn bind_filter_map_bidi<O: VarValue>( &self, other: &Var<O>, map: impl FnMut(&T) -> Option<O> + Send + 'static, map_back: impl FnMut(&O) -> Option<T> + 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.

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

Schedule a custom animation that targets this variable.

The animate closure is called every frame, starting after next frame, the closure inputs are the Animation args and modify access to the variable value, the args can be used to calculate the new variable value and to control or stop the animation.

Examples

Customs animation that displays the animation elapsed time:

let status = var(Txt::from("not animating"));

status
    .animate(|animation, value| {
        let elapsed = animation.elapsed_dur();
        if elapsed < 5.secs() {
            value.set(formatx!("animating: elapsed {}ms", elapsed.as_millis()));
        } else {
            animation.stop();
            value.set("not animating");
        }
    })
    .perm();

Capabilities

If the variable is always read-only no animation is created and a dummy handle returned.

If this var is contextual the animation targets the current context var.

The animation is stopped if this variable is dropped.

pub fn sequence( &self, animate: impl FnMut(Var<T>) -> 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.

This can be used to create a sequence of animations or to repeat an animation.

Examples

Running multiple animations in sequence:

let status = var(Txt::from("not animating"));

let mut stage = 0;
status
    .sequence(move |status| {
        stage += 1;
        if stage < 5 {
            status.animate(move |animation, value| {
                let elapsed = animation.elapsed_stop(5.secs());
                value.set(formatx!("animation {stage}: {}", elapsed.pct()));
            })
        } else {
            status.set("not animating");
            AnimationHandle::dummy()
        }
    })
    .perm();

Capabilities

The sequence stops when animate returns a dummy handle, or the variable is modified outside of animate, or animations are disabled, or the returned handle is dropped.

pub fn set_ease( &self, start_value: impl Into<T>, end_value: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Schedule an easing transition from the start_value to end_value.

The variable updates every time the EasingStep for each frame changes and a different value is sampled.

Examples

Basic usage:

let progress = var(0.pct());

progress.set_ease(0.pct(), 100.pct(), 5.secs(), easing::linear).perm();

Variable is reset to 0% at the start and them transition to 100% in 5 seconds with linear progression.

Capabilities

See animate for details about animation capabilities.

pub fn set_ease_oci( &self, start_value: impl Into<T>, end_value: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Oscillate between start_value to end_value with an easing transition.

The duration defines the easing duration between the two values. The animation will continue running until the handle or the variable is dropped.

Note that you can use sequence to create more complex looping animations.

pub fn set_ease_with( &self, start_value: impl Into<T>, end_value: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, sampler: impl Fn(&Transition<T>, EasingStep) -> T + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Schedule an easing transition from the start_value to end_value using a custom value sampler.

The variable updates every time the EasingStep for each frame changes and a different value is sampled.

See animate for details about animation capabilities.

pub fn set_ease_oci_with( &self, start_value: impl Into<T>, end_value: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, sampler: impl Fn(&Transition<T>, EasingStep) -> T + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Oscillate between start_value to end_value with an easing transition using a custom value sampler.

The duration defines the easing duration between the two values.

Note that you can use sequence to create more complex looping animations.

pub fn ease( &self, new_value: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Schedule an easing transition from the current value to new_value.

The variable updates every time the EasingStep for each frame changes and a different value is sampled.

See animate for details about animation capabilities.

pub fn ease_oci( &self, new_value: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Oscillate between the current value and new_value with an easing transition.

The duration defines the easing duration between the two values.

Note that you can use sequence to create more complex looping animations.

pub fn ease_with( &self, new_value: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, sampler: impl Fn(&Transition<T>, EasingStep) -> T + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Schedule an easing transition from the current value to new_value using a custom value sampler.

The variable updates every time the EasingStep for each frame changes and a different value is sampled.

See animate for details about animation capabilities.

pub fn ease_oci_with( &self, new_value: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, sampler: impl Fn(&Transition<T>, EasingStep) -> T + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Oscillate between the current value and new_value with an easing transition and a custom value sampler.

The duration defines the easing duration between the two values.

Note that you can use sequence to create more complex looping animations.

pub fn set_ease_keyed( &self, keys: Vec<(Factor, T)>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Schedule a keyframed transition animation for the variable, starting from the first key.

The variable will be set to the first keyframe, then animated across all other keys.

See animate for details about animations.

pub fn set_ease_keyed_with( &self, keys: Vec<(Factor, T)>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, sampler: impl Fn(&TransitionKeyed<T>, EasingStep) -> T + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Schedule a keyframed transition animation for the variable, starting from the first key, using a custom value sampler.

The variable will be set to the first keyframe, then animated across all other keys.

See animate for details about animations.

pub fn ease_keyed( &self, keys: Vec<(Factor, T)>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Schedule a keyframed transition animation for the variable, starting from the current value.

The variable will be set to the first keyframe, then animated across all other keys.

See animate for details about animations.

pub fn ease_keyed_with( &self, keys: Vec<(Factor, T)>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, sampler: impl Fn(&TransitionKeyed<T>, EasingStep) -> T + Send + 'static, ) -> AnimationHandle

where T: Transitionable,

Schedule a keyframed transition animation for the variable, starting from the current value, using a custom value sampler.

The variable will be set to the first keyframe, then animated across all other keys.

See animate for details about animations.

pub fn step(&self, new_value: impl Into<T>, delay: Duration) -> AnimationHandle

Set the variable to new_value after a delay.

The variable is_animating until the delay elapses and the value is set.

See animate for details about animations.

pub fn step_oci( &self, new_value: impl Into<T>, delay: Duration, ) -> AnimationHandle

Oscillate between the current value and new_value, every time the delay elapses the variable is set to the next value.

pub fn set_step_oci( &self, from: impl Into<T>, to: impl Into<T>, delay: Duration, ) -> AnimationHandle

Oscillate between from and to, the variable is set to from to start and every time the delay elapses the variable is set to the next value.

pub fn steps( &self, steps: Vec<(Factor, T)>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, ) -> AnimationHandle

Set the variable to a sequence of values as a time duration elapses.

An animation curve is used to find the first factor in steps above or at the curve line at the current time, the variable is set to this step value, continuing animating across the next steps until the last or the animation end. The variable is_animating from the start, even if no step applies and stays animating until the last step applies or the duration is reached.

Examples

Creates a variable that outputs text every 5% of a 5 seconds animation, advanced linearly.

let steps = (0..=100).step_by(5).map(|i| (i.pct().fct(), formatx!("{i}%"))).collect();
text_var.steps(steps, 5.secs(), easing::linear)

The variable is set to "0%", after 5% of the duration elapses it is set to "5%" and so on until the value is set to "100% at the end of the animation.

Returns an AnimationHandle. See Var::animate for details about animations.

pub fn chase( &self, first_target: impl Into<T>, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + 'static, ) -> ChaseAnimation<T>

where T: Transitionable,

Starts an easing animation that chases a target value that can be changed using the ChaseAnimation<T> handle.

pub fn chase_begin(&self) -> ChaseAnimation<T>

where T: Transitionable,

Start a chase animation without a first target.

Use ChaseAnimation<T>::set to set the first chase target.

pub fn easing( &self, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + Sync + 'static, ) -> Var<T>

where T: Transitionable,

Create a vars that ease to each new value of self.

Note that the mapping var can be contextualized, see map for more details.

If self can change the output variable will keep it alive.

pub fn easing_with( &self, duration: Duration, easing: impl Fn(EasingTime) -> EasingStep + Send + Sync + 'static, sampler: impl Fn(&Transition<T>, EasingStep) -> T + Send + Sync + 'static, ) -> Var<T>

where T: Transitionable,

Create a vars that ease_with to each new value of self.

Note that the mapping var can be contextualized, see map for more details. If self is shared the output variable will hold a strong reference to it.

pub fn as_any(&self) -> &AnyVar

Reference the variable without the strong value type.

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

Create a weak reference to this variable.

pub fn read_only(&self) -> Var<T>

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) -> Var<T>

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 current_context(&self) -> Var<T>

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.

pub fn var_eq(&self, other: &Self) -> 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.

Methods from Deref<Target = AnyVar>

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.

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.

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.

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.

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.

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<T: Clone + VarValue> Clone for VarEq<T>

fn clone(&self) -> VarEq<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: VarValue> Debug for VarEq<T>

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

Formats the value using the given formatter.

impl<T: VarValue> Deref for VarEq<T>

type Target = Var<T>

The resulting type after dereferencing.

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

Dereferences the value.

impl<T: VarValue> PartialEq for VarEq<T>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.