1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
//! 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]. //! //! [the Elm architecture]: https://guide.elm-lang.org/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`](crate::Gui) trait for our model, which //! describes what our view will look like, how to handle messages, and when to //! exit the application: //! //! ``` //! # use glyph_ui::{ //! # prelude::*, //! # event::Event, //! # view::{ //! # prelude::*, //! # text, //! # }, //! # }; //! # use keyboard_types::Key; //! # struct HelloWorld { //! # shutdown: bool, //! # } //! 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`](crate::Runtime), which we'll do now: //! //! ```no_run //! # use glyph_ui::{ //! # prelude::*, //! # event::Event, //! # view::{ //! # prelude::*, //! # text, //! # }, //! # }; //! # use keyboard_types::Key; //! # struct HelloWorld { //! # shutdown: bool, //! # } //! # impl Gui for HelloWorld { //! # type Message = bool; //! # type Event = (); //! # fn view(&mut self) -> element::View<Self::Event, Self::Message> { //! # text::new("Hello, world!") //! # .on_event(|e, _f| { //! # if let Event::Key(k) = e { //! # if let Key::Character(c) = &k.key { //! # if c == "q" { //! # return Box::new(std::iter::once(true)); //! # } //! # } //! # } //! # Box::new(std::iter::empty()) //! # }) //! # .into_element() //! # } //! # fn update(&mut self, m: Self::Message) { //! # self.shutdown = m; //! # } //! # fn control_flow(&self) -> ControlFlow { //! # if self.shutdown { //! # ControlFlow::Exit //! # } else { //! # ControlFlow::Wait //! # } //! # } //! # } //! #[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](https://forge.typ3.tech/charles/glyph_ui/-/tree/master/examples). use std::sync::Arc; use parking_lot::Mutex; mod command; pub mod event; mod gui; mod printer; mod runtime; pub mod unit; pub mod view; mod view_trait; /// Prelude for commonly used items pub mod prelude { pub use crate::{view::element, ControlFlow, Gui, Runtime}; } pub use gui::Gui; pub use printer::{OutOfBounds, Printer}; pub use runtime::{ControlFlow, Runtime}; pub use view_trait::View; pub(crate) type Amv<T> = Arc<Mutex<Vec<T>>>; pub(crate) type Am<T> = Arc<Mutex<T>>; pub(crate) use command::{Command, CommandBuf};