Module application

Application foundation used to drive the RAUI interface

An Application is the struct that pulls together all the pieces of a RAUI ui such as layout, interaction, animations, etc.

In most cases users will not need to manually create and manage an Application. That will usually be handled by renderer integration crates like raui_tetra_renderer.

You will need to interact with Application if you are building your own RAUI integration with another renderer or game engine.

Example

// Create the application
let mut application = Application::new();

// We need to run the "setup" functions for the application to register components and
// properties if we want to support serialization of the UI. We pass it a function that
// will do the actual registration
application.setup(setup /* the core setup function from the RAUI prelude */);

// If we used RAUI material we would also want to call it's setup ( but we don't need
// it here )
// application.setup(raui_material::setup);

// Create the renderer. In this case we use the raw renderer that will return raw
// [`WidgetUnit`]'s, but usually you would have a custom renderer for your game
// engine or renderer.
let mut renderer = RawRenderer;

// Create the interactions engine. The default interactions engine covers typical
// pointer + keyboard + gamepad navigation/interactions.
let mut interactions = DefaultInteractionsEngine::new();

// We create our widget tree
let tree = widget! {
    (#{"app"} nav_content_box [
        (#{"button"} button: {NavItemActive} {
            content = (#{"icon"} image_box)
        })
    ])
};

// We apply the tree to the application. This must be done again if we wish to change the
// tree.
application.apply(tree);

// This and the following function calls would need to be called every frame
loop {
    // Telling the app to `process` will make it perform any necessary updates.
    //
    // We can also pass in a `ProcessContext` which allows us to provide the UI with
    // mutable access to application data, but we just pass in a default context in
    // this case.
    application.process();

    // To properly handle layout we need to create a mapping of the screen coordinates to
    // the RAUI coordinates. We would update this with the size of the window every frame.
    let mapping = CoordsMapping::new(Rect {
        left: 0.0,
        right: 1024.0,
        top: 0.0,
        bottom: 576.0,
    });

    // We apply the application layout
    application
        // We use the default layout engine, but you could make your own layout engine
        .layout(&mapping, &mut DefaultLayoutEngine)
        .unwrap();

    // we interact with UI by sending interaction messages to the engine. You would hook this
    // up to whatever game engine or window event loop to perform the proper interactions when
    // different events are emitted.
    interactions.interact(Interaction::PointerMove(Vec2 { x: 200.0, y: 100.0 }));
    interactions.interact(Interaction::PointerDown(
        PointerButton::Trigger,
        Vec2 { x: 200.0, y: 100.0 },
    ));

    // Since interactions engines require constructed layout to process interactions we
    // have to process interactions after we layout the UI.
    application.interact(&mut interactions).unwrap();

    // Now we render the app, printing it's raw widget units
    println!("{:?}", application.render(&mapping, &mut renderer).unwrap());
}

Structs

Application

Contains and orchestrates application layout, animations, interactions, etc.

ChangeNotifier

Allows you to check or indicate that an Application has changed

ProcessContext

Allows you to get mutable or immutable references to data exposed by the host of the RAUI application

Enums

ApplicationError

Errors that can occur while interacting with an application

InvalidationCause

Indicates the reason that an Application state was invalidated and had to be re-rendered