Nvim :help pages, generated
from source
using the tree-sitter-vimdoc parser.
options parameter is a map
with these (optional) keys:rgb Decides the color format.
override Decides how UI capabilities are resolved.
ext_cmdline Externalize the cmdline. ui-cmdline
ext_tabline Externalize the tabline. ui-tabline
ext_termcolors Use external default colors.
term_name Sets the name of the terminal 'term'.
term_colors Sets the number of supported colors 't_Co'.
stdin_fd Read buffer 1 from this fd as if it were stdin --.
Only from --embed UI on startup. ui-startup-stdin
stdin_tty Tells if stdin is a tty or not.
stdout_tty Tells if stdout is a tty or not.
ui_options key for supported options.['notification', 'redraw',
[
['grid_resize', [2, 77, 36]],
['grid_line',
[2, 0, 0, [[' ' , 0, 77]], false],
[2, 1, 0, [['~', 7], [' ', 7, 76]], false],
[2, 9, 0, [['~', 7], [' ', 7, 76]], false],
...
[2, 35, 0, [['~', 7], [' ', 7, 76]], false],
[1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']], false],
[1, 36, 9, [[' ', 9, 50]], false],
[1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]], false]
],
['msg_showmode', [[]]],
['win_pos', [2, 1000, 0, 0, 77, 36]],
['grid_cursor_goto', [2, 0, 0]],
['flush', []]
]
]
Events must be handled in-order. Nvim sends a "flush" event when it has
completed a redraw of the entire screen (so all windows have a consistent view
of buffer state, options, etc.). Multiple "redraw" batches may be sent before
the entire screen has been redrawn, with "flush" following only the last
batch. The user should only see the final state (when "flush" is sent), not
any intermediate state while processing part of the batch array, nor after
a batch not ending with "flush".nvim --embednvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")stdin_fd parameter of nvim_ui_attach. Nvim will
read it as text into buffer 1.cursor_style_enabled is a boolean indicating if the UI should set
the cursor style. mode_info is a list of mode property maps. The
current mode is given by the mode_idx field of the mode_change
event.cursor_shape: "block", "horizontal", "vertical"
cell_percentage: Cell % occupied by the cursor.
blinkwait, blinkon, blinkoff: See cursor-blinking.
attr_id: Cursor attribute id (defined by hl_attr_define).
When attr_id is 0, the background and foreground
colors should be swapped.
attr_id_lm: Cursor attribute id for when :lmap is on.
short_name: Mode code name, see 'guicursor'.
name: Mode descriptive name.
mouse_shape: (To be implemented.)hl_id: Use attr_id instead.
id_lm: Use attr_id_lm instead.name is one of:mode parameter is a string representing
the current mode. mode_idx is an index into the array emitted in
the mode_info_set event. UIs should change the cursor style
according to the properties specified in the corresponding item. The
set of modes reported will change in new versions of Nvim, for
instance more submodes and temporary states might be represented as
separate modes.progpath as the full path to the Nvim executable v:progpath and
argv as its arguments v:argv, and reattach to the new server.
Note: --embed and --headless are excluded from argv, and the client
should decide itself whether to add either flag.{content} to the connected TTY. Only UIs that have the
"stdout_tty" ui-option set will receive this event.ext_linegrid ui-option. Recommended for all new UIs.
Deactivates ui-grid-old implicitly.grid_line event to
update a screen-line (whereas the old protocol emitted separate cursor,
highlight and text events per screen-line).grid index as first parameter. Grid 1 is the
global grid used by default for the entire editor screen state. The
ext_linegrid capability by itself will never cause any additional grids to
be created; to enable per-window grids, activate ui-multigrid.grid. If grid wasn't seen by the client before, a new grid is
being created with this size.cterm_fg and cterm_bg specifies the
default color codes to use in a 256-color terminal.ext_termcolors option, instead
-1 will be used for unset colors. This is mostly useful for a TUI
implementation, where using the terminal builtin ("ANSI") defaults
are expected.id to the highlight table, with the
attributes specified by the rgb_attr and cterm_attr dicts, with the
following (all optional) keys.foreground: foreground color.
background: background color.
special: color to use for various underlines, when
present.
reverse: reverse video. Foreground and background colors
are switched.
italic: italic text.
bold: bold text.
strikethrough: struckthrough text.
underline: underlined text. The line has special color.
undercurl: undercurled text. The curl has special color.
underdouble: double underlined text. The lines have special color.
underdotted: underdotted text. The dots have special color.
underdashed: underdashed text. The dashes have special color.
altfont: alternative font.
blend: blend level (0-100). Could be used by UIs to
support blending floating windows to the
background or to signal a transparent cursor.
url: URL associated with this highlight. UIs should
present the region as a clickable hyperlink.rgb_attr and cterm_attr parameters
respectively. The ui-rgb option has no effect anymore.
Most external UIs will only need to store and use the rgb_attr
attributes.id 0 will always be used for the default highlight with colors defined
by default_colors_set and no styles applied.id values if its internal highlight table is full.
In that case Nvim will always issue redraws of screen cells that are
affected by redefined ids, so UIs do not need to keep track of this
themselves.info is an empty array unless ui-hlstate is enabled.name was set to use the attributes hl_id
defined by a previous hl_attr_define call. This event is not needed
to render the grids which use attribute ids directly, but is useful
for a UI who want to render its own elements with consistent
highlighting. For instance a UI using ui-popupmenu events, might
use the hl-Pmenu family of builtin highlights.row on a grid, starting at the column
col_start. cells is an array of arrays each with 1 to 3 items:
[text(, hl_id, repeat)] . text is the UTF-8 text that should be put in
a cell, with the highlight hl_id defined by a previous hl_attr_define
call. If hl_id is not present the most recently seen hl_id in
the same call should be used (it is always sent for the first
cell in the event). If repeat is present, the cell should be
repeated repeat times (including the first time), otherwise just
once.repeat.wrap is a boolean indicating that this line wraps to the next row.
When redrawing a line which wraps to the next row, Nvim will emit a
grid_line event covering the last column of the line with wrap set
to true, followed immediately by a grid_line event starting at the
first column of the next row.grid.grid will not be used anymore and the UI can free any data associated
with it.grid the current grid and row, col the cursor position on this
grid. This event will be sent at most once in a redraw batch and
indicates the visible cursor position.grid. This is semantically unrelated to editor
scrolling, rather this is an optimized way to say "copy these screen
cells".rows is bigger than 0, move a rectangle in the SR up, this can
happen while scrolling down.
+-------------------------+ | (clipped above SR) | ^ |=========================| dst_top | | dst (still in SR) | | +-------------------------+ src_top | | src (moved up) and dst | | |-------------------------| dst_bot | | src (invalid) | | +=========================+ src_bot
rows is less than zero, move a rectangle in the SR down, this can
happen while scrolling up.
+=========================+ src_top | src (invalid) | | |------------------------ | dst_top | | src (moved down) and dst| | +-------------------------+ src_bot | | dst (still in SR) | | |=========================| dst_bot | | (clipped below SR) | v +-------------------------+
cols is always zero in this version of Nvim, and reserved for future
use.set_scroll_region which was end-inclusive.width and height cells.attrs is a dict with the keys below. Any absent key is reset
to its default value. Color defaults are set by the update_fg etc
updates. All boolean keys default to false.foreground: foreground color.
background: background color.
special: color to use for various underlines, when present.
reverse: reverse video. Foreground and background colors are
switched.
italic: italic text.
bold: bold text.
strikethrough: struckthrough text.
underline: underlined text. The line has special color.
undercurl: undercurled text. The curl has special color.
underdouble: double underlined text. The lines have special color.
underdotted: underdotted text. The dots have special color.
underdashed: underdashed text. The dashes have special color.text is put at the cursor position
(and the cursor is advanced), with the highlights as set by the
last highlight_set update.scroll below.+-------------------------+ | (clipped above SR) | ^ |=========================| dst_top | | dst (still in SR) | | +-------------------------+ src_top | | src (moved up) and dst | | |-------------------------| dst_bot | | src (cleared) | | +=========================+ src_bot
+=========================+ src_top | src (cleared) | | |------------------------ | dst_top | | src (moved down) and dst| | +-------------------------+ src_bot | | dst (still in SR) | | |=========================| dst_bot | | (clipped below SR) | v +-------------------------+
ext_hlstate is enabled, Nvim will emit detailed highlight state in
ui-linegrid events. Otherwise (by default) Nvim only describes grid cells
using the final calculated highlight attributes described at
ui-event-highlight_set.ext_hlstate provides a semantic description of active highlights for each
grid cell. Highlights are predefined in a table, see ui-event-hl_attr_define
and ui-event-grid_line.info parameter in hl_attr_define contains a semantic description of
the highlights. Because highlight groups can be combined, this is an array
where the highest-priority item is last. Each item is a dict with these keys:kind: always present. One of the following values:
"ui": Builtin UI highlight. highlight-groups
"syntax": Highlight applied to a buffer by a syntax declaration or
other runtime/plugin functionality such as
nvim_buf_set_extmark()
"terminal": highlight from a process running in a terminal-emulator.
Contains no further semantic information.
ui_name: Highlight name from highlight-groups. Only for "ui" kind.
hi_name: Name of the final :highlight group where the used
attributes are defined.
id: Unique numeric id representing this item.ui_name and hi_name present. These can
differ, because the builtin group was linked to another group :hi-link , or
because 'winhighlight' was used. UI items will be transmitted, even if the
highlight group is cleared, so ui_name can always be used to reliably identify
screen elements, even if no attributes have been applied.win.anchor_grid at the specified position anchor_row and
anchor_col. For the meaning of anchor and more details of
positioning, see nvim_open_win(). NOTE: you have to manually
ensure that the window fits the screen, possibly by further
reposition it. Ignore screen_row and screen_col in this case.
anchor
and display the window at screen_row and screen_col.
mouse_enabled is true if the window can receive mouse events.zindex is the configured zindex, while compindex is the exact
rendering order of the windows determined by nvim. To render exactly
like the TUI, first render all the non-floating windows, then render
in the compindex order, overwriting any floating window cells.
Finally, blend the floating window cells against the non-floating
background. To add more blending, you can group the windows by zindex,
and blend between the layers. But note that windows inside the same
zindex should still overwrite previous cells inside the same layer
without blending. This ensures that plugins that render multiple
windows, to add borders for example, work as expected.win. The window should be
displayed as a separate top-level window in the desktop environment,
or something similar.grid. The grid will be displayed at row on
the default grid (grid=1), covering the full column width. scrolled
indicates whether the message area has been scrolled to cover other
grids. It can be useful to draw a separator then msgsep. The Builtin
TUI draws a full line filled with sep_char ('fillchars' msgsep
field) and hl-MsgSeparator highlight.zindex and compindex have the same meaning as for win_float_pos.
The zindex always has a fixed value of 200 and included for
completeness.botline is set to one more than the line count of the buffer, if
there are filler lines past the end. scroll_delta contains how much
the top line of a window moved since win_viewport was last emitted.
It is intended to be used to implement smooth scrolling. For this
purpose it only counts "virtual" or "displayed" lines, so folds
only count as one line. When scrolling more than a full screen it is
an approximate value.grid_line, in a batch affects the new viewport,
despite the fact that win_viewport is received after the updates.
Applications implementing, for example, smooth scrolling should take
this into account and keep the grid separated from what's displayed on
the screen and copy it to the viewport destination once win_viewport
is received.win_viewport event. This happens
e.g. in the presence of 'winbar' and floating window borders.ui_watched attribute.ext_popupmenu ui-option.mode_change event, command-line wildmenu may be presented horizontally,
while insert-mode completion would show a vertical popupmenu.items is an array of completion items
to show; each item is an array of the form [word, kind, menu, info] as
defined at complete-items, except that word is replaced by abbr
if present. selected is the initially-selected item, a zero-based
index into the array of items (-1 if no item is selected). row and
col give the anchor position, where the first character of the
completed word will be. When ui-multigrid is used, grid is the
grid for the anchor position. When ext_cmdline is active, grid is
set to -1 to indicate the popupmenu should be anchored to the external
cmdline. Then col will be a byte position in the cmdline text.selected is a zero-based
index into the array of items from the last popupmenu_show event, or
-1 if no item is selected.ext_tabline ui-option.curbuf + buffers were added in API7.
curtab: Current Tabpage
tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...]
curbuf: Current buffer handle.
buffers: List of Dicts [{ "buffer": buffer handle, "name": String}, ...]ext_cmdline ui-option.content is the full content that should be displayed in the
cmdline, and the pos is the position of the cursor that in the
cmdline. The content is divided into chunks with different highlight
attributes represented as a dict (see ui-event-highlight_set).firstc and prompt are text, that if non-empty should be
displayed in front of the command line. firstc always indicates
built-in command lines such as : (ex command) and / ? (search),
while prompt is an input() prompt, highlighted with hl_id.
indent tells how many spaces the content should be indented.<c-r>= at the command line prompt. The level field is used
to distinguish different command lines active at the same time. The
first invoked command line has level 1, the next recursively-invoked
prompt has level 2. A command line invoked from the cmdline-window
has a higher level than the edited command line.shift is true the text after the cursor should be shifted, otherwise
it should overwrite the char at the cursor.level is the nesting level of the cmdline being hidden.
abort is true if the cmdline is hidden after an aborting condition
(c_Esc or c_CTRL-C).:function Foo()
: echo "foo"
:lines is a list of lines of highlighted chunks, in the same form as
the "cmdline_show" contents parameter.msg_id.:echo ""), with empty content.
Should clear messages sharing the 'cmdheight'
area if it is the only message in a batch.
"bufwrite" :write message
"confirm" Message preceding a prompt (:confirm,
confirm(), inputlist(), z=, …)
"emsg" Error (errors, internal error, :throw, …)
"echo" :echo message
"echomsg" :echomsg message
"echoerr" :echoerr message
"completion" ins-completion-menu message
"list_cmd" List output for various commands (:ls, :set, …)
"lua_error" Error in :lua code
"lua_print" print() from :lua code
"progress" Progress message emitted by nvim_echo()
"rpc_error" Error response from rpcrequest()
"quickfix" Quickfix navigation message
"search_cmd" Entered search command
"search_count" Search count message ("S" flag of 'shortmess')
"shell_cmd" :!cmd executed command
"shell_err" :!cmd shell stderr output
"shell_out" :!cmd shell stdout output
"shell_ret" :!cmd shell return code
"undo" :undo and :redo message
"verbose" 'verbose' message
"wildlist" 'wildmode' "list" message
"wmsg" Warning ("search hit BOTTOM", W10, …)
New kinds may be added in the future; clients should treat unknown
kinds as the empty kind.[attr_id, text_chunk, hl_id] tuples, building up the
message text of chunks of different highlights. No extra spacing
should be added between chunks, the text_chunk by itself
contains any necessary whitespace. Messages can contain line
breaks "\n".msg_show call,
but any other visible message should still remain.content has the same
format as in "msg_show". This event is sent with empty content to
hide the last message.content has the same format as in "msg_show".
This event is sent with empty content to hide the last message.content has the same format as in "msg_show". This event is
sent with empty content to hide the last message.