Crate woab

WoAB (Widgets on Actors Bridge) is a library for combining the widgets toolkit GTK with the actors framework Actix. It helps with:

• Running the actors inside the GTK thread, allowing message handlers to interact with the widgets directly.
• Routing GTK signals through the asynchronous runtime, so that the code handling them can proceed naturally to interact with the actors.
• Mapping widgets and signals from Glade XML files to user types.

To use WoAB one would typically create a factories struct using woab::Factories and use it dissect the Glade XML file(s). Each field of the factories struct will be a woab::Factory that can create:

• An Actor (optional)
• A widgets struct using woab::WidgetsFromBuilder
• A signal enum (optional) using woab::BuilderSignal

The factories can then be used to generate the GTK widgets and either connect them to a new actor which will receive the signals defined in the Glade GTK or connect them to an existing actor and tag the signals (so that multiple instances can be added - e.g. with GtkListBox - and the signal handler can know from which one the event came). The actors receive the signals as Actix streams, and use StreamHandler to handle them.

If multiple tagged signals are streamed to the same actor - which is the typical use case for tagged signals - StreamHandler::finished should be overridden to avoid stopping the actor when one instance of the widgets is removed!!!

To remove widget-bound actors at runtime, see woab::Remove.

After initializing GTK and before starting the main loop, woab::run_actix_inside_gtk_event_loop must be called. Do not run the Actix system manually!

use gtk::prelude::*;

#[derive(woab::Factories)]
struct Factories {
    // The field name must be the ID from the builder XML file:
    main_window: woab::Factory<AppActor, AppWidgets, AppSignal>,
    // Possibly other things from the builder XML file that need to be created during the program.
}

struct AppActor {
    widgets: AppWidgets,
    factories: std::rc::Rc<Factories>, // for creating more things from inside the actor.
    // More actor data
}

impl actix::Actor for AppActor {
    type Context = actix::Context<Self>;
}

#[derive(woab::WidgetsFromBuilder)]
struct AppWidgets {
    main_window: gtk::ApplicationWindow, // needed for making the window visible
    // Other widgets inside the window to interact with.
}

#[derive(woab::BuilderSignal)]
enum AppSignal {
    // These are custom signals defined in Glade's "Signals" tab.
    Sig1, // Use unit variants when the signal parameters can be ignored.
    Sig2(gtk::TextBuffer), // Use tuple variants when the signal parameters are needed.
}

impl actix::StreamHandler<AppSignal> for AppActor {
    fn handle(&mut self, signal: AppSignal, ctx: &mut Self::Context) {
        match signal {
            AppSignal::Sig1 => {
                // Behavior for Sig1.
            },
            AppSignal::Sig2(text_buffer) => {
                // Behavior for Sig2 that uses the signal parameter.
            },
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let factories = std::rc::Rc::new(Factories::read(read_builder_xml())?);
    gtk::init()?;
    woab::run_actix_inside_gtk_event_loop("my-WoAB-app")?; // <===== IMPORTANT!!!

    factories.main_window.build().actor(|_ctx, widgets| {
        widgets.main_window.show_all(); // Could also be done inside the actor
        AppActor {
            widgets,
            factories: factories,
        }
    })?;

    gtk::main();
    Ok(())
}

Structs

BuilderFactory	Holds instructions for generating a GTK builder.
BuilderUtilizer	Context for utilizing a gtk::Builder and connecting it to he Actix world.
Factory	Holds instructions for generating GTK widgets and connecing them to Actix actors.
Remove	A message for removing actors along with their GUI

Enums

Error

Traits

BuilderSignal

Represent a GTK signal that originates from a GTK builder. Refer to the corresponding derive.

Functions

run_actix_inside_gtk_event_loop

Start an Actix System that runs inside the GTK thread.

Derive Macros

BuilderSignal	Represent a GTK signal that originates from a GTK builder. See the corresponding trait.
Factories	Dissect a single Glade XML file to multiple builder factories.
Removable	Make the actor remove itself and its widgets when it gets the woab::Remove message.
WidgetsFromBuilder	Represent a set of GTK widgets created by a GTK builder.