Struct druid::Env

pub struct Env(_);

An environment passed down through all widget traversals.

All widget methods have access to an environment, and it is passed downwards during traversals.

A widget can retrieve theme parameters (colors, dimensions, etc.). In addition, it can pass custom data down to all descendants. An important example of the latter is setting a value for enabled/disabled status so that an entire subtree can be disabled ("grayed out") with one setting.

EnvScope can be used to override parts of Env for its descendants.

Important

It is the programmer's responsibility to ensure that the environment is used correctly. See Key for an example.

• Keys should be consts with unique names
• Keys must always be set before they are used.
• Values can only be overwritten by values of the same type.

Implementations

impl Env

pub const DEBUG_WIDGET: Key<bool>

A key used to tell widgets to print additional debug information.

This does nothing by default; however you can check this key while debugging a widget to limit println spam.

For convenience, this key can be set with the WidgetExt::debug_widget method.

Examples

if env.get(Env::DEBUG_WIDGET) {
    eprintln!("widget {:?} bounds: {:?}", widget_id, my_rect);
}

pub fn get<V: ValueType>(&self, key: impl Borrow<Key<V>>) -> V

Gets a value from the environment, expecting it to be present.

Note that the return value is a reference for "expensive" types such as strings, but an ordinary value for "cheap" types such as numbers and colors.

Panics

Panics if the key is not found, or if it is present with the wrong type.

pub fn try_get<V: ValueType>(
    &self,
    key: impl Borrow<Key<V>>
) -> Result<V, MissingKeyError>

Trys to get a value from the environment.

If the value is not found, the raw key is returned as the error.

Panics

Panics if the value for the key is found, but has the wrong type.

pub fn get_untyped<V>(&self, key: impl Borrow<Key<V>>) -> &Value

Gets a value from the environment, in its encapsulated Value form, expecting the key to be present.

WARNING: This is not intended for general use, but only for inspecting an Env e.g. for debugging, theme editing, and theme loading.

Panics

Panics if the key is not found.

pub fn try_get_untyped<V>(
    &self,
    key: impl Borrow<Key<V>>
) -> Result<&Value, MissingKeyError>

Gets a value from the environment, in its encapsulated Value form, returning None if a value isn't found.

Note

This is not intended for general use, but only for inspecting an Env e.g. for debugging, theme editing, and theme loading.

pub fn get_all(&self) -> impl ExactSizeIterator<Item = (&ArcStr, &Value)>

Gets the entire contents of the Env, in key-value pairs.

WARNING: This is not intended for general use, but only for inspecting an Env e.g. for debugging, theme editing, and theme loading.

pub fn adding<V: ValueType>(self, key: Key<V>, value: impl Into<V>) -> Env

Adds a key/value, acting like a builder.

pub fn set<V: ValueType>(&mut self, key: Key<V>, value: impl Into<V>)

Sets a value in an environment.

Panics

Panics if the environment already has a value for the key, but it is of a different type.

Trait Implementations

impl Clone for Env

pub fn clone(&self) -> Env

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Data for Env

pub fn same(&self, other: &Env) -> bool

Determine whether two values are the same.

impl Default for Env

pub fn default() -> Self

Returns the "default value" for a type.