Crate actuate

Source
Expand description

§Actuate

A high-performance and borrow-checker friendly framework for declarative programming in Rust. This crate provides a generic library that lets you define reactive components (also known as composables, for more see Compose).

use actuate::prelude::*;
use bevy::prelude::*;

// Counter composable.
#[derive(Data)]
struct Counter {
    start: i32,
}

impl Compose for Counter {
    fn compose(cx: Scope<Self>) -> impl Compose {
        let count = use_mut(&cx, || cx.me().start);

        material_ui((
            text::headline(format!("High five count: {}", count)),
            button(text::label("Up high")).on_click(move || SignalMut::update(count, |x| *x += 1)),
            button(text::label("Down low")).on_click(move || SignalMut::update(count, |x| *x -= 1)),
            if *count == 0 {
                Some(text::label("Gimme five!"))
            } else {
                None
            },
        ))
        .align_items(AlignItems::Center)
        .justify_content(JustifyContent::Center)
    }
}

§Borrowing

Composables can borrow from their ancestors, as well as state.

use actuate::prelude::*;
use bevy::prelude::*;

#[derive(Data)]
struct User<'a> {
    // `actuate::Cow` allows for either a borrowed or owned value.
    name: Cow<'a, String>,
}

impl Compose for User<'_> {
    fn compose(cx: Scope<Self>) -> impl Compose {
        text::headline(cx.me().name.to_string())
    }
}

#[derive(Data)]
struct App {
    name: String
}

impl Compose for App {
    fn compose(cx: Scope<Self>) -> impl Compose {
        // Get a mapped reference to the app's `name` field.
        let name = Signal::map(cx.me(), |me| &me.name).into();

        User { name }
    }
}

§Hooks

Functions that begin with use_ are called hooks in Actuate. Hooks are used to manage state and side effects in composables.

Hooks must be used in the same order for every re-compose. Don’t use hooks inside loops, conditions, nested functions, or match blocks. Instead, always use hooks at the top level of your composable, before any early returns.

§Installation

To add this crate to your project:

cargo add actuate --features full

§Features

  • std: Enables features that use Rust’s standard library (default). With this feature disabled Actuate can be used in #![no_std] environments.
  • animation: Enables the animation module for animating values from the Bevy ECS. (enables the ecs feature).
  • ecs: Enables the ecs module for bindings to the Bevy ECS.
  • executor: Enables the executor module for multi-threaded tasks.
  • material: Enables the material module for Material UI (enables the ecs and ui features).
  • picking: Enables support for picking event handlers with Modify (requires the ecs feature).
  • rt Enables support for the Tokio runtime with the Executor trait. (enables the executor feature).
  • tracing: Enables the logging through the tracing crate.
  • ui: Enables the ui module for user interface components.
  • full: Enables all features above.

Modules§

  • animationanimation
    Animation hooks.
  • Composable functions.
  • Low-level composer.
  • Data trait and macros. Data trait and macros.
  • ecsecs
    Bevy ECS integration.
  • executorexecutor
    Task execution context.
  • Prelude of commonly used items.
  • uiui
    User interface components.

Structs§

  • Error for a missing context.
  • Mapped immutable reference to a value of type T.
  • Unchecked, mapped immutable reference to a value of type T.
  • Composable scope.
  • State of a composable.
  • Immutable reference to a value of type T.
  • Mutable reference to a value of type T.

Enums§

  • Clone-on-write value.
  • Immutable reference or mapped reference to a value.

Traits§

  • Generational reference. This can be used to compare expensive values by pointer equality.

Functions§

  • Use a callback function. The returned function will be updated to f whenever this component is re-composed.
  • Use a context value of type T.
  • Use a function that will be called when this scope is dropped.
  • Use an effect that will run whenever the provided dependency is changed.
  • Use a local task that runs on the current thread.
  • Use a memoized value of type T with a dependency of type D.
  • Use a mutable reference to a value of type T.
  • Provide a context value of type T.
  • Use an immutable reference to a value of type T.
  • use_taskexecutor
    Use a multi-threaded task that runs on a separate thread.

Type Aliases§