Using the same automated dart signal in multiple widgets

[2bndy5]

I needed a way to use the same signal stream in multiple widgets to dynamically adjust the app theme's colors.

The Problem

Rinf docs do a great job explaining how to use signals to interact (call and respond) with rust. However, if you want to use the same exact response signal in multiple flutter widgets, a multitude of the same exact automated call signals (to instigate the response) can have undesired side effects throughout the entire widget tree.

Consider a root widget that uses dart signals to display the app's colors and maybe some other state(s) all managed in rust. Now imagine a child widget that uses the same signal to only display and change the app's state of colors. When the root widget updates the colors, it will also have to update any other state it gets from rust, and the subsequent widget tree is rebuilt (including the child widget that manipulates the colors). In my experience, this results in a infinite loop of calls-and-responses (evident in debug_print!() outputs).

So, how do we extend the data from 1 stream of an automated dart signal into the scope of child widgets? We could pass the stream's data into constructors of child widgets, but that ends up with bloated code and memory consumption, especially if a grandchild needs the data but not it's immediate parent.

The Solution

Use the provider (flutter favorite) plugin to propagate 1 response from rust into multiple widgets (children of the StreamProvider widget).

Note

It might be possible to instigate a response from a StatefulWidget.initState() or StatelessWidget.build(), but this can lead to a bloated queue of signals that both dart and rust have to contend.

The following code snippets might be a little rough around the edges, but it works as expected.

Here is a sample project: rinf_provider.zip

Third-party dependencies (other than rinf)

Flutter

• flex_color_picker
• provider

Rust

• dirs
• messages
• serde_json

In flutter

Let app settings propagate up the widget tree from

lib/main.dart

import 'dart:typed_data';
import 'dart:ui';
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:flex_color_picker/flex_color_picker.dart';
import 'package:rinf/rinf.dart';
import './messages/all.dart';
import './settings/global.dart';

void main() async {
  await initializeRust(assignRustSignal);
  runApp(
    StreamProvider(
      create: (context) => AppSettings.rustSignalStream,
      initialData: RustSignal(
        AppSettings(color: '4CAF50', mode: AppTheme.system),
        Uint8List(0),
      ),
      child: MyApp(),
    ),
  );
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late final AppLifecycleListener _listener;

  @override
  void initState() {
    super.initState();

    // instigate an `AppSettings` response signal
    SettingRefresh().sendSignalToRust();

    _listener = AppLifecycleListener(
      onExitRequested: () async {
        finalizeRust(); // This line shuts down the async Rust runtime.
        return AppExitResponse.exit;
      },
    );
  }

  @override
  void dispose() {
    _listener.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    // rebuild widget tree if app settings change
    final appSettings = context.watch<RustSignal<AppSettings>>();

    // convert string from signal to `Color` type (using flex_color_picker API)
    final seedColor = appSettings.message.color.toColor;

    return MaterialApp(
      title: 'My Colored App',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: seedColor),
        useMaterial3: true,
      ),
      darkTheme: ThemeData(
        colorScheme: ColorScheme.fromSeed(
          seedColor: seedColor,
          brightness: Brightness.dark,
        ),
      ),
      themeMode: ThemeMode.values.firstWhere(
        (mode) => mode.index == appSettings.message.mode.value,
      ),
      home: SettingsGlobal(),
      debugShowCheckedModeBanner: false,
    );
  }
}

Warning

In the above dart example, I had to manually instantiate a RustSignal<T> as a default value to the StreamProvider.initialData field. Developers should beware the difference between [DART-SIGNAL-BINARY] and [DART-SIGNAL]! In the solution provided, I never use the binary value of a dart signal. Thus, I was able to use Uint8List(0) as a placeholder until the stream actually received data.

And change the color settings from a child widget in

lib/setting/global.dart

import 'package:flex_color_picker/flex_color_picker.dart';
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:rinf/rinf.dart';
import '../messages/all.dart';

class SettingsGlobal extends StatelessWidget {
  const SettingsGlobal({super.key});

  @override
  Widget build(BuildContext context) {
    // here we only read the app settings because the entire widget tree
    // will be rebuilt when we change the settings.
    final appSettings = context.read<RustSignal<AppSettings>>();
    final currentColor = appSettings.message.color.toColor;

    final theme = Theme.of(context);
    final colorScheme = theme.colorScheme;
    return Scaffold(
      appBar: AppBar(
        backgroundColor: colorScheme.primaryContainer,
        foregroundColor: colorScheme.onPrimaryContainer,
        title: const Text("App settings"),
      ),
      body: Padding(
        padding: const EdgeInsets.all(8.0),
        child: ListView(
          children: [
            ListTile(
              onTap: () async {
                final Color newColor = await showColorPickerDialog(
                  context,
                  currentColor,
                );
                if (newColor != currentColor) {
                  AppSettings(
                    color: newColor.hex,
                    mode: appSettings.message.mode,
                  ).sendSignalToRust();
                }
              },
              title: const Text("App Color"),
              trailing: LayoutBuilder(builder: (context, constraints) {
                  return Padding(
                    padding: const EdgeInsets.all(8.0),
                    child: ColorIndicator(
                      height: constraints.maxHeight - 16.0,
                      onSelectFocus: false,
                      width: constraints.maxHeight - 16.0,
                      color: currentColor,
                    ),
                  );
                },
              ),
            ),
            ListTile(
              title: const Text("Color Scheme"),
              trailing: SegmentedButton<ThemeMode>(
                segments: [
                  const ButtonSegment<ThemeMode>(
                      value: ThemeMode.system,
                      label: Text("Auto"),
                      icon: Icon(Icons.brightness_auto_outlined)),
                  const ButtonSegment<ThemeMode>(
                      value: ThemeMode.light,
                      label: Text("Light"),
                      icon: Icon(Icons.brightness_5)),
                  const ButtonSegment<ThemeMode>(
                      value: ThemeMode.dark,
                      label: Text("Dark"),
                      icon: Icon(Icons.brightness_2_outlined)),
                ],
                selected: <ThemeMode>{
                  ThemeMode.values.firstWhere(
                    (mode) => mode.index == appSettings.message.mode.value,
                  ),
                },
                onSelectionChanged: (Set<ThemeMode> mode) {
                  AppSettings(
                    color: appSettings.message.color,
                    mode: AppTheme.valueOf(mode.first.index),
                  ).sendSignalToRust();
                },
              ),
            ),
          ],
        ),
      ),
    );
  }
}

In ProtoBuf

I declared the signals to communicate app settings in messages/settings.proto

// [DART-SIGNAL]
message SettingRefresh {
}

enum AppTheme {
  system = 0;
  light = 1;
  dark = 2;
}

// [RUST-SIGNAL]
// [DART-SIGNAL]
message AppSettings {
  string color = 1;
  AppTheme mode = 2;
}

In Rust

I used the recommended Actor model to handle signals in

native/hub/src/settings.rs

use crate::cache::{CacheManager, CacheSettings};
use crate::messages::{AppSettings, SettingRefresh};
use anyhow::Result;
use messages::prelude::*;
use rinf::debug_print;
use tokio::task::spawn;

pub struct SettingsActor {
    cache_mgr: CacheManager,
}

impl Actor for SettingsActor {}

fn check_err<T>(err_msg: Option<&str>, result: Result<T, impl std::fmt::Debug>) -> Option<T> {
    match result {
        Ok(k) => return Some(k),
        Err(e) => {
            debug_print!("{}: {e:?}", err_msg.unwrap_or_default());
            None
        }
    }
}

impl SettingsActor {
    pub fn new(settings_addr: Address<Self>) -> Result<Self> {
        let cache_mgr = CacheManager::new()?;
        spawn(Self::listen_for_settings_refresh(settings_addr.clone()));
        spawn(Self::listen_for_settings_update(settings_addr));
        Ok(Self { cache_mgr })
    }

    pub async fn listen_for_settings_refresh(mut settings_addr: Address<Self>) {
        let receiver = SettingRefresh::get_dart_signal_receiver();
        while let Some(dart_signal) = receiver.recv().await {
            debug_print!("refreshing settings");
            let result = settings_addr.send(dart_signal.message).await;
            if let Some(result) = check_err(None, result) {
                check_err(Some("Failed to update GUI settings"), result);
            }
        }
    }

    pub async fn listen_for_settings_update(mut settings_addr: Address<Self>) {
        let receiver = AppSettings::get_dart_signal_receiver();
        while let Some(dart_signal) = receiver.recv().await {
            debug_print!("updating app settings");
            let result = settings_addr.send(dart_signal.message).await;
            if let Some(result) = check_err(None, result) {
                check_err(Some("Failed to update cached settings"), result);
            }
            let result = settings_addr.send(SettingRefresh {}).await;
            if let Some(result) = check_err(None, result) {
                check_err(Some("Failed to update GUI settings"), result);
            }
        }
    }
}

#[async_trait]
impl Handler<AppSettings> for SettingsActor {
    type Result = Result<()>;
    async fn handle(&mut self, msg: AppSettings, _context: &Context<Self>) -> Self::Result {
        let settings = CacheSettings {
            color: msg.color,
            mode: msg.mode as u8,
        };
        self.cache_mgr.write_settings(&settings)
    }
}

#[async_trait]
impl Handler<SettingRefresh> for SettingsActor {
    type Result = Result<()>;
    // Handles messages received by the actor.
    async fn handle(&mut self, _msg: SettingRefresh, _context: &Context<Self>) -> Self::Result {
        let current = self.cache_mgr.load_settings()?;
        AppSettings {
            color: current.color,
            mode: current.mode as i32,
        }
        .send_signal_to_dart();
        Ok(())
    }
}

// Creates and spawns the actors in the async system.
pub async fn create_actors() -> Result<()> {
    // Create actor contexts.
    let settings_context = Context::new();
    let settings_addr = settings_context.address();

    // Spawn actors.
    let actor = SettingsActor::new(settings_addr)?;
    spawn(settings_context.run(actor));

    Ok(())
}

And I manage the cache in

native/hub/src/cache.rs

use crate::messages::AppTheme;
use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};
use std::{
    env::current_dir,
    fs,
    io::{BufReader, Write},
    path::PathBuf,
};

#[derive(Debug, PartialEq, Deserialize, Serialize)]
pub struct CacheSettings {
    pub color: String,
    pub mode: u8,
}

pub struct CacheManager {
    settings: PathBuf,
}

impl CacheManager {
    pub fn new() -> Result<Self> {
        // if platform is unsupported by dirs crate, use working directory
        // TODO: improve this for Android and iOS
        let cache_dir = dirs::cache_dir().map_or(current_dir()?, |d| d.join("my-cool-app"));
        let settings_file = cache_dir.join("settings.json");
        if !cache_dir.exists() {
            fs::create_dir(cache_dir)?;
        }
        Ok(Self { settings: settings_file })
    }

    pub fn load_settings(&self) -> Result<CacheSettings> {
        if !self.settings.exists() {
            let default = CacheSettings {
                color: "4CAF50".to_string(), // Colors.green
                mode: AppTheme::System as u8,
            };
            fs::write(&self.settings, serde_json::to_string(&default)?)
                .with_context(|| "Failed to write default settings to new cache")?;
            return Ok(default);
        }
        let file = fs::File::open(&self.settings)?;
        let reader = BufReader::new(file);
        let settings: CacheSettings = serde_json::from_reader(reader)?;
        Ok(settings)
    }

    pub fn write_settings(&self, settings: &CacheSettings) -> Result<()> {
        let mut file = fs::File::create(&self.settings)?;
        file.write_all(serde_json::to_string(settings)?.as_bytes())
            .with_context(|| "Failed to update cached settings")
    }
}

[temeddix]

Using inherited state management with provider or InheritedWidget would be nice to be introduced in the docs! I will definitely look into it later.

[2bndy5]

I like the provider pkg because it requires less boilerplate code and is feature complete. The API is stable and any updates that follow are oriented around breaking changes in the Flutter SDK.

It should be noted that this tactic is probably not a good idea for time-sensitive signals (eg audio or video that typically consume a binary stream). I haven't stressed tested this tactic for performance. But it works great for state and metadata signals.

[2bndy5]

The docs addition could probably do without the caching parts. In rust, there isn't any crates like dirs that support mobile OS or the web platform.

[2bndy5]

The docs addition could probably do without the caching parts. In rust, there isn't any crates like dirs that support mobile OS or the web platform.

Looking at how this would work without caching in rust side, I'm not sure how applicable this tactic is. Caching in dart can be done with the shared_preferences plugin. There's no need to use rust for managing a cached state that is get/set in dart.

Instead of app colors, I think a docs addition would simply manage a 'Hello $name' string in 2 widgets: 1 that displays the value and 1 that sets the value. I'm imagining a dialog that that is spawned (as a child widget) when tapping on the displayed string to change it.

I'm open to other ideas, but I'm trying to keep the proposed docs' example simple.

[temeddix]

Great :)

If we add the info to the docs, it would be nice to organize them into one dedicated page (not multiple pages).