774 lines
32 KiB
Plaintext
774 lines
32 KiB
Plaintext
*ui.txt* Nvim
|
||
|
||
|
||
NVIM REFERENCE MANUAL
|
||
|
||
|
||
Nvim UI protocol *UI* *ui*
|
||
|
||
Type |gO| to see the table of contents.
|
||
|
||
==============================================================================
|
||
UI Events *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,
|
||
monospace font. The UI can opt-in to have windows drawn on separate grids, and
|
||
have some elements ("widgets") presented by the UI itself rather than by Nvim
|
||
("externalized").
|
||
|
||
*ui-option*
|
||
Call |nvim_ui_attach()| to tell Nvim that your program wants to draw the Nvim
|
||
screen grid with a size of width × height cells. This is typically done by an
|
||
embedder at startup (see |ui-startup|), but UIs can also connect to a running
|
||
Nvim instance and invoke nvim_ui_attach(). The `options` parameter is a map
|
||
with these (optional) keys:
|
||
*ui-rgb*
|
||
`rgb` Decides the color format.
|
||
true: (default) 24-bit RGB colors
|
||
false: Terminal colors (8-bit, max 256)
|
||
*ui-override*
|
||
`override` Decides how UI capabilities are resolved.
|
||
true: Enable requested UI capabilities, even
|
||
if not supported by all connected UIs
|
||
(including |TUI|).
|
||
false: (default) Disable UI capabilities not
|
||
supported by all connected UIs
|
||
(including TUI).
|
||
*ui-ext-options*
|
||
`ext_cmdline` Externalize the cmdline. |ui-cmdline|
|
||
`ext_hlstate` Detailed highlight state. |ui-hlstate|
|
||
Sets `ext_linegrid` implicitly.
|
||
`ext_linegrid` Line-based grid events. |ui-linegrid|
|
||
Deactivates |ui-grid-old| implicitly.
|
||
`ext_messages` Externalize messages. |ui-messages|
|
||
Sets `ext_linegrid` and `ext_cmdline` implicitly.
|
||
`ext_multigrid` Per-window grid events. |ui-multigrid|
|
||
Sets `ext_linegrid` implicitly.
|
||
`ext_popupmenu` Externalize |popupmenu-completion| and
|
||
'wildmenu'. |ui-popupmenu|
|
||
`ext_tabline` Externalize the tabline. |ui-tabline|
|
||
`ext_termcolors` Use external default colors.
|
||
|
||
Specifying an unknown option is an error; UIs can check the |api-metadata|
|
||
`ui_options` key for supported options.
|
||
|
||
By default Nvim requires all connected UIs to support the same capabilities,
|
||
thus the active capabilities are the intersection of those requested. UIs may
|
||
specify |ui-override| to invert this behavior (useful for debugging). The
|
||
"option_set" event announces which capabilities are active.
|
||
|
||
Nvim sends RPC notifications to all attached UIs, with method name "redraw"
|
||
and a single argument: an array (batch) of screen "update events". Each update
|
||
event is itself an array whose first element is the event name and remaining
|
||
elements are event-parameter tuples. Thus multiple events of the same kind can
|
||
be sent contiguously without repeating the event name.
|
||
|
||
Example of a typical "redraw" batch in a single RPC notification: >
|
||
|
||
['notification', 'redraw',
|
||
[
|
||
['grid_resize', [2, 77, 36]],
|
||
['grid_line',
|
||
[2, 0, 0, [[' ' , 0, 77]]],
|
||
[2, 1, 0, [['~', 7], [' ', 7, 76]]],
|
||
[2, 9, 0, [['~', 7], [' ', 7, 76]]],
|
||
...
|
||
[2, 35, 0, [['~', 7], [' ', 7, 76]]],
|
||
[1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']]],
|
||
[1, 36, 9, [[' ', 9, 50]]],
|
||
[1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]]]
|
||
],
|
||
['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".
|
||
|
||
By default, Nvim sends |ui-global| and |ui-grid-old| events (for backwards
|
||
compatibility); these suffice to implement a terminal-like interface. However
|
||
the new |ui-linegrid| represents text more efficiently (especially highlighted
|
||
text), and allows UI capabilities requiring multiple grids. New UIs should
|
||
implement |ui-linegrid| instead of |ui-grid-old|.
|
||
|
||
Nvim optionally sends various screen elements "semantically" as structured
|
||
events instead of raw grid-lines, as specified by |ui-ext-options|. The UI
|
||
must present such elements itself, Nvim will not draw them on the grid.
|
||
|
||
Future versions of Nvim may add new update kinds and may append new parameters
|
||
to existing update kinds. Clients must be prepared to ignore such extensions,
|
||
for forward-compatibility. |api-contract|
|
||
|
||
==============================================================================
|
||
UI startup *ui-startup*
|
||
|
||
UI embedders (clients that start Nvim with |--embed| and later call
|
||
|nvim_ui_attach()|) must start Nvim without |--headless|: >
|
||
nvim --embed
|
||
Nvim will pause before loading startup files and reading buffers, so the UI
|
||
has a chance to invoke requests and do early initialization. Startup will
|
||
continue as soon as the UI invokes |nvim_ui_attach()|.
|
||
|
||
A simple UI only needs to do a single |nvim_ui_attach()| request and then
|
||
prepare to handle any UI event. A more featureful UI, which might need
|
||
additional configuration of the Nvim process, should use the following startup
|
||
procedure:
|
||
|
||
1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or
|
||
to get the list of supported UI extensions.
|
||
2. Do any configuration that should be happen before user config is loaded.
|
||
Buffers and windows are not available at this point, but this could be used
|
||
to set |g:| variables visible to init.vim
|
||
3. If the UI wants to do additional setup after user config is loaded,
|
||
register a VimEnter autocmd: >
|
||
nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
|
||
<4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now:
|
||
sourcing init.vim and loading buffers might lead to blocking prompts.
|
||
5. If step 3 was used, Nvim will send a blocking "vimenter" request to the UI.
|
||
Inside this request handler, the UI can safely do any initialization before
|
||
entering normal mode, for example reading variables set by init.vim.
|
||
|
||
==============================================================================
|
||
Global Events *ui-global*
|
||
|
||
The following UI events are always emitted, and describe global state of
|
||
the editor.
|
||
|
||
["set_title", title]
|
||
["set_icon", icon]
|
||
Set the window title, and icon (minimized) window title, respectively.
|
||
In windowing systems not distinguishing between the two, "set_icon"
|
||
can be ignored.
|
||
|
||
["mode_info_set", cursor_style_enabled, mode_info]
|
||
`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.
|
||
|
||
Each mode property map may contain these keys:
|
||
|
||
KEY DESCRIPTION ~
|
||
`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 'langmap' is active.
|
||
`short_name`: Mode code name, see 'guicursor'.
|
||
`name`: Mode descriptive name.
|
||
`mouse_shape`: (To be implemented.)
|
||
|
||
Some keys are missing in some modes.
|
||
|
||
The following keys are deprecated:
|
||
|
||
`hl_id`: Use `attr_id` instead.
|
||
`hl_lm`: Use `attr_id_lm` instead.
|
||
|
||
["option_set", name, value]
|
||
UI-related option changed, where `name` is one of:
|
||
|
||
'arabicshape'
|
||
'ambiwidth'
|
||
'emoji'
|
||
'guifont'
|
||
'guifontwide'
|
||
'linespace'
|
||
'pumblend'
|
||
'showtabline'
|
||
'termguicolors'
|
||
"ext_*" (all |ui-ext-options|)
|
||
|
||
Triggered when the UI first connects to Nvim, and whenever an option
|
||
is changed by the user or a plugin.
|
||
|
||
Options are not represented here if their effects are communicated in
|
||
other UI events. For example, instead of forwarding the 'mouse' option
|
||
value, the "mouse_on" and "mouse_off" UI events directly indicate if
|
||
mouse support is active. Some options like 'ambiwidth' have already
|
||
taken effect on the grid, where appropriate empty cells are added,
|
||
however a UI might still use such options when rendering raw text
|
||
sent from Nvim, like for |ui-cmdline|.
|
||
|
||
["mode_change", mode, mode_idx]
|
||
Editor mode changed. The `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.
|
||
|
||
["mouse_on"]
|
||
["mouse_off"]
|
||
|'mouse'| was enabled/disabled in the current editor mode. Useful for
|
||
a terminal UI, or other situations where Nvim mouse would conflict
|
||
with other usages of the mouse. UIs may ignore this and always send
|
||
mouse input, because 'mouse' decides the behavior of |nvim_input()|
|
||
implicitly.
|
||
|
||
["busy_start"]
|
||
["busy_stop"]
|
||
Nvim started or stopped being busy, and possibly not responsive to
|
||
user input. This could be indicated to the user by hiding the cursor.
|
||
|
||
["suspend"]
|
||
|:suspend| command or |CTRL-Z| mapping is used. A terminal client (or
|
||
another client where it makes sense) could suspend itself. Other
|
||
clients can safely ignore it.
|
||
|
||
["update_menu"]
|
||
The menu mappings changed.
|
||
|
||
["bell"]
|
||
["visual_bell"]
|
||
Notify the user with an audible or visual bell, respectively.
|
||
|
||
["flush"]
|
||
Nvim is done redrawing the screen. For an implementation that renders
|
||
to an internal buffer, this is the time to display the redrawn parts
|
||
to the user.
|
||
|
||
==============================================================================
|
||
Grid Events (line-based) *ui-linegrid*
|
||
|
||
Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs.
|
||
Deactivates |ui-grid-old| implicitly.
|
||
|
||
The biggest change compared to |ui-grid-old| is to use a single `grid_line`
|
||
event to update the contents of a screen line (whereas the old protocol used
|
||
a combination of cursor, highlight and text events)
|
||
|
||
Most of these events take a `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|.
|
||
|
||
Highlight attribute groups are predefined. UIs should maintain a table to map
|
||
numerical highlight ids to the actual attributes.
|
||
|
||
["grid_resize", grid, width, height]
|
||
Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is
|
||
being created with this size.
|
||
|
||
["default_colors_set", rgb_fg, rgb_bg, rgb_sp, cterm_fg, cterm_bg]
|
||
The first three arguments set the default foreground, background and
|
||
special colors respectively. `cterm_fg` and `cterm_bg` specifies the
|
||
default color codes to use in a 256-color terminal.
|
||
|
||
The RGB values will always be valid colors, by default. If no
|
||
colors have been set, they will default to black and white, depending
|
||
on 'background'. By setting the `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.
|
||
|
||
Note: Unlike the corresponding |ui-grid-old| events, the screen is not
|
||
always cleared after sending this event. The UI must repaint the
|
||
screen with changed background color itself.
|
||
|
||
*ui-event-hl_attr_define*
|
||
["hl_attr_define", id, rgb_attr, cterm_attr, info]
|
||
Add a highlight with `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 underline and undercurl, 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.
|
||
`blend`: Blend level (0-100). Could be used by UIs to support
|
||
blending floating windows to the background or to
|
||
signal a transparent cursor.
|
||
|
||
For absent color keys the default color should be used. Don't store
|
||
the default value in the table, rather a sentinel value, so that
|
||
a changed default color will take effect.
|
||
All boolean keys default to false, and will only be sent when they
|
||
are true.
|
||
|
||
Highlights are always transmitted both for both the RGB format and as
|
||
terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters
|
||
respectively. The |ui-rgb| option has no effect 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.
|
||
|
||
Note: Nvim may reuse `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 by default, and will be used by the
|
||
|ui-hlstate| extension explained below.
|
||
|
||
["hl_group_set", name, hl_id]
|
||
The bulitin highlight group `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 an UI who want to render its own elements with consistent
|
||
highlighting. For instance an UI using |ui-popupmenu| events, might
|
||
use the |hl-Pmenu| family of builtin highlights.
|
||
|
||
*ui-event-grid_line*
|
||
["grid_line", grid, row, col_start, cells]
|
||
Redraw a continuous part of a `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.
|
||
|
||
The right cell of a double-width char will be represented as the empty
|
||
string. Double-width chars never use `repeat`.
|
||
|
||
If the array of cell changes doesn't reach to the end of the line, the
|
||
rest should remain unchanged. A whitespace char, repeated
|
||
enough to cover the remaining line, will be sent when the rest of the
|
||
line should be cleared.
|
||
|
||
["grid_clear", grid]
|
||
Clear a `grid`.
|
||
|
||
["grid_destroy", grid]
|
||
`grid` will not be used anymore and the UI can free any data associated
|
||
with it.
|
||
|
||
["grid_cursor_goto", grid, row, column]
|
||
Makes `grid` the current grid and `row, column` 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_scroll", grid, top, bot, left, right, rows, cols]
|
||
Scroll a region of `grid`. This is semantically unrelated to editor
|
||
|scrolling|, rather this is an optimized way to say "copy these screen
|
||
cells".
|
||
|
||
The following diagrams show what happens per scroll direction.
|
||
"===" represents the SR (scroll region) boundaries.
|
||
"---" represents the moved rectangles.
|
||
Note that dst and src share a common region.
|
||
|
||
If `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
|
||
<
|
||
If `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.
|
||
|
||
Note when updating code from |ui-grid-old| events: ranges are
|
||
end-exclusive, which is consistent with API conventions, but different
|
||
from `set_scroll_region` which was end-inclusive.
|
||
|
||
The scrolled-in area will be filled using |ui-event-grid_line| directly
|
||
after the scroll event. The UI thus doesn't need to clear this area as
|
||
part of handling the scroll event.
|
||
|
||
==============================================================================
|
||
Grid Events (cell-based) *ui-grid-old*
|
||
|
||
This is the legacy representation of the screen grid, emitted if |ui-linegrid|
|
||
is not active. New UIs should implement |ui-linegrid| instead.
|
||
|
||
["resize", width, height]
|
||
The grid is resized to `width` and `height` cells.
|
||
|
||
["clear"]
|
||
Clear the grid.
|
||
|
||
["eol_clear"]
|
||
Clear from the cursor position to the end of the current line.
|
||
|
||
["cursor_goto", row, col]
|
||
Move the cursor to position (row, col). Currently, the same cursor is
|
||
used to define the position for text insertion and the visible cursor.
|
||
However, only the last cursor position, after processing the entire
|
||
array in the "redraw" event, is intended to be a visible cursor
|
||
position.
|
||
|
||
["update_fg", color]
|
||
["update_bg", color]
|
||
["update_sp", color]
|
||
Set the default foreground, background and special colors
|
||
respectively.
|
||
|
||
*ui-event-highlight_set*
|
||
["highlight_set", attrs]
|
||
Set the attributes that the next text put on the grid will have.
|
||
`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 underline and undercurl, 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.
|
||
|
||
["put", text]
|
||
The (utf-8 encoded) string `text` is put at the cursor position
|
||
(and the cursor is advanced), with the highlights as set by the
|
||
last `highlight_set` update.
|
||
|
||
["set_scroll_region", top, bot, left, right]
|
||
Define the scroll region used by `scroll` below.
|
||
|
||
Note: ranges are end-inclusive, which is inconsistent with API
|
||
conventions.
|
||
|
||
["scroll", count]
|
||
Scroll the text in the scroll region. The diagrams below illustrate
|
||
what will happen, depending on the scroll direction. "=" is used to
|
||
represent the SR(scroll region) boundaries and "-" the moved rectangles.
|
||
Note that dst and src share a common region.
|
||
|
||
If count 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 (cleared) | |
|
||
+=========================+ src_bot
|
||
<
|
||
If count is less than zero, move a rectangle in the SR down, this can
|
||
happen while scrolling up.
|
||
>
|
||
+=========================+ src_top
|
||
| src (cleared) | |
|
||
|------------------------ | dst_top |
|
||
| src (moved down) and dst| |
|
||
+-------------------------+ src_bot |
|
||
| dst (still in SR) | |
|
||
|=========================| dst_bot |
|
||
| (clipped below SR) | v
|
||
+-------------------------+
|
||
<
|
||
==============================================================================
|
||
Detailed highlight state Extension *ui-hlstate*
|
||
|
||
Activated by the `ext_hlstate` |ui-option|.
|
||
Activates |ui-linegrid| implicitly.
|
||
|
||
By default Nvim will only describe grid cells using the final calculated
|
||
highlight attributes, as described by the dict keys in |ui-event-highlight_set|.
|
||
The `ext_hlstate` extension allows to the UI to also receive a semantic
|
||
description of the highlights active in a cell. In this mode highlights will be
|
||
predefined in a table, see |ui-event-hl_attr_define| and |ui-event-grid_line|.
|
||
The `info` parameter in `hl_attr_define` will contain a semantic description
|
||
of the highlights. As highlight groups can be combined, this will be an array
|
||
of items, with the item with highest priority last. Each item is a dictionary
|
||
with the following possible 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_add_highlight()|
|
||
"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.
|
||
|
||
Note: "ui" items will have both `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.
|
||
|
||
==============================================================================
|
||
Multigrid Events *ui-multigrid*
|
||
|
||
Activated by the `ext_multigrid` |ui-option|.
|
||
Activates |ui-linegrid| implicitly.
|
||
|
||
See |ui-linegrid| for grid events.
|
||
See |nvim_ui_try_resize_grid()| to request changing the grid size.
|
||
See |nvim_input_mouse()| for sending mouse events to Nvim.
|
||
|
||
The multigrid extension gives UIs more control over how windows are displayed:
|
||
- UIs receive updates on a separate grid for each window.
|
||
- UIs can set the grid size independently of how much space the window
|
||
occupies on the global layout. So the UI could use a different font size
|
||
per-window. Or reserve space around the border of the window for its own
|
||
elements, such as scrollbars from the UI toolkit.
|
||
- A dedicated grid is used for messages, which may scroll over the window
|
||
area. (Alternatively |ext_messages| can be used).
|
||
|
||
By default, the grid size is handled by Nvim and set to the outer grid size
|
||
(i.e. the size of the window frame in Nvim) whenever the split is created.
|
||
Once a UI sets a grid size, Nvim does not handle the size for that grid and
|
||
the UI must change the grid size whenever the outer size is changed. To
|
||
delegate grid-size handling back to Nvim, request the size (0, 0).
|
||
|
||
A window can be hidden and redisplayed without its grid being deallocated.
|
||
This can happen multiple times for the same window, for instance when switching
|
||
tabs.
|
||
|
||
["win_pos", grid, win, start_row, start_col, width, height]
|
||
Set the position and size of the grid in Nvim (i.e. the outer grid
|
||
size). If the window was previously hidden, it should now be shown
|
||
again.
|
||
|
||
["win_float_pos", grid, win, anchor, anchor_grid, anchor_row, anchor_col, focusable]
|
||
Display or reconfigure floating window `win`. The window should be
|
||
displayed above another grid `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()|.
|
||
|
||
["win_external_pos", grid, win]
|
||
Display or reconfigure external window `win`. The window should be
|
||
displayed as a separate top-level window in the desktop environment,
|
||
or something similar.
|
||
|
||
["win_hide", grid]
|
||
Stop displaying the window. The window can be shown again later.
|
||
|
||
["win_close", grid]
|
||
Close the window.
|
||
|
||
["msg_set_pos", grid, row, scrolled, sep_char]
|
||
Display messages on `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 ('display' msgsep
|
||
flag). The Builtin TUI draws a full line filled with `sep_char` and
|
||
|hl-MsgSeparator| highlight.
|
||
|
||
When |ext_messages| is active, no message grid is used, and this event
|
||
will not be sent.
|
||
|
||
["win_viewport", grid, win, topline, botline, curline, curcol]
|
||
Indicates the range of buffer text displayed in the window, as well
|
||
as the cursor position in the buffer. All positions are zero-based.
|
||
`botline` is set to one more than the line count of the buffer, if
|
||
there are filler lines past the end.
|
||
|
||
==============================================================================
|
||
Popupmenu Events *ui-popupmenu*
|
||
|
||
Activated by the `ext_popupmenu` |ui-option|.
|
||
|
||
This UI extension delegates presentation of the |popupmenu-completion| and
|
||
command-line 'wildmenu'.
|
||
|
||
["popupmenu_show", items, selected, row, col, grid]
|
||
Show |popupmenu-completion|. `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.
|
||
|
||
["popupmenu_select", selected]
|
||
Select an item in the current popupmenu. `selected` is a zero-based
|
||
index into the array of items from the last popupmenu_show event, or
|
||
-1 if no item is selected.
|
||
|
||
["popupmenu_hide"]
|
||
Hide the popupmenu.
|
||
|
||
==============================================================================
|
||
Tabline Events *ui-tabline*
|
||
|
||
Activated by the `ext_tabline` |ui-option|.
|
||
|
||
["tabline_update", curtab, tabs]
|
||
Tabline was updated. UIs should present this data in a custom tabline
|
||
widget.
|
||
curtab: Current Tabpage
|
||
tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...]
|
||
|
||
==============================================================================
|
||
Cmdline Events *ui-cmdline*
|
||
|
||
Activated by the `ext_cmdline` |ui-option|.
|
||
|
||
This UI extension delegates presentation of the |cmdline| (except 'wildmenu').
|
||
For command-line 'wildmenu' UI events, activate |ui-popupmenu|.
|
||
|
||
["cmdline_show", content, pos, firstc, prompt, indent, level]
|
||
content: List of [attrs, string]
|
||
[[{}, "t"], [attrs, "est"], ...]
|
||
|
||
Triggered when the cmdline is displayed or changed.
|
||
The `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. `indent` tells how many spaces
|
||
the content should be indented.
|
||
|
||
The Nvim command line can be invoked recursively, for instance by
|
||
typing `<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 than the edited command line.
|
||
|
||
["cmdline_pos", pos, level]
|
||
Change the cursor position in the cmdline.
|
||
|
||
["cmdline_special_char", c, shift, level]
|
||
Display a special char in the cmdline at the cursor position. This is
|
||
typically used to indicate a pending state, e.g. after |c_CTRL-V|. If
|
||
`shift` is true the text after the cursor should be shifted, otherwise
|
||
it should overwrite the char at the cursor.
|
||
|
||
Should be hidden at next cmdline_show.
|
||
|
||
["cmdline_hide"]
|
||
Hide the cmdline.
|
||
|
||
["cmdline_block_show", lines]
|
||
Show a block of context to the current command line. For example if
|
||
the user defines a |:function| interactively: >
|
||
:function Foo()
|
||
: echo "foo"
|
||
:
|
||
<
|
||
`lines` is a list of lines of highlighted chunks, in the same form as
|
||
the "cmdline_show" `contents` parameter.
|
||
|
||
["cmdline_block_append", line]
|
||
Append a line at the end of the currently shown block.
|
||
|
||
["cmdline_block_hide"]
|
||
Hide the block.
|
||
|
||
==============================================================================
|
||
Message/Dialog Events *ui-messages*
|
||
|
||
Activated by the `ext_messages` |ui-option|.
|
||
Activates |ui-linegrid| and |ui-cmdline| implicitly.
|
||
|
||
This UI extension delegates presentation of messages and dialogs. Messages
|
||
that would otherwise render in the message/cmdline screen space, are emitted
|
||
as UI events.
|
||
|
||
Nvim will not allocate screen space for the cmdline or messages, and
|
||
'cmdheight' will be forced zero. Cmdline state is emitted as |ui-cmdline|
|
||
events, which the UI must handle.
|
||
|
||
["msg_show", kind, content, replace_last]
|
||
Display a message to the user.
|
||
|
||
kind
|
||
Name indicating the message kind:
|
||
"" (empty) Unknown (consider a feature-request: |bugs|)
|
||
"confirm" |confirm()| or |:confirm| dialog
|
||
"confirm_sub" |:substitute| confirm dialog |:s_c|
|
||
"emsg" Error (|errors|, internal error, |:throw|, …)
|
||
"echo" |:echo| message
|
||
"echomsg" |:echomsg| message
|
||
"echoerr" |:echoerr| message
|
||
"lua_error" Error in |:lua| code
|
||
"rpc_error" Error response from |rpcrequest()|
|
||
"return_prompt" |press-enter| prompt after a multiple messages
|
||
"quickfix" Quickfix navigation message
|
||
"search_count" Search count message ("S" flag of 'shortmess')
|
||
"wmsg" Warning ("search hit BOTTOM", |W10|, …)
|
||
New kinds may be added in the future; clients should treat unknown
|
||
kinds as the empty kind.
|
||
|
||
content
|
||
Array of `[attr_id, text_chunk]` 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".
|
||
|
||
replace_last
|
||
Decides how multiple messages should be displayed:
|
||
false: Display the message together with all previous messages
|
||
that are still visible.
|
||
true: Replace the message in the most-recent `msg_show` call,
|
||
but any other visible message should still remain.
|
||
|
||
["msg_clear"]
|
||
Clear all messages currently displayed by "msg_show". (Messages sent
|
||
by other "msg_" events below will not be affected).
|
||
|
||
["msg_showmode", content]
|
||
Shows 'showmode' and |recording| messages. `content` has the same
|
||
format as in "msg_show". This event is sent with empty `content` to
|
||
hide the last message.
|
||
|
||
["msg_showcmd", content]
|
||
Shows 'showcmd' messages. `content` has the same format as in "msg_show".
|
||
This event is sent with empty `content` to hide the last message.
|
||
|
||
["msg_ruler", content]
|
||
Used to display 'ruler' when there is no space for the ruler in a
|
||
statusline. `content` has the same format as in "msg_show". This event is
|
||
sent with empty `content` to hide the last message.
|
||
|
||
["msg_history_show", entries]
|
||
Sent when |:messages| command is invoked. History is sent as a list of
|
||
entries, where each entry is a `[kind, content]` tuple.
|
||
|
||
==============================================================================
|
||
vim:tw=78:ts=8:noet:ft=help:norl:
|