Crate glyph_ui[−][src]
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 |
Traits
Gui | A Glyph User Interface |
View | A UI element |