TWins in brief

TWins is a C++ library designed for easy creation of visual terminal applications on non-os platforms, like bare Cortex-M3. It provides basic facilities required by interactive applications such as screen and cursor management, keyboard input, keymaps, color codes. User can also define terminal windows and it's widgets in a convenient way as const tree of twins::Widget structures.

References

Implementation is based on examples:

• https://github.com/fidian/ansi/blob/master/ansi - great bash script providing most of the codes for terminal use
• https://github.com/stark/Color-Scripts
• https://wiki.bash-hackers.org/scripting/terminalcodes
• http://0x80.pl/articles/terminals.html
• https://www.jedsoft.org/slang/
• https://www.systutorials.com/docs/linux/man/4-console_codes/#lbAF
• https://rdrr.io/cran/fansi/man/sgr_to_html.html
• Wiki: reference color tables for different terminals

Primary goals

• text properties
  • foreground and background color codes
  • attributes (bold, inversion)
• operations
  • clear screen
  • go to home
  • go to location
• reading input
  • regular characters (a..z)
  • control codes (Up/Down, Del, Ctrl, Home, ...)
• buffered terminal output
• platform abstraction layer (PAL) to ease porting
• make it compile in clang
• command line interface with history (CLI)

Secondary goals

• widgets (controls) to implement
  • window
  • panel
  • static label / led
  • check box
  • edit field (text/number)
  • radio button
  • page control
  • progress bar
  • list box
  • combo box
  • scrollable text box
  • custom widget base
  • scrollbar
  • horizontal page control
  • popup windows
  • layers - to control visibility of groups of widgets
  • password input
• navigation
  • widgets navigation by Tab/Esc key
  • render focused widget state
  • blinking cursor instead of inversed colors
  • select widget by mouse
• notifications
  • notify event per widget type (button clicked, checkbox toggled)
• color theme for window
• keyboard handler returns if key was handled by active widget
• support for mouse click
• double-width character support (emoticons 😁)
• multiline solid button

Prerequisites

Library is using C++14 and reguires gcc 7.5 or never.

sudo apt install g++ cmake cmake-curses-gui

How to build demo

Project is CMake-based and contains two targets: TWinsDemo and TWinsUT.
Tests are enabled by default, Demo has to be enabled from commandline or in ccmake ..

mkdir build && cd build
cmake -DTWINS_BUILD_DEMO=ON -DTWINS_THEME_DIR="../demo/inc/" ..
make -j

Run GUI demo:

./bin/TWinsDemo

Run CLI demo:

./bin/TWinsDemo --cli

How to build unit tests

TWins tests are using google test library as a submodule. The first step is to fetch the library:

cmake -DTWINS_BUILD_UT=ON ..
git submodule update --init

You can also turn on building of the tests with ccmake:
Go to build/ and use ccmake . to turn on TWINS_BUILD_UT.
Press c -> c -> g to reconfigure build scripts

Build and run the tests

make -j
ctest -V

If you have gcovr installed, after running tests you can generate test coverage HTML report

make twins_cov_only
firefox cover_html/cover.html

---