update state management

Author: MoAlyousef

docs/State-Management.html

@@ -223,114 +223,281 @@ <h1 id="state-management"><a class="header" href="#state-management">State manag
     a.run();
 }</code></pre></pre>
 <h2 id="helper-crates"><a class="header" href="#helper-crates">Helper crates</a></h2>
-<p>The crates ecosystem offers many crates which provide state management. Also there are 2 crates under the fltk-rs org which offer means of architecting your app and managing its state:</p>
+<p>The crates ecosystem offers many crates which provide state management. Also there are 3 crates under the fltk-rs org which offer means of architecting your app and managing its state:</p>
 <ul>
-<li><a href="https://github.com/fltk-rs/flemish">flemish</a>:</li>
+<li>
+<p><a href="https://github.com/fltk-rs/fltk-observe">fltk-observe</a>
+Provides an observer-like mechanism on top of fltk-rs. With it, you can implement patterns such as MVC, MVP, or MVVM. The crate helps decouple your data (Model) from your UI (View) by automatically triggering updates in the UI when state changes, making your code cleaner and easier to maintain.</p>
+</li>
+<li>
+<p><a href="https://github.com/fltk-rs/flemish">flemish</a>:</p>
+</li>
 </ul>
-<p>Offers an Elm like SVU architecture. This is reactive, immutable in essence, and tears down the view which each Message.</p>
+<p>Implements an Elm-like architecture, sometimes referred to as SVU (State-View-Update). It uses an immutable, reactive approach: each time you send a Message, Flemish compares the difference in the virtual dom and updates the View according to the updated state. This can simplify logic by making view rendering a pure function of your state.</p>
 <ul>
 <li><a href="https://github.com/fltk-rs/fltk-evented">fltk-evented</a>:</li>
 </ul>
-<p>This resembles immediate-mode guis in that all events are handled in the event loop. In reality it's also reactive but mutable and stateless. This doesn't cause a redraw with triggers.</p>
-<p>Both crates avoid the use of callbacks since these can be a pain in Rust in terms of lifetimes and borrowing. You need to use shared smart pointers with interior mutability to be able to borrow into a callback.</p>
-<p>You can take a look at both crates for inspiration.</p>
-<p>A sample counter in both:</p>
-<h2 id="flemish"><a class="header" href="#flemish">Flemish</a></h2>
-<pre><pre class="playground"><code class="language-rust edition2021">use flemish::{
-    button::Button, color_themes, frame::Frame, group::Flex, prelude::*, OnEvent, Sandbox, Settings,
-};
+<p>Adopts a more immediate-mode paradigm, where all events are handled centrally in the event loop. Despite being described as “reactive” and “stateless,” it still processes user interactions in a single pass, updating state as needed without forcing redraws unless explicitly triggered. This avoids needing multiple callbacks scattered throughout your code.</p>
+<p>All three crates aim to sidestep heavy use of callbacks, which can introduce borrowing complexities in Rust. Instead, they lean on shared smart pointers, internal mutability, or fully reactive state flows, so you don’t have to juggle lifetimes and manual callback wiring. If you’re looking for alternative approaches to managing state and events in your fltk-rs application, check out each crate for inspiration on different ways to structure your GUI logic.</p>
+<p>A sample counter in the above mentioned crates:</p>
+<h2 id="fltk-observe"><a class="header" href="#fltk-observe">fltk-observe</a></h2>
+<pre><pre class="playground"><code class="language-rust edition2021">use fltk::{app, button::Button, prelude::*, window::Window};
+use fltk_observe::{Runner, WidgetObserver};
 
-pub fn main() {
-    Counter::new().run(Settings {
-        size: (300, 100),
-        resizable: true,
-        color_map: Some(color_themes::BLACK_THEME),
-        ..Default::default()
-    })
+struct Counter {
+    value: i32,
 }
 
-#[derive(Default)]
+impl Counter {
+    fn new() -&gt; Self {
+        Self { value: 0 }
+    }
+
+    fn value(&amp;self) -&gt; i32 {
+        self.value
+    }
+
+    fn increment(&amp;mut self, _b: &amp;Button) {
+        self.value += 1;
+    }
+
+    fn update_label(&amp;self, b: &amp;mut Button) {
+        b.set_label(&amp;self.value().to_string());
+    }
+}
+
+fn main() {
+    let a = app::App::default().use_state(Counter::new).unwrap();
+
+    let mut window = Window::default().with_size(200, 200).with_label("Add data");
+    let mut inc = Button::default_fill();
+    inc.set_action(Counter::increment);
+    inc.set_view(Counter::update_label);
+    window.end();
+    window.show();
+
+    a.run().unwrap();
+}</code></pre></pre>
+<p>An example of an MVVM architecture on top of fltk-observe:</p>
+<pre><pre class="playground"><code class="language-rust edition2021">use fltk::{app, button::Button, frame::Frame, group::Flex, prelude::*, window::Window};
+
 struct Counter {
     value: i32,
 }
 
-#[derive(Debug, Clone, Copy)]
-enum Message {
-    IncrementPressed,
-    DecrementPressed,
+impl Counter {
+    fn new() -&gt; Self {
+        Self { value: 0 }
+    }
+    fn increment(&amp;mut self) {
+        self.value += 1;
+    }
+    fn decrement(&amp;mut self) {
+        self.value -= 1;
+    }
+    fn get_value(&amp;self) -&gt; i32 {
+        self.value
+    }
+}
+
+struct CounterViewModel {
+    model: Counter,
+}
+
+impl CounterViewModel {
+    fn new() -&gt; Self {
+        Self {
+            model: Counter::new(),
+        }
+    }
+
+    fn increment(&amp;mut self, _btn: &amp;Button) {
+        self.model.increment();
+    }
+
+    fn decrement(&amp;mut self, _btn: &amp;Button) {
+        self.model.decrement();
+    }
+
+    fn update_display(&amp;self, frame: &amp;mut Frame) {
+        frame.set_label(&amp;self.model.get_value().to_string());
+    }
+}
+
+struct CounterView {
+    inc_btn: Button,
+    dec_btn: Button,
+    display: Frame,
+}
+
+impl CounterView {
+    fn new() -&gt; Self {
+        let mut window = Window::default()
+            .with_size(300, 160)
+            .with_label("MVVM (fltk-observe)");
+        let flex = Flex::default_fill().column();
+        let inc_btn = Button::default().with_label("Increment");
+        let display = Frame::default();
+        let dec_btn = Button::default().with_label("Decrement");
+        flex.end();
+        window.end();
+        window.show();
+        Self {
+            inc_btn,
+            dec_btn,
+            display,
+        }
+    }
 }
 
-impl Sandbox for Counter {
-    type Message = Message;
+struct CounterApp {
+    app: app::App,
+}
 
+impl CounterApp {
     fn new() -&gt; Self {
-        Self::default()
+        use fltk_observe::{Runner, WidgetObserver};
+        let app = app::App::default()
+            .use_state(CounterViewModel::new)
+            .unwrap();
+
+        let mut view = CounterView::new();
+        view.inc_btn.set_action(CounterViewModel::increment);
+        view.dec_btn.set_action(CounterViewModel::decrement);
+        view.display.set_view(CounterViewModel::update_display);
+
+        Self { app }
     }
 
-    fn title(&amp;self) -&gt; String {
-        String::from("Counter - fltk-rs")
+    fn run(&amp;self) {
+        self.app.run().unwrap();
     }
+}
+
+fn main() {
+    let app = CounterApp::new();
+    app.run();
+}</code></pre></pre>
+<h2 id="flemish"><a class="header" href="#flemish">Flemish</a></h2>
+<pre><pre class="playground"><code class="language-rust edition2021">use flemish::{view::*, Settings};
+
+pub fn main() {
+    flemish::application("counter", Counter::update, Counter::view)
+        .settings(Settings {
+            size: (300, 100),
+            resizable: true,
+            ..Default::default()
+        })
+        .run();
+}
+
+#[derive(Default)]
+struct Counter {
+    value: i32,
+}
+
+#[derive(Debug, Clone, Copy)]
+enum Message {
+    Increment,
+    Decrement,
+}
 
+impl Counter {
     fn update(&amp;mut self, message: Message) {
         match message {
-            Message::IncrementPressed =&gt; {
+            Message::Increment =&gt; {
                 self.value += 1;
             }
-            Message::DecrementPressed =&gt; {
+            Message::Decrement =&gt; {
                 self.value -= 1;
             }
         }
     }
 
-    fn view(&amp;mut self) {
-        let col = Flex::default_fill().column();
-        Button::default()
-            .with_label("Increment")
-            .on_event(Message::IncrementPressed);
-        Frame::default().with_label(&amp;self.value.to_string());
-        Button::default()
-            .with_label("Decrement")
-            .on_event(Message::DecrementPressed);
-        col.end();
+    fn view(&amp;self) -&gt; View&lt;Message&gt; {
+        Column::new(&amp;[
+            Button::new("+", Message::Increment).view(),
+            Frame::new(&amp;self.value.to_string()).view(),
+            Button::new("-", Message::Decrement).view(),
+        ])
+        .view()
     }
 }</code></pre></pre>
 <h2 id="fltk-evented"><a class="header" href="#fltk-evented">fltk-evented</a></h2>
 <pre><pre class="playground"><code class="language-rust edition2021">use fltk::{app, button::Button, frame::Frame, group::Flex, prelude::*, window::Window};
 use fltk_evented::Listener;
 
-fn main() {
-    let a = app::App::default().with_scheme(app::Scheme::Gtk);
-    app::set_font_size(20);
-
-    let mut wind = Window::default()
-        .with_size(160, 200)
-        .center_screen()
-        .with_label("Counter");
-    let flex = Flex::default()
-        .with_size(120, 160)
-        .center_of_parent()
-        .column();
-    let but_inc: Listener&lt;_&gt; = Button::default().with_label("+").into();
-    let mut frame = Frame::default();
-    let but_dec: Listener&lt;_&gt; = Button::default().with_label("-").into();
-    flex.end();
-    wind.end();
-    wind.show();
-
-    let mut val = 0;
-    frame.set_label(&amp;val.to_string());
-
-    while a.wait() {
-        if but_inc.triggered() {
-            val += 1;
-            frame.set_label(&amp;val.to_string());
-        }
+struct Counter {
+    value: i32,
+}
+
+impl Counter {
+    fn new() -&gt; Self {
+        Self { value: 0 }
+    }
+    fn increment(&amp;mut self) {
+        self.value += 1;
+    }
+    fn decrement(&amp;mut self) {
+        self.value -= 1;
+    }
+    fn value(&amp;self) -&gt; i32 {
+        self.value
+    }
+}
 
-        if but_dec.triggered() {
-            val -= 1;
-            frame.set_label(&amp;val.to_string());
+struct CounterApp {
+    counter: Counter,
+    a: app::App,
+    but_inc: Listener&lt;Button&gt;,
+    frame: Frame,
+    but_dec: Listener&lt;Button&gt;,
+}
+
+impl CounterApp {
+    pub fn new(counter: Counter) -&gt; Self {
+        let a = app::App::default().with_scheme(app::Scheme::Gtk);
+        app::set_font_size(20);
+
+        let mut wind = Window::default()
+            .with_size(160, 200)
+            .with_label("Counter");
+        let flex = Flex::default()
+            .with_size(120, 160)
+            .center_of_parent()
+            .column();
+        let but_inc: Listener&lt;_&gt; = Button::default().with_label("+").into();
+        let frame = Frame::default().with_label(&amp;counter.value().to_string());
+        let but_dec: Listener&lt;_&gt; = Button::default().with_label("-").into();
+        flex.end();
+        wind.end();
+        wind.show();
+        Self {
+            counter,
+            a,
+            but_inc,
+            frame,
+            but_dec,
+        }
+    }
+    pub fn run(&amp;mut self) {
+        while self.a.wait() {
+            if fltk_evented::event() {
+                if self.but_inc.triggered() {
+                    self.counter.increment();
+                }
+                if self.but_dec.triggered() {
+                    self.counter.decrement();
+                }
+                self.frame.set_label(&amp;self.counter.value().to_string());
+            }
         }
     }
+}
+
+fn main() {
+    let mut app = CounterApp::new(Counter::new());
+    app.run();
 }</code></pre></pre>
 
                     </main>