Crate glyph_ui

Glyph User Interface

Not your typical GUI library: Glyph UI is actually for implementing text-based interfaces. In particular, its usage is designed to result in maintainable applications even at large numbers of components by leveraging the Elm architecture.

Examples

Glyph UI's hello world isn't the most succinct, but that's a non-goal. With that understanding, let's get started by setting up our imports:

use glyph_ui::{
    // Here we import the absolutely necessary items to implement the `Gui`
    // trait and start the `Runtime`
    prelude::*,

    // The `view` module contains various premade views
    view::{
        // This gives us extensions to the `View` trait; we'll use two later
        prelude::*,

        // Like all modules inside the `view` module (except `prelude`),
        // this contains a `View` trait implementer as well as a shorthand
        // for instantiating it. Some modules also have a `State` (think
        // "model") and/or other items for configuring the view's behavior
        text,
    },

    // This type describes view-level events, which are not to be confused
    // with the Elm architecture's concept of "messages"
    event::Event,
};

// We'll use this later for detecting specific keypresses
use keyboard_types::Key;

Next, let's define our model:

struct HelloWorld {
    // Keep track of whether it's time to exit the application
    shutdown: bool,
}

Now we can implement the Gui trait for our model, which describes what our view will look like, how to handle messages, and when to exit the application:

impl Gui for HelloWorld {
    // Our message type will be `bool`, which we'll set during updates to
    // to be read when queried about control flow
    type Message = bool;

    // Glyph UI's event type has a variant in which a custom type can be
    // produced. This is a more advanced feature that we don't need at the
    // moment, so the unit type will do
    type Event = ();

    // In this function, we build up our application's appearance by
    // combining views
    fn view(&mut self) -> element::View<Self::Event, Self::Message> {
        // It's about time we actually wrote the hello world part, isn't it?
        text::new("Hello, world!")
            // This is one of the two extension functions mentioned earlier.
            // It allows us to wrap a view in another view that makes it
            // easier to respond to events (not messages) in a custom manner
            .on_event(|e, _f| {
                // Detect whether the user pressed the 'q' key, for "quit"
                if let Event::Key(k) = e {
                    if let Key::Character(c) = &k.key {
                        if c == "q" {
                            // Views can produce multiple messages from a
                            // single event, but we only need to produce one
                            return Box::new(std::iter::once(true));
                        }
                    }
                }

                // Some other key was pressed, so we produce no messages
                Box::new(std::iter::empty())
            })
            // This is the second extension function. It turns a view into
            // a more generic object, which is useful for defining
            // abstraction layers between UI components. It also happens to
            // be the required return type of `Gui::view()`
            .into_element()
    }

    // This function will only get called when there are new messages
    fn update(&mut self, m: Self::Message) {
        // Update our internal state
        self.shutdown = m;
    }

    // This function gets called after `update`, which means it also only
    // runs when there are new messages
    fn control_flow(&self) -> ControlFlow {
        if self.shutdown {
            // If the user pressed 'q', we'll have received a message of
            // `true` in `update`, which means it's time to exit
            ControlFlow::Exit
        } else {
            // Otherwise, we continue to run the event loop, waiting until
            // the next message
            ControlFlow::Wait
        }
    }
}

Nearly there! The final piece is to create and start the Runtime, which we'll do now:

#[tokio::main]
async fn main() {
    // Instantiate our model
    let gui = HelloWorld {
        shutdown: false,
    };

    // Create and start the runtime
    Runtime::new(gui, |task| tokio::spawn(task)).run().await;
}

Now if we compile and run our code, we'll see Hello, world! in the top left corner of our terminal, and we'll get our shell back if we press the q key. For more examples that demonstrate more complex applications, see here.

Modules

event	Event handling
prelude	Prelude for commonly used items
unit	Dimensional units
view	UI elements

Structs

Printer	Draw on a subset of the screen
Runtime	Runtime for a Glyph User Interface application

Enums

ControlFlow	Event loop control flow
OutOfBounds	Error returned from some Printer methods

Traits

Gui	A Glyph User Interface
View	A UI element