Struct dioxus::prelude::ScopeState

pub struct ScopeState { /* fields omitted */ }

Every component in Dioxus is represented by a ScopeState.

Scopes contain the state for hooks, the component’s props, and other lifecycle information.

Scopes are allocated in a generational arena. As components are mounted/unmounted, they will replace slots of dead components. The actual contents of the hooks, though, will be allocated with the standard allocator. These should not allocate as frequently.

We expose the Scope type so downstream users can traverse the Dioxus VirtualDOM for whatever use case they might have.

Implementations

impl ScopeState

pub fn height(&self) -> u32

Get the height of this Scope - IE the number of scopes above it.

A Scope with a height of 0 is the root scope - there are no other scopes above it.

Example

let mut dom = VirtualDom::new(|cx|  cx.render(rsx!{ div {} }));
dom.rebuild();

let base = dom.base_scope();

assert_eq!(base.height(), 0);

pub fn parent(&self) -> Option<ScopeId>

Get the Parent of this Scope within this Dioxus VirtualDOM.

This ID is not unique across Dioxus VirtualDOMs or across time. IDs will be reused when components are unmounted.

The base component will not have a parent, and will return None.

Example

let mut dom = VirtualDom::new(|cx|  cx.render(rsx!{ div {} }));
dom.rebuild();

let base = dom.base_scope();

assert_eq!(base.parent(), None);

pub fn scope_id(&self) -> ScopeId

Get the ID of this Scope within this Dioxus VirtualDOM.

This ID is not unique across Dioxus VirtualDOMs or across time. IDs will be reused when components are unmounted.

Example

let mut dom = VirtualDom::new(|cx|  cx.render(rsx!{ div {} }));
dom.rebuild();
let base = dom.base_scope();

assert_eq!(base.scope_id(), 0);

pub fn schedule_update(&self) -> Rc<dyn Fn() + 'static>

Create a subscription that schedules a future render for the reference component

Notice: you should prefer using prepare_update and get_scope_id

pub fn schedule_update_any(&self) -> Rc<dyn Fn(ScopeId) + 'static>

Schedule an update for any component given its ScopeId.

A component’s ScopeId can be obtained from use_hook or the ScopeState::scope_id method.

This method should be used when you want to schedule an update for a component

pub fn needs_update(&self)

Get the ScopeId of a mounted component.

ScopeId is not unique for the lifetime of the VirtualDom - a ScopeId will be reused if a component is unmounted.

pub fn needs_update_any(&self, id: ScopeId)

Get the ScopeId of a mounted component.

ScopeId is not unique for the lifetime of the VirtualDom - a ScopeId will be reused if a component is unmounted.

pub fn root_node(&self) -> &VNode<'_>

Get the Root Node of this scope

pub fn provide_context<T>(&self, value: T) where
    T: 'static, 

This method enables the ability to expose state to children further down the VirtualDOM Tree.

This is a “fundamental” operation and should only be called during initialization of a hook.

For a hook that provides the same functionality, use use_provide_context and use_consume_context instead.

When the component is dropped, so is the context. Be aware of this behavior when consuming the context via Rc/Weak.

Example

struct SharedState(&'static str);

static App: Component = |cx| {
    cx.use_hook(|_| cx.provide_context(SharedState("world")));
    rsx!(cx, Child {})
}

static Child: Component = |cx| {
    let state = cx.consume_state::<SharedState>();
    rsx!(cx, div { "hello {state.0}" })
}

pub fn consume_context<T>(&self) -> Option<Rc<T>> where
    T: 'static, 

Try to retrieve a SharedState with type T from the any parent Scope.

pub fn push_future(&self, fut: impl Future<Output = ()> + 'static) -> TaskId

Pushes the future onto the poll queue to be polled after the component renders.

The future is forcibly dropped if the component is not ready by the next render

pub fn remove_future(&self, id: TaskId)

pub fn render(&'src self, rsx: LazyNodes<'src, '_>) -> Option<VNode<'src>>

Take a lazy VNode structure and actually build it with the context of the VDom’s efficient VNode allocator.

This function consumes the context and absorb the lifetime, so these VNodes must be returned.

Example

fn Component(cx: Scope<Props>) -> Element {
    // Lazy assemble the VNode tree
    let lazy_nodes = rsx!("hello world");

    // Actually build the tree and allocate it
    cx.render(lazy_tree)
}

pub fn use_hook<State>(
    &'src self,
    initializer: impl FnOnce(usize) -> State
) -> &'src mut State where
    State: 'static, 

Store a value between renders

This is the foundational hook for all other hooks.

• Initializer: closure used to create the initial hook state
• Runner: closure used to output a value every time the hook is used

To “cleanup” the hook, implement Drop on the stored hook value. Whenever the component is dropped, the hook will be dropped as well.

Example

// use_ref is the simplest way of storing a value between renders
fn use_ref<T: 'static>(initial_value: impl FnOnce() -> T) -> &RefCell<T> {
    use_hook(|| Rc::new(RefCell::new(initial_value())))
}