mirror of
https://github.com/neovim/neovim.git
synced 2024-12-23 04:35:04 -07:00
e50d0b6fc1
Replace the implementation cargo-culted from Vim's source with something simpler which "seems to look better" with 'pumblend'.
716 lines
30 KiB
Plaintext
716 lines
30 KiB
Plaintext
*ui.txt* Nvim
|
||
|
||
|
||
NVIM REFERENCE MANUAL
|
||
|
||
|
||
Nvim UI protocol *ui*
|
||
|
||
Type |gO| to see the table of contents.
|
||
|
||
==============================================================================
|
||
UI Events *ui-events*
|
||
|
||
GUIs can be implemented as external processes communicating with Nvim over the
|
||
RPC API. The default UI model consists of a terminal-like grid with a single,
|
||
monospace font size. The UI can opt-in to have windows drawn on separate
|
||
grids, as well as to have some elements (UI "widgets") be drawn by the UI
|
||
itself rather than by nvim ("externalized").
|
||
|
||
|
||
*ui-options*
|
||
The |nvim_ui_attach()| API method is used 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, see |ui-startup| below for details, but an UI can also
|
||
connect to a running nvim instance and invoke this method. `options` must be
|
||
a dictionary with these (optional) keys:
|
||
`rgb` Decides the color format. *ui-rgb*
|
||
Set true (default) for 24-bit RGB colors.
|
||
Set false for terminal colors (max of 256).
|
||
*ui-ext-options*
|
||
`ext_popupmenu` Externalize the popupmenu. |ui-popupmenu|
|
||
`ext_tabline` Externalize the tabline. |ui-tabline|
|
||
`ext_cmdline` Externalize the cmdline. |ui-cmdline|
|
||
`ext_wildmenu` Externalize the wildmenu. |ui-wildmenu|
|
||
`ext_messages` Externalize messages. |ui-messages|
|
||
`ext_linegrid` Use new revision of the grid events. |ui-linegrid|
|
||
`ext_multigrid` Use per-window grid based events. |ui-multigrid|
|
||
`ext_hlstate` Use detailed highlight state. |ui-hlstate|
|
||
`ext_termcolors` Use external default colors.
|
||
|
||
Specifying a non-existent option is an error. UIs can check the |api-metadata|
|
||
`ui_options` key for supported options. Additionally Nvim (currently) requires
|
||
that all connected UIs use the same set of widgets. Therefore the active
|
||
widgets will be the intersection of the requested widget sets of all connected
|
||
UIs. The "option_set" event announces which widgets actually are active.
|
||
|
||
Nvim sends msgpack-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. This allows multiple events of
|
||
the same kind to be sent in a row without the event name being repeated. This
|
||
batching is mostly used for "grid_line", because each "grid_line" event puts
|
||
contents in one grid line, but clients must be prepared for multiple argument
|
||
sets being batched for all event kinds.
|
||
|
||
Events must be handled in-order. A "flush" event is sent when nvim is done
|
||
redrawing the entire screen (so that all windows have a consistent view of
|
||
buffer state, options etc). Clients should be prepared that several "redraw"
|
||
batches are sent before the entire screen has been redrawn, and only the last
|
||
batch will end in "flush". The user should only see the final state when
|
||
"flush" is sent, and not any intermediate state after processing only part of
|
||
the batch array, nor after a batch not ending with "flush".
|
||
|
||
By default, Nvim sends |ui-global| and |ui-grid-old| events; these suffice to
|
||
implement a terminal-like interface. However there are two revisions of the
|
||
grid part of the protocol. The newer revision |ui-linegrid|, enabled by
|
||
`ext_linegrid` option, has a more effecient representation of text (especially
|
||
highlighted text), and allows extensions that use multiple grids.
|
||
|
||
The older revision is available and used by default only for backwards
|
||
compatibility reasons. New UIs are strongly recommended to use |ui-linegrid|,
|
||
as further protocol extensions require it. The |ui-multigrid| extension
|
||
enables |ui-linegrid| implicitly.
|
||
|
||
Nvim optionally sends screen elements "semantically" as structured events
|
||
instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present
|
||
those elements itself; Nvim will not draw those elements 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*
|
||
|
||
Nvim defines a standard procedure for how an embedding UI should interact with
|
||
the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag
|
||
but not the |--headless| flag. The started Nvim process will pause before loading
|
||
startup files and reading buffers, and give the UI a chance to invoke requests
|
||
to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the
|
||
startup will continue.
|
||
|
||
A simple UI only need to do a single |nvim_ui_attach()| request and then
|
||
be prepared 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 this is needed to setup the client library
|
||
and/or to get the list of supported UI extensions.
|
||
2. At this time, any configuration that should be happen before init.vim
|
||
loading should be done. 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 the init.vim file was loaded
|
||
register an autocmd for VimEnter at this point: >
|
||
|
||
nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
|
||
|
||
<4. Now invoke |nvim_ui_attach()|. The UI will need to handle keyboard input
|
||
at this point, as 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 instance reading variables set by
|
||
init.vim.
|
||
|
||
==============================================================================
|
||
Global Events *ui-global*
|
||
|
||
The following events will always be available, 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`)
|
||
`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'
|
||
'guifontset'
|
||
'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]
|
||
The mode changed. The first parameter `mode` is a string representing
|
||
the current mode. `mode_idx` is an index into the array received 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"]
|
||
Tells the client whether mouse support, as determined by |'mouse'|
|
||
option, is considered to be active in the current mode. This is mostly
|
||
useful for a terminal frontend, or other situations where nvim mouse
|
||
would conflict with other usages of the mouse. It is safe for a client
|
||
to ignore this and always send mouse events.
|
||
|
||
["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*
|
||
|
||
These events are used if `ext_linegrid` option is set (recommended for all new
|
||
UIs). The biggest change compared to previous revision is to use a single
|
||
event `grid_line` to update the contents of a screen line (where 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. Grids other
|
||
than that will be defined by future extensions. Just activating the
|
||
`ext_linegrid` option by itself will never cause any additional grids to be
|
||
created. To enable per-window grids, `ext_multigrid` option should be set (see
|
||
|ui-multigrid|).
|
||
|
||
Highlight attribute groups are predefined. UIs should maintain a table to map
|
||
numerical highlight `id`:s 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 emulators builitn
|
||
defaults are expected.
|
||
|
||
Note: unlike the corresponding events in the first revision, the
|
||
screen is not always cleared after sending this event. The GUI has to
|
||
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.
|
||
`underline`: underlined text. The line has `special` color.
|
||
`undercurl`: undercurled text. The curl has `special` color.
|
||
|
||
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: `id`:s can be reused if Nvim's internal highlight table is full.
|
||
In this case, Nvim will always issue redraws of screen cells that are
|
||
affected by redefined `id`:s, so UIs do not need to keep track of this
|
||
themselves.
|
||
|
||
`info` is an empty array per default, and will be used by the
|
||
|ui-hlstate| extension explaned below.
|
||
|
||
*ui-event-grid_line*
|
||
["grid_line", grid, row, col_start, cells]
|
||
Redraw a continous 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 the text in the a region of `grid`. 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 `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.
|
||
|
||
==============================================================================
|
||
Legacy Grid Events (cell based) *ui-grid-old*
|
||
|
||
This is an older representation of the screen grid, used if `ext_linegrid`
|
||
option is not set. New UIs should use |ui-linegrid|.
|
||
|
||
["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`: backround 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.
|
||
`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*
|
||
|
||
Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies
|
||
`ext_linegrid`.
|
||
|
||
By default, nvim will only describe grid cells using the final calculated
|
||
higlight 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
|
||
describtion of the higlights 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": A builtin ui highlight.
|
||
"syntax": highlight applied to a buffer by a syntax declaration or
|
||
other runtime/plugin functionallity such as
|
||
|nvim_buf_add_highlight()|
|
||
"terminal": highlight from a process running in a |terminal-emulator|.
|
||
Contains no futher semantic information.
|
||
`ui_name`: Name of the builtin highlight. See |highlight-groups| for
|
||
possible values. Only present for "ui".
|
||
`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*
|
||
|
||
Only sent if `ext_multigrid` option is set in |ui-options|. Enables the
|
||
`ext_linegrid` extension implicitly.
|
||
|
||
The multigrid extension gives the UIs more control over how windows are
|
||
displayed. The UIs receive updates on a separate grid for each window. The UIs
|
||
can set the grid size independently of how much space the window occupies on
|
||
the global layout. This enables the UIs to set a different font size for each
|
||
window if the UI so desires. The UI can also reserve space around the border
|
||
of the window for its own elements, for instance scrollbars from the UI
|
||
toolkit.
|
||
|
||
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 the handling of grid size back to nvim, the UIs should 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_hide", grid]
|
||
Stop displaying the window.
|
||
|
||
["win_scroll_over_start"]
|
||
Hint that following `grid_scroll` on the default grid should
|
||
scroll over windows. This is a temporary workaround to allow
|
||
UIs to use the builtin message drawing. Later on, messages will be
|
||
drawn on a dedicated grid.
|
||
|
||
["win_scroll_over_reset"]
|
||
Hint that scrolled over windows should be redrawn again, and not be
|
||
overdrawn by default grid scrolling anymore.
|
||
|
||
See |ui-linegrid| for grid events.
|
||
See |nvim_ui_try_resize_grid| in |api-ui| to request changing the grid size.
|
||
See |nvim_input_mouse| for sending mouse events to Nvim.
|
||
|
||
==============================================================================
|
||
Popupmenu Events *ui-popupmenu*
|
||
|
||
Only sent if `ext_popupmenu` option is set in |ui-options|
|
||
|
||
["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.
|
||
|
||
["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*
|
||
|
||
Only sent if `ext_tabline` option is set in |ui-options|
|
||
|
||
["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*
|
||
|
||
Only sent if `ext_cmdline` option is set in |ui-options|.
|
||
|
||
["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.
|
||
|
||
==============================================================================
|
||
Wildmenu Events *ui-wildmenu*
|
||
|
||
Only sent if `ext_wildmenu` option is set in |ui-options|
|
||
|
||
["wildmenu_show", items]
|
||
Activate the wildmenu (command-line completion). `items` is an array
|
||
with the completion items.
|
||
|
||
["wildmenu_select", selected]
|
||
Select an item in the current wildmenu. `selected` is a zero-based
|
||
index into the array of items from the last wildmenu_show event, or -1
|
||
if no item is selected.
|
||
|
||
["wildmenu_hide"]
|
||
Hide the wildmenu.
|
||
|
||
==============================================================================
|
||
Message Events *ui-messages*
|
||
|
||
Only sent if `ext_messages` option is set in |ui-options|. This option implies
|
||
`ext_linegrid` and `ext_cmdline` also being set. |ui-linegrid| and |ui-cmdline| events
|
||
will thus also be sent.
|
||
|
||
This extension allows the UI to control the display of messages that otherwise
|
||
would have been displayed in the message/cmdline area in the bottom of the
|
||
screen.
|
||
|
||
Activating this extension means that Nvim will allocate no screen space for
|
||
the cmdline or messages, and 'cmdheight' will be set to zero. Attempting to
|
||
change 'cmdheight' will silently be ignored. |ui-cmdline| events will be used
|
||
to represent the state of the cmdline.
|
||
|
||
["msg_show", kind, content, replace_last]
|
||
Display a message to the user.
|
||
|
||
`kind` will be one of the following
|
||
`emsg`: Internal error message
|
||
`echo`: temporary message from plugin (|:echo|)
|
||
`echomsg`: ordinary message from plugin (|:echomsg|)
|
||
`echoerr`: error message from plugin (|:echoerr|)
|
||
`return_prompt`: |press-enter| prompt after a group of messages
|
||
`quickfix`: Quickfix navigation message
|
||
`kind` can also be the empty string. The message is then some internal
|
||
informative or warning message, that hasn't yet been assigned a kind.
|
||
New message kinds can be added in later versions; clients should
|
||
handle messages of an unknown kind just like empty kind.
|
||
|
||
`content` will be an 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 should contain any necessary whitespace. Messages can contain
|
||
line breaks `"\n"`.
|
||
|
||
`replace_last` controls how multiple messages should be displayed.
|
||
If `replace_last` is false, this message should be displayed together
|
||
with all previous messages that are still visible. If `replace_last`
|
||
is true, this message should 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:
|