diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/doc/api.txt | 11 | ||||
| -rw-r--r-- | runtime/doc/gui.txt | 28 | ||||
| -rw-r--r-- | runtime/doc/news.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/tui.txt | 41 | ||||
| -rw-r--r-- | runtime/doc/ui.txt | 2 |
5 files changed, 65 insertions, 20 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index a7b59f20bc..45c6168e3d 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -779,7 +779,7 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* • {chan} channel_id, or 0 for current channel Return: ~ - Dictionary describing a channel, with these keys: + Channel info dict with these keys: • "id" Channel id. • "argv" (optional) Job arguments list. • "stream" Stream underlying the channel. @@ -792,11 +792,11 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* • "terminal" |terminal| instance interprets ASCII sequences. • "rpc" |RPC| communication on the channel is active. • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a - device path like "/dev/pts/1". If the name is unknown, the key will - still be present if a pty is used (e.g. for conpty on Windows). - • "buffer" (optional) Buffer with connected |terminal| instance. + device path like "/dev/pts/1". If unknown, the key will still be + present if a pty is used (e.g. for conpty on Windows). + • "buffer" (optional) Buffer connected to |terminal| instance. • "client" (optional) Info about the peer (client on the other end of - the RPC channel), if provided by it via |nvim_set_client_info()|. + the RPC channel), which it provided via |nvim_set_client_info()|. nvim_get_color_by_name({name}) *nvim_get_color_by_name()* Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or @@ -1285,6 +1285,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) inclusive. • {attributes} Arbitrary string:string map of informal client properties. Suggested keys: + • "pid": Process id. • "website": Client homepage URL (e.g. GitHub repository) • "license": License description ("Apache 2", "GPLv3", diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 69e251e657..f0f2334ff6 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -6,14 +6,38 @@ Nvim Graphical User Interface *gui* *GUI* +Any client that supports the Nvim |ui-protocol| can be used as a UI for Nvim. +And multiple UIs can connect to the same Nvim instance! The terms "UI" and +"GUI" are often used interchangeably because all Nvim UI clients have the same +potential capabilities; the "TUI" refers to a UI client that outputs to your +terminal, whereas a "GUI" outputs directly to the OS graphics system. + +Except where noted, this document describes UI capabilities available to both +TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes +specific to the terminal UI. Help tags with the "gui-" prefix refer to UI +features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|. + +Nvim provides a default, builtin UI (the |TUI|), but there are many other +(third-party) GUIs that you can use instead: + +- Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim +- vscode-neovim (Nvim in VSCode!) https://github.com/vscode-neovim/vscode-neovim +- Neovide https://neovide.dev/ +- Goneovim https://github.com/akiyosi/goneovim +- Nvy https://github.com/RMichelsen/Nvy +- Neovim-Qt (Qt5) https://github.com/equalsraf/neovim-qt +- VimR (macOS) https://github.com/qvacua/vimr +- Others https://github.com/neovim/neovim/wiki/Related-projects#gui + Type |gO| to see the table of contents. ============================================================================== -Starting the GUI *gui-start* *E229* *E233* +Starting the GUI *gui-config* *gui-start* *ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC* For GUI-specific configuration Nvim provides the |UIEnter| event. This -happens after other |initialization|s, like reading your vimrc file. +happens after other |initialization|s, or whenever a UI attaches (multiple UIs +can connect to any Nvim instance). Example: this sets "g:gui" to the value of the UI's "rgb" field: > :autocmd UIEnter * let g:gui = filter(nvim_list_uis(),{k,v-> v.chan==v:event.chan})[0].rgb diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 515aef753d..1d95886356 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -189,6 +189,9 @@ TREESITTER TUI +• The builtin UI declares info |nvim_set_client_info()| on its channel. See + |startup-tui|. To see the current UI info, try this: > + :lua =vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan) • |log| messages written by the builtin UI client (TUI, |--remote-ui|) are now prefixed with "ui" instead of "?". diff --git a/runtime/doc/tui.txt b/runtime/doc/tui.txt index d2af878239..9493f91b1e 100644 --- a/runtime/doc/tui.txt +++ b/runtime/doc/tui.txt @@ -6,28 +6,45 @@ Terminal UI *TUI* *tui* -Nvim uses a list of terminal capabilities to display its user interface -(except in |--embed| and |--headless| modes). If that information is wrong, -the screen may be messed up or keys may not be recognized. +By default when you run `nvim` (without |--embed| or |--headless|) it starts +the builtin "terminal UI" (TUI). This default UI is optional: you can run Nvim +as a "headless" server, or you can use a |GUI|. Type |gO| to see the table of contents. ============================================================================== -Startup *startup-terminal* +Startup *startup-tui* *startup-terminal* + +Nvim has a client-server architecture: by default when you run `nvim`, this +starts the builtin UI client, which starts a `nvim --embed` server (child) +process that the UI client connects to. After attaching to the server, the UI +client calls |nvim_set_client_info()| (as recommended for all UIs |dev-ui|) +and sets these fields on its channel: > + + client = { + attributes = { + license = 'Apache 2', + pid = …, + website = 'https://neovim.io', + }, + name = 'nvim-tui', + type = 'ui', + version = { … }, + } Nvim guesses the terminal type when it starts (except in |--embed| and |--headless| modes). The |$TERM| environment variable is the primary hint that determines the terminal type. *terminfo* *E557* *E558* *E559* -The terminfo database is used if available. - -The Unibilium library (used by Nvim to read terminfo) allows you to override -the system terminfo with one in $HOME/.terminfo/ directory, in part or in -whole. - -Building your own terminfo is usually as simple as running this as -a non-superuser: +To display its user interface, Nvim reads a list of "terminal capabilities" +from the system terminfo database (or builtin defaults if terminfo is not +found). If that information is wrong, the screen may be messed up or keys may +not be recognized. + +The Unibilium library (used to read terminfo) allows you to override the +system terminfo with one in the "$HOME/.terminfo/" directory. Building your +own terminfo is usually as simple as running this: > curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gz gunzip terminfo.src.gz diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 1f5132bd30..42dfcd2fe7 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -9,7 +9,7 @@ Nvim UI protocol *UI* *ui* Type |gO| to see the table of contents. ============================================================================== -UI Events *ui-events* +UI Events *ui-protocol* *ui-events* UIs can be implemented as external client processes communicating with Nvim over the RPC API. The default UI model is a terminal-like grid with a single, |