illwill is a (n)curses inspired simple terminal library that aims to make writing cross-platform text mode applications easy. Having said that, it's much simpler than (n)curses and it's not as robust by far in terms of supporting different encodings, terminal types, etc. The aim was to write something small and simple in pure Nim that works for 99% of users without requiring any external dependencies or a terminfo database.
For "serious" applications, the best is always to write different backends for *nix and Windows (one of the main reasons being that the Windows Console is buffer based, not file based). But I think this library is perfect for small cross-platform programs and utilities where you need something more than the basic blocking console I/O, but you don't actually want to bother with a full-blown GUI.
cmd.exe
) and most common POSIX terminals.nim-mod is an oldschool MOD player that uses illwill for its awesome text-mode user interface
The best way to install the library is by using nimble:
nimble install illwill
https://www.johnnovak.net/illwill/
This is a simple example on the general structure of a fullscreen terminal application. Check out the examples for more advanced use cases (e.g. using box drawing buffers, handling terminal resizes, etc.)
import os, strutils
import illwill
# 1. Initialise terminal in fullscreen mode and make sure we restore the state
# of the terminal state when exiting.
proc exitProc() {.noconv.} =
illwillDeinit()
showCursor()
quit(0)
illwillInit(fullscreen=true)
setControlCHook(exitProc)
hideCursor()
# 2. We will construct the next frame to be displayed in this buffer and then
# just instruct the library to display its contents to the actual terminal
# (double buffering is enabled by default; only the differences from the
# previous frame will be actually printed to the terminal).
var tb = newTerminalBuffer(terminalWidth(), terminalHeight())
# 3. Display some simple static UI that doesn't change from frame to frame.
tb.setForegroundColor(fgBlack, true)
tb.drawRect(0, 0, 40, 5)
tb.drawHorizLine(2, 38, 3, doubleStyle=true)
tb.write(2, 1, fgWhite, "Press any key to display its name")
tb.write(2, 2, "Press ", fgYellow, "ESC", fgWhite,
" or ", fgYellow, "Q", fgWhite, " to quit")
# 4. This is how the main event loop typically looks like: we keep polling for
# user input (keypress events), do something based on the input, modify the
# contents of the terminal buffer (if necessary), and then display the new
# frame.
while true:
var key = getKey()
case key
of Key.None: discard
of Key.Escape, Key.Q: exitProc()
else:
tb.write(8, 4, ' '.repeat(31))
tb.write(2, 4, resetStyle, "Key pressed: ", fgGreen, $key)
tb.display()
sleep(20)
Copyright © 2018-2024 John Novak <john@johnnovak.net>
This work is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See the COPYING file for more details.