diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 8bbaa5ede..dc8c4a108 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -59,10 +59,9 @@ - [FAQ](./faq/README.md) - - [Duplicate key events on Windows](./faq/duplicate-key-events-windows.md) + - [Duplicate key events](./faq/duplicate-key-events-windows.md) - [`tokio` / `async`](./faq/tokio-async.md) - [`tui.rs` history](./faq/tui-rs-history.md) - - [`ratatui` vs `tui-realm`](./faq/ratatui-vs-tui-realm.md) # Reference diff --git a/src/faq/README.md b/src/faq/README.md index 4d678b600..cefd256f3 100644 --- a/src/faq/README.md +++ b/src/faq/README.md @@ -1,6 +1,81 @@ # FAQ -- [Duplicate key events](./duplicate-key-events-windows.md) +- [Duplicate Key Events on Windows](./duplicate-key-events-windows.md) - [`tokio` / `async`](./tokio-async.md) - [`tui.rs` history](./tui-rs-history.md) -- [`ratatui` vs `tui-realm`](./ratatui-vs-tui-realm.md) + +## What is the difference between a library and a framework? + +The terms library and framework are often used interchangeably in software development, but they +serve different purposes and have distinct characteristics. + +| | Library | Framework | +| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Usage** | A library is a collection of functions and procedures that a programmer can call in their application. The library provides specific functionality, but it's the developer's responsibility to explicitly call and use it. | A framework is a pre-built structure or scaffold that developers build their application within. It provides a foundation, enforcing a particular way of creating an application. | +| **Control Flow** | In the case of a library, the control flow remains with the developer's application. The developer chooses when and where to use the library. | With a framework, the control flow is inverted. The framework decides the flow of control by providing places for the developer to plug in their own logic (often referred to as "Inversion of Control" or IoC). | +| **Nature** | Libraries are passive in nature. They wait for the application's code to invoke their methods. | Frameworks are active and have a predefined flow of their own. The developer fills in specific pieces of the framework with their own code. | +| **Example** | Imagine you're building a house. A library would be like a toolbox with tools (functions) that you can use at will. You decide when and where to use each tool. | Using the house-building analogy, a framework would be like a prefabricated house where the main structure is already built. You're tasked with filling in the interiors and decor, but you have to follow the design and architecture already provided by the prefabricated design. | + +## What is the difference between a `ratatui` (a library) and a `tui-realm` (a framework)? + +While `ratatui` provides tools (widgets) for building terminal UIs, it doesn't dictate or enforce a +specific way to structure your application. You need to decide how to best use the library in your +particular context, giving you more flexibility. + +In contrast, `tui-realm` might provide more guidelines and enforcements about how your application +should be structured or how data flows through it. And, for the price of that freedom, you get more +features out of the box with `tui-realm` and potentially lesser code in your application to do the +same thing that you would with `ratatui`. + +## Can you change font size in a terminal using `ratatui`? + +`ratatui` itself doesn't control the terminal's font size. `ratatui` renders content based on the +size and capabilities of the terminal it's running in. If you want to change the font size, you'll +need to adjust the settings of your terminal emulator. + +![](https://user-images.githubusercontent.com/1813121/269147939-0ed031f2-1977-4e92-b4b4-6c217d02e79b.png) + +However, changing this setting in your terminal emulator will only change the font size for you +while you are developing your `ratatui` based application. + +When a user zooms in and out using terminal shortcuts, that will typically change the font size in +their terminal. You typically will not know what the terminal font size is ahead of time. + +However, you can know the current terminal size (i.e. columns and rows). Additionally, when zooming +in and out `ratatui` applications will see a terminal resize event that will contain the new columns +and rows. You should ensure your `ratatui` application can handle these changes gracefully. + +You can detect changes in the terminal's size by listening for terminal resize events from the +backend of your choice and you can adjust your application layout as needed. + +For example, here's how you might do it in +[crossterm](https://docs.rs/crossterm/0.27.0/crossterm/event/enum.Event.html#variant.Resize): + +```rust + match crossterm::terminal::read() { + Ok(evt) => { + match evt { + crossterm::event::Event::Resize(x, y) => { + // handle resize event here + }, + _ => {} + } + } + } +``` + +```admonish tip +Since this can happen on the user end without your control, this means that you'll have to design +your `ratatui` based terminal user interface application to display content well in a +number of different terminal sizes. +``` + +`ratatui` does support various styles, including bold, italic, underline, and more, and while this +doesn't change the font size, it does provide you with the capability to emphasize or de-emphasize +text content in your application. + +Additionally you can use [`figlet`](https://docs.rs/figlet-rs/latest/figlet_rs/) or +[`tui-big-text`](https://github.com/joshka/tui-big-text/) to display text content across multiple +lines. Here's an example using [`tui-big-text`](https://github.com/joshka/tui-big-text/): + +![[tui-big-text](https://github.com/joshka/tui-big-text/)](https://camo.githubusercontent.com/3a738ce21da3ae67660181538ef27473b86bebca73f42944e8012d52f86e500d/68747470733a2f2f7668732e636861726d2e73682f7668732d3364545474724c6b79553534684e61683232504152392e676966) diff --git a/src/faq/duplicate-key-events-windows.md b/src/faq/duplicate-key-events-windows.md index 8d6885a04..a43c59c45 100644 --- a/src/faq/duplicate-key-events-windows.md +++ b/src/faq/duplicate-key-events-windows.md @@ -1,5 +1,7 @@ # Why am I getting duplicate key events on Windows? +{{#title Duplicate key events on Windows}} + A lot of examples out there in the wild might use the following code for sending key presses: ```rust diff --git a/src/faq/ratatui-vs-tui-realm.md b/src/faq/ratatui-vs-tui-realm.md deleted file mode 100644 index 2a5ce39c3..000000000 --- a/src/faq/ratatui-vs-tui-realm.md +++ /dev/null @@ -1,42 +0,0 @@ -# `ratatui` vs `tui-realm` - -Fundamentally, the difference is that **`ratatui` is a library** but -**[`tui-realm`](https://github.com/veeso/tui-realm/) is a framework**. - -The terms library and framework are often used interchangeably in software development, but they -serve different purposes and have distinct characteristics. - -## Library - -- **Usage**: A library is a collection of functions and procedures that a programmer can call in - their application. The library provides specific functionality, but it's the developer's - responsibility to explicitly call and use it. -- **Control Flow**: In the case of a library, the control flow remains with the developer's - application. The developer chooses when and where to use the library. -- **Passivity**: Libraries are passive in nature. They wait for the application's code to invoke - their methods. -- **Example**: Imagine you're building a house. A library would be like a toolbox with tools - (functions) that you can use at will. You decide when and where to use each tool. - -## Framework - -- **Usage**: A framework is a pre-built structure or scaffold that developers build their - application within. It provides a foundation, enforcing a particular way of creating an - application. -- **Control Flow**: With a framework, the control flow is inverted. The framework decides the flow - of control by providing places for the developer to plug in their own logic (often referred to as - "Inversion of Control" or IoC). -- **Activeness**: Frameworks are active and have a predefined flow of their own. The developer fills - in specific pieces of the framework with their own code. -- **Example**: Using the house-building analogy, a framework would be like a prefabricated house - where the main structure is already built. You're tasked with filling in the interiors and decor, - but you have to follow the design and architecture already provided by the prefabricated design. - -While `ratatui` provides tools (widgets) for building terminal UIs, it doesn't dictate or enforce a -specific way to structure your application. You need to decide how to best use the library in your -particular context, giving you more flexibility. - -In contrast, `tui-realm` might provide more guidelines and enforcements about how your application -should be structured or how data flows through it. And, for the price of that freedom, you get more -features out of the box with `tui-realm` and potentially lesser code in your application to do the -same thing that you would with `ratatui`. diff --git a/src/faq/tokio-async.md b/src/faq/tokio-async.md index 237dedff5..362d52456 100644 --- a/src/faq/tokio-async.md +++ b/src/faq/tokio-async.md @@ -2,16 +2,16 @@ `ratatui` isn't a native `async` library. So is it beneficial to use `tokio` or `async`/`await`? -And as a user, there really is only one point of interface with the `ratatui` library and that's the -`terminal.draw(|f| ui(f))` functionality, because the rendering of widgets happens in `ui(f)`. -Everything else in your code is your own to do as you wish. +As a user of `rataui`, there really is only one point of interface with the `ratatui` library and +that's the `terminal.draw(|f| ui(f))` functionality (the creation of widgets provided by `ratatui` +typically happens in `ui(f)`). Everything else in your code is your own to do as you wish. Should `terminal.draw(|f| ui(f))` be `async`? Possibly. Rendering to the terminal buffer is relatively fast, especially using the double buffer technique that only renders diffs that `ratatui` -uses. +uses. Creating of the widgets can also be done quite efficiently. -Can we make it `async` ourselves? Yes, we can. Check out - for an example. +So one question you may ask is can we make `terminal.draw(|f| ui(f))` `async` ourselves? Yes, we +can. Check out for an example. The only other part related to `ratatui` that is beneficial to being `async` is reading the key event inputs from `stdin`, and that can be made `async` with `crossterm`'s event-stream. @@ -37,6 +37,11 @@ Another way to think about it is, do you think your app would work better with 1 `--------' ``` +```admonish note +Even with the above architecture, you can use tokio to spawn tasks during `Update State`, +and follow up on the work done by those tasks in the next iteration. +``` + Or would it work with 3 threads / `tokio` tasks like this: ```svgbob @@ -63,5 +68,8 @@ Or would it work with 3 threads / `tokio` tasks like this: `------------------' ┊ ┊ `------------------' ``` +In your `main` thread or `tokio` task, do you expect to be spawning more `tokio` tasks? How many +more tasks do you plan to be spawning? + The former can be done without any `async` code and the latter is the approach showcased in [`ratatui-async-template`](https://github.com/ratatui-org/ratatui-async-template) with `tokio`.