# 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 ## 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 Most elements have a uint64 color argument which holds up to eight colors. Typically byte 0 is the text color and byte 1 is the background color. For example 0x08040f encodes three colors. When used with a button the text is white (0f), the background is blue (04), and the frame is gray (08). The terminal should support xterm-256 colors. The TERM variable is ignored. The lower 16 colors vary across different terminals, so the upper 240 colors should be used if consistency is important. xterm-256 color chart https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg ## 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. event | cause -------------|----------------------- DRAW_EVENT | input, timeout, resize KEY_EVENT | key press MOUSE_EVENT | mouse click VOID_EVENT | consumed event ## elements frame (x, y, w, h, color) Draw an empty frame and fill area. x/y/w/h see layout documentation color 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 color 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 color 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 color 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 color 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 color 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 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.