217 lines
8.2 KiB
Markdown
217 lines
8.2 KiB
Markdown
markdown
|
|
---
|
|
sidebar_position: 5
|
|
title: Data Flow and Sync
|
|
---
|
|
|
|
# Data Flow and Synchronization
|
|
|
|
OSUI's reactive state system and event handling capabilities provide a robust foundation for managing data flow within your application. The `use_sync_state` and `use_sync_effect` hooks offer powerful patterns for synchronizing component state with external events and vice versa, enabling sophisticated inter-component communication and data management.
|
|
|
|
## `use_sync_state`: State from Events
|
|
|
|
`use_sync_state` allows a component's internal `State` to be automatically updated whenever a specific type of event is emitted to its `Context`. This is a powerful way to inject external data or changes into a component's reactive state.
|
|
|
|
### How it works:
|
|
|
|
It combines `use_state` and `cx.on_event`.
|
|
1. You provide an initial value for the state.
|
|
2. You specify the event type (`E`) and a `decoder` function.
|
|
3. The `decoder` function takes an `&E` event and returns a new value `T` for the state.
|
|
4. Whenever an event of type `E` is emitted to the current `Context`, the `decoder` runs, and the internal `State<T>` is updated.
|
|
|
|
```rust
|
|
use osui::prelude::*;
|
|
use std::sync::Arc;
|
|
use crossterm::event::{self, Event, KeyCode, KeyEventKind};
|
|
|
|
// Define a simple event to change a message
|
|
#[derive(Debug, Clone)]
|
|
pub struct MessageChangeEvent(pub String);
|
|
|
|
#[component]
|
|
fn MessageDisplay(cx: &Arc<Context>) -> View {
|
|
// Use `use_sync_state` to update the message based on `MessageChangeEvent`
|
|
let message = use_sync_state(
|
|
cx,
|
|
"Initial Message".to_string(), // Initial state value
|
|
|event: &MessageChangeEvent| event.0.clone(), // Decoder: extract string from event
|
|
);
|
|
|
|
rsx! {
|
|
"Received Message:"
|
|
format!(" {}", message.get_dl())
|
|
}.view(&cx)
|
|
}
|
|
|
|
#[component]
|
|
fn MessageInput(cx: &Arc<Context>) -> View {
|
|
// Simulate input by reacting to key presses and emitting MessageChangeEvent
|
|
use_effect(
|
|
{
|
|
let cx = cx.clone();
|
|
move || {
|
|
let _ = crossterm::terminal::enable_raw_mode();
|
|
loop {
|
|
if event::poll(std::time::Duration::from_millis(50)).unwrap() {
|
|
if let Event::Key(key_event) = event::read().unwrap() {
|
|
if key_event.kind == KeyEventKind::Press {
|
|
match key_event.code {
|
|
KeyCode::Char(c) => {
|
|
let msg = format!("Typed: {}", c);
|
|
cx.emit_event(MessageChangeEvent(msg));
|
|
},
|
|
KeyCode::Enter => {
|
|
cx.emit_event(MessageChangeEvent("Enter pressed!".to_string()));
|
|
},
|
|
KeyCode::Esc => {
|
|
let _ = crossterm::terminal::disable_raw_mode();
|
|
cx.stop().expect("Failed to stop engine");
|
|
break;
|
|
},
|
|
_ => {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
&[], // Run once on mount
|
|
);
|
|
|
|
rsx! {
|
|
"Type something to change the message (Esc to quit):"
|
|
}.view(&cx)
|
|
}
|
|
|
|
#[component]
|
|
fn App(cx: &Arc<Context>) -> View {
|
|
rsx! {
|
|
MessageInput {} // Emits MessageChangeEvent
|
|
MessageDisplay {} // Synchronizes its state with MessageChangeEvent
|
|
}.view(&cx)
|
|
}
|
|
|
|
pub fn main() {
|
|
let engine = Console::new();
|
|
engine.run(App {}).expect("Failed to run app");
|
|
let _ = crossterm::terminal::disable_raw_mode();
|
|
}
|
|
```
|
|
|
|
In this example, `MessageInput` emits `MessageChangeEvent`s based on keyboard input. `MessageDisplay` automatically updates its `message` state whenever it receives one of these events from its parent `Context`, thanks to `use_sync_state`.
|
|
|
|
## `use_sync_effect`: Events from State
|
|
|
|
`use_sync_effect` allows changes in a component's internal `State` to automatically trigger the emission of a specific type of event to its `Context`. This is useful for communicating state changes upwards or to sibling components.
|
|
|
|
### How it works:
|
|
|
|
It combines `use_effect` and `cx.emit_event`.
|
|
1. You provide an `State<T>` instance you want to monitor.
|
|
2. You specify an `encoder` function and optional dependencies.
|
|
3. The `encoder` function takes a `&State<T>` and returns an event `Ev`.
|
|
4. Whenever the `State<T>` changes (or any specified dependencies), the `encoder` runs, and the generated event `Ev` is emitted to the current `Context`.
|
|
|
|
```rust
|
|
use osui::prelude::*;
|
|
use std::sync::Arc;
|
|
use std::collections::HashMap;
|
|
|
|
// Event to signal a counter has changed
|
|
#[derive(Debug, Clone)]
|
|
pub struct CounterUpdatedEvent {
|
|
pub id: usize,
|
|
pub new_value: i32,
|
|
}
|
|
|
|
#[component]
|
|
fn ChildCounter(cx: &Arc<Context>, id: &usize, initial_value: &i32) -> View {
|
|
let count = use_state(*initial_value);
|
|
|
|
// Use `use_sync_effect` to emit `CounterUpdatedEvent` when `count` changes
|
|
use_sync_effect(
|
|
cx,
|
|
&count, // Monitor this state
|
|
move |state_ref: &State<i32>| {
|
|
// Encoder: create an event from the state
|
|
CounterUpdatedEvent {
|
|
id: *id,
|
|
new_value: state_ref.get_dl(),
|
|
}
|
|
},
|
|
&[&count], // Effect runs when `count` changes
|
|
);
|
|
|
|
// Simulate incrementing the counter periodically
|
|
use_effect(
|
|
{
|
|
let count = count.clone();
|
|
move || {
|
|
loop {
|
|
sleep(1000); // Increment every second
|
|
*count.get() += 1;
|
|
}
|
|
}
|
|
},
|
|
&[], // Run once on mount
|
|
);
|
|
|
|
rsx! {
|
|
format!("Counter {}: {}", id, count.get_dl())
|
|
}.view(&cx)
|
|
}
|
|
|
|
#[component]
|
|
fn ParentDashboard(cx: &Arc<Context>) -> View {
|
|
let all_counts = use_state(HashMap::<usize, i32>::new());
|
|
|
|
// Listen for `CounterUpdatedEvent` from children
|
|
cx.on_event({
|
|
let all_counts = all_counts.clone();
|
|
move |_ctx, event: &CounterUpdatedEvent| {
|
|
let mut counts_guard = all_counts.get();
|
|
counts_guard.insert(event.id, event.new_value);
|
|
}
|
|
});
|
|
|
|
rsx! {
|
|
"Dashboard Overview:"
|
|
@for (id, value) in all_counts.get_dl() {
|
|
format!(" Counter {}: {}", id, value)
|
|
}
|
|
"---"
|
|
ChildCounter { id: 1, initial_value: 0 }
|
|
ChildCounter { id: 2, initial_value: 10 }
|
|
}.view(&cx)
|
|
}
|
|
|
|
#[component]
|
|
fn App(cx: &Arc<Context>) -> View {
|
|
rsx! {
|
|
ParentDashboard {}
|
|
}.view(&cx)
|
|
}
|
|
|
|
pub fn main() {
|
|
let engine = Console::new();
|
|
engine.run(App {}).expect("Failed to run app");
|
|
}
|
|
```
|
|
|
|
In this example:
|
|
* `ChildCounter` uses `use_sync_effect` to emit a `CounterUpdatedEvent` every time its internal `count` state changes.
|
|
* `ParentDashboard` listens for these `CounterUpdatedEvent`s (which bubble up from its children) using `cx.on_event` and updates its own `all_counts` `HashMap` state. This `HashMap` then drives the display in the dashboard.
|
|
|
|
## When to use `use_sync_state` and `use_sync_effect`:
|
|
|
|
* **Inter-component Communication**: When components need to communicate beyond simple prop passing. Events are excellent for sibling-to-sibling or child-to-ancestor communication without prop drilling.
|
|
* **Centralized State Management**: You can have a central "store" component that emits events, and other components `use_sync_state` to react to those events.
|
|
* **External System Integration**: When your TUI needs to react to external system events (e.g., file changes, network updates) by mapping them to internal `State`.
|
|
* **Decoupling**: They help decouple components, as they don't need direct references to each other, only awareness of event types.
|
|
|
|
By combining `use_state`, `use_effect`, `use_sync_state`, and `use_sync_effect` with OSUI's event system, you can build powerful and maintainable data flow architectures for your TUI applications.
|
|
|
|
**Next:** Learn how to arrange your components visually using OSUI's rendering primitives in [Building Complex Layouts](./06-building-complex-layouts.md).
|