235 lines
8.1 KiB
Markdown
235 lines
8.1 KiB
Markdown
# tim
|
|
Fork of https://codeberg.org/chuvok/tim.h
|
|
|
|
## about
|
|
tim is a portable library to create simple terminal applications
|
|
Demo video: https://asciinema.org/a/zn3p0dsVCOQOzwY1S9gDfyaxQ
|
|
|
|
## build
|
|
1. Clone this repository.
|
|
```
|
|
git clone https://timerix.ddns.net/git/Timerix/tim.git
|
|
```
|
|
|
|
2. Install [cbuild](https://timerix.ddns.net/git/Timerix/cbuild/releases).
|
|
Select latest version compatible with the one in `project.config`.
|
|
Example: For `2.3.2` download latest `2.3.x`.
|
|
|
|
3. Build static library
|
|
```
|
|
cd tim
|
|
cbuild build_static_lib
|
|
```
|
|
4. Build tests and examples
|
|
```
|
|
cbuild ask hello snek test color string
|
|
```
|
|
|
|
## quick start
|
|
See [example/hello.c](./example/hello.c)
|
|
|
|
## layout
|
|
The terminal's columns (x) and rows (y) are addressed by their coordinates,
|
|
the origin is in the top left corner.
|
|
|
|
Scopes are the primary layout mechanism. They are used to group and place
|
|
multiple elements. Scopes can be nested.
|
|
|
|
The root scope is the full terminal screen. The scope macro is constructed
|
|
with a for loop, so statements like break or return inside the scope block
|
|
will probably give you a bad time.
|
|
|
|
Elements (widget, control, component) are elements of user interaction, such
|
|
as a button or edit box. Most elements take x/y/w/h arguments to control
|
|
placement. All positions are given in relation the element's parent scope.
|
|
|
|
Automatic (A) width and height are either based on the element's content, or
|
|
take the full available space from parent.
|
|
|
|
arg | value | placement
|
|
-----|-------|---------------------------------
|
|
x | n | n columns to left
|
|
x | ~n | n columns to right
|
|
x | A | center horizontally
|
|
y | n | n rows to top
|
|
y | ~n | n rows to bottom
|
|
y | A | center vertically
|
|
w | n | n columns wide
|
|
w | ~n | fit width to n columns to right
|
|
w | A | automatic width
|
|
h | n | n rows high
|
|
h | ~n | fit height n rows to bottom
|
|
h | A | automatic height
|
|
|
|
The layout automatically adopts to terminal window resize events.
|
|
|
|
## colors
|
|
Colors are stored as 8-bit values.
|
|
Most terminals support 16 ANSI colors. You can see them in TimColor16 enum.
|
|
It's better to use xterm256 colors istead, because ANSI colors look different in each terminal.
|
|
https://www.ditig.com/256-colors-cheat-sheet
|
|
|
|
|
|
## events
|
|
tim_run blocks until it observes an event. Mouse and key events are always
|
|
immediately followed by a draw event in order to make changes visible.
|
|
|
|
Some elements need to consume events, for example edit consumes the key
|
|
event when focused in order to prevent other key handlers on acting on them.
|
|
|
|
The current event is stored in tim->event.
|
|
|
|
## elements
|
|
frame (x, y, w, h, color)
|
|
|
|
Draw an empty frame and fill area.
|
|
|
|
x/y/w/h see layout documentation
|
|
style background, frame
|
|
|
|
label (str, x, y, w, h, color)
|
|
|
|
Draw text label. Automatic width and height are supported. Strings
|
|
exceeding width or height are clipped.
|
|
|
|
str zero terminated string
|
|
x/y/w/h see layout documentation
|
|
style background, text
|
|
|
|
button (str, x, y, w, h, color) -> bool
|
|
|
|
Draw button. Automatic width and height are supported. Strings exceeding
|
|
width or height are clipped. Returns true when clicked.
|
|
|
|
str zero terminated string
|
|
x/y/w/h see layout documentation
|
|
style frame, background, text
|
|
|
|
edit (state, x, y, w, color) -> int
|
|
|
|
Draw text edit. Output is stored in state.s.
|
|
Receives input events when focused by mouse click or by setting focus manually.
|
|
Escape or return relinquish focus.
|
|
Returns key id if received key input.
|
|
|
|
state pointer to persistent edit state struct
|
|
x/y/w see layout documentation
|
|
style f rame, background, text
|
|
|
|
check (str, state, x, y, w, color) -> bool
|
|
|
|
Draw check box. State determines how the box is checked. [x] when state
|
|
is non-zero, [ ] when state is zero, [-] when state is -1. A mouse click
|
|
toggles the state between one and zero and returns true.
|
|
|
|
str zero terminated string
|
|
state pointer to persistent state variable
|
|
x/y/w see layout documentation
|
|
style check, background, text
|
|
|
|
radio (str, state, v, x, y, w, color) -> bool
|
|
|
|
Draw radio box. If state equals v, the box is selected. Radios are
|
|
grouped through a shared state. Within that group, each v must be unique.
|
|
A mouse click assigns v to state and returns true.
|
|
|
|
str zero terminated string
|
|
state pointer to persistent state variable
|
|
v unique state value
|
|
x/y/w see layout documentation
|
|
style radio, background, text
|
|
|
|
## functions
|
|
tim_run (fps) -> bool
|
|
|
|
Process events and render frame. Blocks until input is received or the
|
|
next frame is due. First call also initializes the terminal. When fps is
|
|
zero the function blocks until input is received. Key and mouse events
|
|
are immediately followed by a draw event, so the actual fps can be
|
|
significantly greater than requested. Always returns true. To reset the
|
|
terminal after a crash, run "reset".
|
|
The Ctrl-C interrupt is masked, so make sure to put an exit condition
|
|
like this at the end of the main loop:
|
|
|
|
if (tim_is_key_press(ESCAPE_KEY))
|
|
exit(0);
|
|
|
|
fps frames per second
|
|
|
|
tim_is_key_press (key) -> bool
|
|
|
|
Returns true if key was pressed.
|
|
|
|
key char literal or one of the KEY constants, see constants
|
|
|
|
tim_time_usec () -> int64
|
|
|
|
Returns monotonic clock value in microseconds. Not affected by summer
|
|
time or leap seconds.
|
|
|
|
## useful links
|
|
https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
|
|
https://learn.microsoft.com/en-us/windows/console/
|
|
|
|
## bugs
|
|
- Double buffering is still new, set ENABLE_DBUF to 0 if you see glitches
|
|
- Double width characters like 彁 are not fully supported. Terminals do not
|
|
handle these consistently and there is no portable way to reliably
|
|
determine character width. The renderer can deal with some of the problems
|
|
caused by this, but results may vary.
|
|
- Decomposed (NFD) UTF-8 is not supported and will cause havoc
|
|
- Zero width code points are not supported
|
|
- Windows cmd.exe resize events may be delayed
|
|
|
|
## compatibility
|
|
emulator | support | remarks
|
|
------------------|---------|----------------------------------
|
|
Alacritty | ? |
|
|
cmd.exe | good | resize may lag
|
|
Cool Retro Term | good | wide character spill
|
|
Deepin Terminal | good | wide character spill
|
|
Eterm | abysmal | garbled output
|
|
GNOME Terminal | full |
|
|
GNUstep Terminal | abysmal | garbled output
|
|
iTerm2 | ? |
|
|
kitty | full |
|
|
Konsole | full |
|
|
LXTerminal | full |
|
|
macOS Terminal | ? |
|
|
PuTTY | full |
|
|
QTerminal | good | wide character spill
|
|
rxvt-unicode | full |
|
|
GNU Screen | good | no alternate buffer, double esc
|
|
st | full |
|
|
Terminator | full |
|
|
Terminology | full |
|
|
tmux | good | esc lags
|
|
Windows Terminal | full |
|
|
Xfce Terminal | full |
|
|
XTerm | full | XTerm is law
|
|
Zutty | full |
|
|
|
|
## license
|
|
MIT License
|
|
|
|
Copyright (c) MMXXIV Chu'vok <chuvok@maeppi.e4ward.com>
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the "Software"), to deal
|
|
in the Software without restriction, including without limitation the rights
|
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
copies of the Software, and to permit persons to whom the Software is
|
|
furnished to do so, subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included in
|
|
all copies or substantial portions of the Software.
|
|
|
|
The software is provided "as is", without warranty of any kind, express or
|
|
implied, including but not limited to the warranties of merchantability,
|
|
fitness for a particular purpose and noninfringement. In no event shall the
|
|
authors or copyright holders be liable for any claim, damages or other
|
|
liability, whether in an action of contract, tort or otherwise, arising from,
|
|
out of or in connection with the software or the use or other dealings in the
|
|
software.
|
|
|