The goal is to make TUI creation fast & simple by providing sufficient documentation with many boiled down examples that will allow developers to focus on their application's logic instead of having to think too much about presentation layer annoyances.
Inspired by this post I decided that as my first more serious project written in Rust I will try to create a generic library for terminal user interface management.
By making your programs more user-friendly you have a higher chance of growing a happy user base of utilities you create.
Allowing users customizing the look and feel of those solutions with community driven skins/themes and keybindings makes it more likely people will stay attached to those apps.
This library uses termios as it's only dependency, which allows you to use it on multiple OSes.
Graphic objects can be defined and loaded as a plaintext file. Graphic's building blocks - frames are also text files, with optional ANSI escape codes that allow using colors and various styles.
Internally rendering is being served on a separate thread, so waiting for a key press does not make any difference to animation playback.
Attached studio app is a working proof this library does work. It can be used by non-programmers so that people more design focused can help with user interface's look and feel.
In order to use this library, you need to create a [Manager]:
```no_run
use animaterm::prelude::*;
use std::time::Duration;
let capturekeyboard = true;
let cols = Some(40);
let rows = None; // use all rows available
let glyph = Some(Glyph::default()); // initially fill the screen with this
// You can crank refreshtimeout down, but anything below 1ms won't make a difference,
// other than high CPU usage.
// With default 30ms you get as high as 33 FPS, probably enough for a terminal application.
let refreshtimeout = Some(Duration::frommilis(10));
let mut mgr = Manager::new(capturekeyboard, cols, rows, glyph, refreshtimeout);
```
Please also note that in order to see the progress you are making with this library you need to keep your program running, since animaterm makes use of an alternate terminal buffer. After your program finishes you go back to original buffer, wiping out all the graphics you have placed on the screen so far.
In order to keep your program running you can use a loop like this: ```norun let mut keeprunning = true; while keeprunning { if let Some(key) = mgr.readkey() { match key { Key::Q | Key::ShiftQ => { keep_running = false; } _ => continue } } } mgr.terminate();
```
With mgr under your control you can do all kinds of things:
* create a [Graphic] containing multiple frames with fully adjustable [Color] and [Glyph] - see example;
* add an [Animation] to a [Graphic] and run it - see example;
* take action according to [Key] press - see example;
* change Frame or [Animation] of displayed [Graphic] to a different one - see example1 or example2;
* pause selected [Animation] on selected Frame - see example;
* switch back and forth between multiple [Display] instances - see example;
* stack [Graphic] over or under others on a [Display] with layer change - see example;
* move [Graphic] up/down/left/right on a [Display] - see example;
* update selected [Glyph] within existing Frame of a [Graphic] - see example;
* make parts of a [Graphic] transparent by changing [Glyph] property - see example;
* add cloned or completely new Frame to [Graphic] - see example1 or example_2;
* and more.
Please also check the examples directory for working examples of how to use this library.
``` let cols = 10; let rows = 5; let startframe = 0; let mut library = HashMap::withcapacity(2);
library.insert( startframe, vec![Glyph::default(); rows * cols]); library.insert( startframe+1, vec![Glyph::plain(); rows * cols]); let animations = None; let mut gr = Graphic::new(cols, rows, start_frame, library, animations);
let layer = 0; let offset = (15, 5); let graphicid = mgr.addgraphic(gr, layer, offset).unwrap(); mgr.setgraphic(graphicid, start_frame); ```
``` // You can define some animations upon creation of a graphic: let running = false; let looping = true; let seconds = 0; let miliseconds = 500; let ordering = vec![ (startframe, Timestamp::new(seconds, miliseconds)), (startframe + 1, Timestamp::new(seconds, miliseconds)), ]; let starttime = Timestamp::now(); let animation = Animation::new(running, looping, ordering, starttime); let mut animations = HashMap::new(); let animid = 0; animations.insert(animid, animation);
let mut gr = Graphic::new(cols, rows, start_frame, library, Some(animations));
// Or add a new animation to existing graphic let optionanimid = gr.addanimation(Animation::new(running, looping, ordering, starttime));
// You can even create additional animation via a manager mgr.addanimation( graphicid, Animation::new(running, looping, ordering, Timestamp::now()), );
let mut varanimid = None; if let Ok(AnimOk::AnimationAdded(animid)) = mgr.readresult() { varanimid = Some(anim_id); } ```
For more agile solution allowing user-defined key bindings see how studio implements user input loop.
let mut keep_running = true;
while keep_running {
if let Some(key) = mgr.read_key() {
match key {
Key::Left => mgr.move_graphic(graphic_id, layer, (-1, 0)),
Key::Right => mgr.move_graphic(graphic_id, layer, (1, 0)),
Key::Up => mgr.move_graphic(graphic_id, layer, (0, -1)),
Key::Down => mgr.move_graphic(graphic_id, layer, (0, 1)),
Key::Q | Key::ShiftQ => {
keep_running = false;
}
_ => continue,
}
}
}
mgr.terminate();
// Use force wisely, since it causes entire screen to be refreshed,
// thus app is becoming less responsive.
let force = true;
mgr.set_graphic(graphic_id, frame_id, force)
mgr.start_animation(graphic_id, anim_id);
``` //You can pause immediately mgr.pauseanimation(graphicid);
//You can pause on a selected frame mgr.pauseanimationonframe(graphicid, frame_id); ```
let keep_existing = true;
let second_display_id = mgr.new_display(keep_existing);
// default display has id = 0
mgr.restore_display(0, keep_existing);
mgr.move_graphic(graphic_id, new_layer, (0, 0));
mgr.move_graphic(graphic_id, layer, (offset_cols, offset_rows));
``` // Change a Glyph for a selected Frame agraphic.setframe(frameid); agraphic.setglyph(newglyph, col, row, graphic_offset);
// Change a Glyph for current Frame of an on Screen Graphic mgr.setglyph(graphicid, new_glyph, col, row); ```
``` // Make a transparent Glyph for a selected Frame agraphic.setframe(frameid, graphicoffset); agraphic.setglyph(Glyph::transparent(), col, row, graphic_offset);
// Change a Glyph to transparent for current Frame of an on Screen Graphic mgr.setglyph(graphicid, Glyph::transparent(), col, row, graphic_offset)); ```
``` // In both cases empty Frame becomes current for that Graphic
// if sourceframeid is None current Frame will get cloned let sourceframeid = Some(id);
// Add a new Frame to a graphic directly let frameidoption = agraphic.cloneframe(sourceframeid);
// Or use a Manager to do so mgr.cloneframe(graphicid); if let Ok(AnimOk::FrameAdded(graphicid, frameid)) = mgr.readresult() { let addedframeid = frameid; } ```
``` // In both cases empty Frame becomes current for that Graphic
// Add a new Frame to a graphic directly let frameidoption = agraphic.emptyframe();
// Or use a Manager to do so mgr.emptyframe(graphicid); if let Ok(AnimOk::FrameAdded(graphicid, frameid)) = mgr.readresult() { let addedframeid = frameid; } ```