diff options
Diffstat (limited to 'v_windows/v/vlib/term/ui/README.md')
| -rw-r--r-- | v_windows/v/vlib/term/ui/README.md | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/v_windows/v/vlib/term/ui/README.md b/v_windows/v/vlib/term/ui/README.md new file mode 100644 index 0000000..6bce054 --- /dev/null +++ b/v_windows/v/vlib/term/ui/README.md @@ -0,0 +1,99 @@ +## `term.ui` + +A V module for designing terminal UI apps + +#### Quickstart + +```v +import term.ui as tui + +struct App { +mut: + tui &tui.Context = 0 +} + +fn event(e &tui.Event, x voidptr) { + mut app := &App(x) + println(e) + if e.typ == .key_down && e.code == .escape { + exit(0) + } +} + +fn frame(x voidptr) { + mut app := &App(x) + + app.tui.clear() + app.tui.set_bg_color(r: 63, g: 81, b: 181) + app.tui.draw_rect(20, 6, 41, 10) + app.tui.draw_text(24, 8, 'Hello from V!') + app.tui.set_cursor_position(0, 0) + + app.tui.reset() + app.tui.flush() +} + +mut app := &App{} +app.tui = tui.init( + user_data: app + event_fn: event + frame_fn: frame + hide_cursor: true +) +app.tui.run() ? +``` + +See the `/examples/term.ui/` folder for more usage examples. + +#### Configuration + +- `user_data voidptr` - a pointer to any `user_data`, it will be passed as the last argument to + each callback. Used for accessing your app context from the different callbacks. +- `init_fn fn(voidptr)` - a callback that will be called after initialization + and before the first event / frame. Useful for initializing any user data. +- `frame_fn fn(voidptr)` - a callback that will be fired on each frame, + at a rate of `frame_rate` frames per second. +`event_fn fn(&Event, voidptr)` - a callback that will be fired for every event received. +- `cleanup_fn fn(voidptr)` - a callback that will be fired once, before the application exits. +- `fail_fn fn(string)` - a callback that will be fired + if a fatal error occurs during app initialization. +- `buffer_size int = 256` - the internal size of the read buffer. + Increasing it may help in case you're missing events, but you probably shouldn't lower + this value unless you make sure you're still receiving all events. In general, + higher frame rates work better with lower buffer sizes, and vice versa. +- `frame_rate int = 30` - the number of times per second that the `frame` callback will be fired. + 30fps is a nice balance between smoothness and performance, + but you can increase or lower it as you wish. +- `hide_cursor bool` - whether to hide the mouse cursor. Useful if you want to use your own. +- `capture_events bool` - sets the terminal into raw mode, which makes it intercept some + escape codes such as `ctrl + c` and `ctrl + z`. + Useful if you want to use those key combinations in your app. +- `window_title string` - sets the title of the terminal window. + This may be changed later, by calling the `set_window_title()` method. +- `reset []int = [1, 2, 3, 4, 6, 7, 8, 9, 11, 13, 14, 15, 19]` - a list of reset signals, + to setup handlers to cleanup the terminal state when they're received. + You should not need to change this, unless you know what you're doing. + +All of these fields may be omitted, in which case, the default value will be used. +In the case of the various callbacks, they will not be fired if a handler has not been specified. + + +#### FAQ + +Q: My terminal (doesn't receive events / doesn't print anything / prints gibberish characters), +what's up with that? +A: Please check if your terminal. The module has been tested with `xterm`-based terminals on Linux +(like `gnome-terminal` and `konsole`), and `Terminal.app` and `iterm2` on macOS. +If your terminal does not work, open an issue with the output of `echo $TERM`. + +Q: There are screen tearing issues when doing large prints +A: This is an issue with how terminals render frames, +as they may decide to do so in the middle of receiving a frame, +and cannot be fully fixed unless your console implements the [synchronized updates spec](https://gitlab.com/gnachman/iterm2/-/wikis/synchronized-updates-spec). +It can be reduced *drastically*, though, by using the rendering methods built in to the module, +and by only painting frames when your app's content has actually changed. + +Q: Why does the module only emit `keydown` events, and not `keyup` like `sokol`/`gg`? +A: It's because of the way terminals emit events. Every key event is received as a keypress, +and there isn't a way of telling terminals to send keyboard events differently, +nor a reliable way of converting these into `keydown` / `keyup` events. |