- Rust 100%
| nrustes | Correctly handle text input events when using SDL backends | |
| pictures | Forgot this | |
| .gitignore | Created workspace with nrustes and nrustes_derive | |
| Cargo.toml | Update to edition 2024 | |
| LICENSE.txt | Define a workspace package | |
| nrustes_config.ron | Fix some typos | |
| README.md | Update the README | |
| rustfmt.toml | cargo fmt | |
nrustes
Welcome!
nrustes is a wrapper around other libraries to facilitate the creation of "terminal-like" programs.
Its main goals are:
- To facilitate the creation of programs that have a "terminal-like" appearance.
- To internally support many libraries (backends).
- To expose a common API that allows effortlessly switching between its backends.
- To have nice defaults.
- To be somewhat opinionated.
- To be simple - maybe too much to be useful for some use cases.
- To be efficient enough.
Examples
There are some examples. I should add more.
For more advanced examples check dastan: a game I'm creating using nrustes.
Add it to your project
Add nrustes to your Cargo.toml:
[dependencies.nrustes]
git = "https://codeberg.org/bespinas/nrustes.git"
Read the section about "Backends" to know about the features you can enable.
Main features
Print text
Print text with foreground and background colors of your choosing.
Use absolute coordinates or coordinates relative to a container.
Read keyboard input
Read key presses that are not displayed and don't require pressing Enter.
Also read text input that is displayed while being entered and obtained when pressing Enter.
Scrollable list
Create containers that render a list of items that can be scrolled.
If there are too many items to display at once, the list will be paginated.
Paginated text
Create containers that render text that is paginated if it doesn't fit at once.
Popup dialogs
Display some types of dialogs.
If something fails or cannot be done, you can display a popup with an error message:
While something is being processed, you can display a popup that can be updated and dismissed once done:
Modal dialogs
Get user input through auxiliar containers.
Forms
Create forms with different types of fields and requirements.
Forms support these types of fields:
- Text
- Natural numbers
- Whole numbers
- Integer numbers
- Real numbers
- A choice between some options
Fields can be either optional or required.
Views
Dealing with only one container is simple: when displaying a popup on top of it, darken it; when dismissing that popup, redraw it.
When multiple containers are involved, having to handle everything can be complex. Following with the example above, multiple containers have to be darkened and redrawn when displaying a single popup.
Views attempt to make this management easier: they group containers and allow having to worry about a single thing. When displaying a popup, the whole view can be darkened at once, for example, without having to worry about individual containers.
Currently, there are these main types of views:
- Mono views: with a single container
- Dual views: with two containers
There are some available presets based on them:
- A scrollable list to the left with a simple window to the right
- A scrollable list to the left with a paginated window to the right
- A form to the left with a simple window to the right
The idea is to have presets for common types of views. You can create your own views yourself!
Double view: scrollable and window
Double view: scrollable and scrollbar
Render graphics
Custom fonts
This is not an nrustes feature but something you can do if you'd like to have something like sprites when you can only render text.
"Terminal" backends (crossterm, termion) can only render text.
You can design your own font and replace characters that you don't need with your own creations.
Play with foreground and background colors.
For example: if you are creating a game, 'ç' could be a healing potion, 'È' could be a cow... :)
This requires creating a font and distributing it. Your users would have to download, install and configure your font in their terminal to run your program.
Sprites
Some backends (sdl2, sdl3) can render text and images.
nrustes exposes tools for these backends to load texture atlasses, configure the size of the sprites, render them...
You can render text and sprites at the same time, each with different sizes.
Main missing features
There are some features I don't plan to support. At least for now, but who knows.
- Mouse support: not needed by my use cases, and I'd like to explore what can be done with keyboard-driven interfaces.
- Animations: not needed by my use cases.
Backends
There are many available backends, all enabled by default.
You can choose which to enable through cargo features.
crossterm
features = [ "crossterm_backend" ]
It uses the crossterm crate.
termion
features = [ "termion_backend" ]
It uses the termion crate.
sdl2
features = [ "sdl2_backend" ]
It uses the sdl2 crate.
Install any missing dependencies cargo complains about not having. You'll probably need to install development packages for SDL2 image and SDL2 ttf.
See the crate's documentation for instructions on how to let cargo build SDL2 from source and use it so that you don't have to rely on your distribution's package repository.
sdl3
features = [ "sdl3_backend" ]
It uses the sdl3 crate.
Install any missing dependencies cargo complains about not having. You'll probably need to install development packages for SDL3-image and SDL3-ttf.
See the crate's documentation for instructions on how to let cargo build SDL3 from source and use it so that you don't have to rely on your distribution's package repository.