Why there are so many state methods?

[ansarizafar]

There are so many methods for creating state and no information is available about their use

       use_shared_state(key)
        use_shared_state_with(key, initial)
  
  // Methods on WindowedContext
      ctx.use_signal(initial)
        ctx.use_signal_keyed(key, init)
        
        ctx.use_state(initial)
        ctx.use_state_for(key, initial)
        ctx.use_state_keyed(key, init)

Blinc_cn is using use_state without context

  //https://github.com/project-blinc/Blinc/blob/0181dd9eb0d12a6a0b84d2f4c9f7d986108b6d3c/docs/book/src/cn/dialog.md?plain=1#L11
        let is_open = use_state(false);

we also have

            BlincContextState::get().update(count, |v| v - 1);

and #[state] macro
I am really confused where to use which method. Please help me understand.

[darmie]

Have you checked the Blinc Book chapter on State Management yet?

https://project-blinc.github.io/Blinc/core/state.html

[ansarizafar]

Yes I have read the whole book and skill.md and I am able to build a counter app.

There is no info about use_shared_state(key), use_shared_state_with(key, initial), ctx.use_signal(initial), ctx.use_signal_keyed(key, init), ctx.use_state(initial), ctx.use_state_for(key, initial) and how blinc_cn is using use_state() without a context.

BlincContextState::get().update(count, |v| v - 1) is not accepting a signal created with ctx.use_state_keyed(key, init)

Stateful is not working with signal created with let count2 = ctx.use_signal_keyed("count2", || 0i32);

state has a method state.signal_id() where as signal has signal.id(). API should be consistent.

How can we update state/UI from a tokio task in button on_click closure?
Why do we need to create a state for button let inc_btn = ctx.use_state_for("inc_btn", ButtonState::Idle); why not button has a default state?

It seems a lot has changed since the book was first written.

[darmie]

@ansarizafar Please join the newly created Discord server, and repost your query in the #help channel. So that it's easier to follow up. https://discord.gg/NPRzChSm

[ansarizafar]

Ok. I have joined Blinc Discord server.

[darmie]

I already provided a robust response below, mark as answer if it's sufficient. If not, please recreate this query in the help channel on Discord. Cheers!

[darmie]

You would mostly want to use use_state_keyed to create stable states that survives UI rebuild (which happens during window resizing or any internal call to rebuild the UI layout), because the layout tree would generate new IDs for layout elements at build time. The key provided in use_state_keyed is a stable key.

Now to answer your question, the 10 methods you listed are constructors for two underlying types, called from different places:

• State<T> / Signal<T> — plain reactive values (counts, flags, form fields).
• SharedState<S> — FSM widget state for types implementing StateTransitions (ButtonState, CheckboxState, your own enums).

Plain reactive values

Inside build_ui, with ctx (the most common case):

let count = ctx.use_state_keyed("count", || 0i32);
button("inc").on_click(move |_| count.set(count.get() + 1))

Inside reusable widget code, no ctx (free function, same persistence):

use blinc_core::use_state_keyed;

let page = use_state_keyed("pagination_page", || 1usize);

The free function delegates to a process-global BlincContextState. Same call, just spelled differently for where you are.

Inside Blinc widget internals (you'll see this all over blinc_cn):

let handle = BlincContextState::get().use_state_keyed(&self.key.derive("handle"), || None);

Same call as the free function, just spelled out.

For mutating an existing Signal<T> from anywhere:

BlincContextState::get().update(count, |v| v - 1);

Most app code uses state.set(...) on a State<T> it already holds and never touches this.

Avoid these unless you really mean it:

let count = ctx.use_signal(0);             // creates a new signal every build_ui call
let count = ctx.use_signal_keyed("c", || 0); // same as use_state_keyed but lower level

ctx.use_signal(initial) does NOT survive rebuilds. Pick ctx.use_state_keyed first; reach for use_signal / use_signal_keyed only when you need a raw Signal<T> to wire into reactive APIs that take one.

FSM widget state (SharedState<S>)

The current convention: create the stateful container with the type parameter and let it manage its own state internally. The on_state callback receives a StateContext that exposes the current state, per-stateful signals, the triggering event (if any), and animation hooks.

use blinc_layout::stateful::{stateful, ButtonState};

stateful::<ButtonState>()
    .initial(ButtonState::Idle)
    .on_state(|ctx| {
        let bg = match ctx.state() {
            ButtonState::Hovered => Color::RED,
            ButtonState::Pressed => Color::DARK_RED,
            _                    => Color::BLUE,
        };
        div().bg(bg).rounded(8.0).child(text("Click me"))
    })

Inside the callback you also get:

.on_state(|ctx| {
    let toggled = ctx.use_signal("toggled", || false);   // per-stateful persisted signal
    if let Some(event) = ctx.event() { /* react to it */ }
    let scale = ctx.use_spring("scale", 1.0, SpringConfig::wobbly());
    div().transform(Transform::scale(scale.get(), scale.get()))
})

The remaining four constructors materialize a SharedState<S> you can hand to other APIs (lower-level Stateful::with_shared_state, or for sharing a single FSM across multiple containers). For typical widget code you don't need them — stateful::<S>().initial(...).on_state(...) is the path:

// Single call site, key auto-derived from #[track_caller]:
let handle = ctx.use_state(ButtonState::Idle);

// In a loop, with explicit per-instance key:
for item in items {
    let handle = ctx.use_state_for(item.id, ButtonState::Idle);
}

// No ctx, default initial:
use blinc_layout::stateful::use_shared_state;
let handle = use_shared_state::<ButtonState>("submit_button");

// No ctx, custom initial:
use blinc_layout::stateful::use_shared_state_with;
let handle = use_shared_state_with::<ButtonState>("disabled_btn", ButtonState::Disabled);

#[derive(BlincComponent)]

Generates typed accessors backed by use_state_keyed / use_animated_value_keyed, so you get compile-time-checked names instead of stringly-typed keys:

#[derive(BlincComponent)]
pub struct Counter {
    count: i32,
    #[animation]
    scale: f32,
}

let count = Counter::use_count(ctx, 0);                          // State<i32>
let scale = Counter::use_scale(ctx, 1.0, SpringConfig::wobbly()); // SharedAnimatedValue

Each field generates use_<field> (single instance), use_<field>_for(key, ...) for loops, and use_<field>_auto(...) with #[track_caller].

Decision rule

Plain value (count, flag, form field):
    have ctx?                   -> ctx.use_state_keyed("name", || initial)
    no ctx?                     -> use_state_keyed("name", || initial)
    inside .on_state callback   -> ctx.use_signal("name", || initial)

Widget interaction state (button hover, checkbox checked):
    typical use                 -> stateful::<ButtonState>()
                                       .initial(ButtonState::Idle)
                                       .on_state(|ctx| { ... ctx.state() ... })
    advanced (manual handle):
        have ctx, single site   -> ctx.use_state(initial)
        have ctx, in a loop     -> ctx.use_state_for(key, initial)
        no ctx                  -> use_shared_state(key) or use_shared_state_with(key, initial)

Multiple fields on one component:
    #[derive(BlincComponent)] + Foo::use_<field>(ctx, ...)

About the docs

Good catch on let is_open = use_state(false) in dialog.md — there's no such function. Fixed in a640e606 along with the same bug in 12 other doc files and source comments. The Book now consistently uses use_state_keyed("key", || initial).