mirror/v
1
0
Fork 0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00
Code Issues Projects Releases Wiki Activity

docs_ci: check all md files except thirdparty (#6855)

Browse Source
This commit is contained in:
Lukas Neubert
2020-11-18 18:28:28 +01:00
committed by GitHub
parent d8f64f516b
commit df4165c7ee
20 changed files with 373 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
vlib/term/README.md
View File

@@ -1,12 +1,14 @@
# Quickstart
The V `term` module is a module designed to provide the building blocks for building very simple TUI apps.
For more complex apps, you should really look at the `term.input` module, as it includes terminal events, is easier to use,
and is much more performant for large draws.
The V `term` module is a module designed to provide the building blocks
for building very simple TUI apps.
For more complex apps, you should really look at the `term.input` module,
as it includes terminal events, is easier to use and is much more performant for large draws.
# Use
You can use the `term` module to either color the output on a terminal or to decide on where to put the output in your terminal.
You can use the `term` module to either color the output on a terminal
or to decide on where to put the output in your terminal.
For example let's make a simple program which prints colored text in the middle of the terminal.
@@ -16,8 +18,8 @@ import os
fn main() {
term.clear() // clears the content in the terminal
width, height := term.get_terminal_size() // get the size of the terminal
term.set_cursor_position(x: width / 2, y: height / 2) // now we point the cursor to the middle of the terminal
width, height := term.get_terminal_size() // get the size of the terminal
term.set_cursor_position(x: width / 2, y: height / 2) // now we point the cursor to the middle of the terminal
println(term.strikethrough(term.bright_green("hello world"))) // Print green text
term.set_cursor_position(x: 0, y: height) // Sets the position of the cursor to the bottom of the terminal
mut var := os.input('press q to quit: ')
@@ -38,17 +40,17 @@ This simple program covers many of the principal aspects of the `term ` module.
Here are some functions you should be aware of in the `term `module:
```v
```v oksyntax
// returns the height and the width of the terminal
term.get_terminal_size() (width, height)
// returns the string as green text to be printed on stdout
// returns the string as green text to be printed on stdout
term.ok_message(string)
// returns the string as red text to be printed on stdout
// returns the string as red text to be printed on stdout
term.fail_message(string)
// returns the string as yellow text to be printed on stdout
// returns the string as yellow text to be printed on stdout
term.warning_message(string)
//clears the entire terminal and leaves a blank one
@@ -66,7 +68,8 @@ term.strikethrough(string)
// underlines the given string
term.underline(string)
// colors the background of the outup following the given color, the available colors are: black,blue,yellow,green,cyan,gray
// colors the background of the output following the given color
// the available colors are: black, blue, yellow, green, cyan, gray
term.bg_<color>(string)
// sets the position of the cursor at a given place in the terminal

68
vlib/term/ui/README.md
View File

@@ -44,32 +44,58 @@ 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.
- `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.
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: Why does this module not work on Windows?
A: As with many other things, Windows has a completely different and incompatible way of handling input parsing and drawing primitives, and support has not been implemented yet. Contributions are definitely welcome though.
Q: Why does this module not work on Windows?
A: As with many other things, Windows has a completely different and incompatible way of handling
input parsing and drawing primitives, and support has not been implemented yet.
Contributions are definitely welcome though.
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: 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: 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.
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.