@@ -11,22 +11,23 @@ Nvim UI protocol *ui*
==============================================================================
UI Events *ui-events*
G UIs 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").
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-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 ×
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*
*ui-option*
Call |nvim_ui_attach()| to tell Nvim that your program wants to draw the Nvim
screen grid with a size of width ×
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
@@ -34,54 +35,74 @@ a dictionary with these (optional) keys:
false: (default) Disable UI capabilities not
supported by all connected UIs
(including TUI).
*ui-ext-options*
*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_cmdline` Externalize the cmdline. |ui-cmdline|
`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.
Specifying an unknown option is an error; UIs can check the |api-metadata|
`ui_options` key for supported options.
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 e ven t 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.
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 in ver t th is behavior (useful for debugging). The
"option_set" event announces which capabilities are active.
Ev ent s 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"
batche s are s ent 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".
Nvim s end s 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
element s are ev ent-parameter tuples. Thus multiple events of the same kind can
be sent contiguously without repeating the event name.
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 efficient representation of text (especially
highlighted text), and allows extensions that use multiple grids.
Example of a typical "redraw" batch in a single RPC notification: >
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.
['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', []]
]
]
Nvim optionally sends screen elements "semantically" as structured event s
ins tea d 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.
Events must be handled in-order. Nvim sends a "flush" event when it ha s
comple ted 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,
@@ -99,7 +120,7 @@ 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 n vim process, should use the following startup
additional configuration of the N vim process, should use the following startup
procedure:
1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or
@@ -119,7 +140,7 @@ procedure:
==============================================================================
Global Events *ui-global*
The following events will always be available , and describe global state of
The following UI events are always emitted , and describe global state of
the editor.
["set_title", title]
@@ -192,7 +213,7 @@ the editor.
["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 n vim mouse
useful for a terminal frontend, or other situations where N vim mouse
would conflict with other usages of the mouse. It is safe for a client
to ignore this and always send mouse events.
@@ -221,17 +242,17 @@ the editor.
==============================================================================
Grid Events (line-based) *ui-linegrid*
These events are used if `ext_linegrid` option is set (r ecommended for all new
UIs). The biggest change compared to previous revision is to use a single
`grid_line` event to update the contents of a screen line (where the old
protocol used a combination of cursor, highlight and text events)
Activated by the `ext_linegrid` |ui- option|. R ecommended 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. Grids ot her
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|).
global grid used by default for the entire editor screen state. T he
`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.
@@ -375,10 +396,10 @@ numerical highlight ids to the actual attributes.
part of handling the scroll event.
==============================================================================
Legacy Grid Events (cell based) *ui-grid-old*
Grid Events (cell- based) *ui-grid-old*
This is an older representation of the screen grid, us ed if `ext_ linegrid`
option is not set . New UIs should use |ui-linegrid|.
This is the legacy representation of the screen grid, emitt ed 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.
@@ -465,8 +486,8 @@ option is not set. New UIs should use |ui-linegrid|.
==============================================================================
Detailed highlight state Extension *ui-hlstate*
Only sent if `ext_hlstate` option is set in |ui-options |. `ext_hlstate` implies
`ext_linegrid` .
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|.
@@ -499,30 +520,32 @@ 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.
Activated by the `ext_multigrid` |ui-option|.
Activates |ui-linegrid| 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.
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.
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 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.
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 th e handling of grid size back to n vim, the UIs should request the
size (0, 0).
delegate grid-siz e handling back to N vim, 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 n vim (i.e. the outer grid
Set the position and size of the grid in N vim (i.e. the outer grid
size). If the window was previously hidden, it should now be shown
again.
@@ -553,15 +576,13 @@ tabs.
["win_close", grid]
Close the window.
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 |.
Events for |popupmenu-completion| and command-line 'wildmenu'.
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
@@ -586,7 +607,7 @@ Events for |popupmenu-completion| and command-line 'wildmenu'.
==============================================================================
Tabline Events *ui-tabline*
Only sent if `ext_tabline` option is set in |ui-options |
Activated by the `ext_tabline` |ui-option|.
["tabline_update", curtab, tabs]
Tabline was updated. UIs should present this data in a custom tabline
@@ -597,8 +618,10 @@ Only sent if `ext_tabline` option is set in |ui-options|
==============================================================================
Cmdline Events *ui-cmdline*
Only sent if `ext_cmdline` option is set in |ui-options |. To handle
command-line 'wildmenu', enable |ui-popupmenu| and handle its events.
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]
@@ -654,20 +677,18 @@ command-line 'wildmenu', enable |ui-popupmenu| and handle its events.
Hide the block.
==============================================================================
Message Events *ui-messages*
Message/Dialog Events *ui-messages*
Only sent if `ext_messages` option is set in |ui-options |. This option
implicitly enables `ext_ linegrid` and `ext_ cmdline`. |ui-linegrid| and
|ui-cmdline| events will thus also be sent.
Activated by the `ext_messages` |ui-option|.
Activates |ui- linegrid| and |ui- cmdline| implicitly.
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 .
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 .
Activating this extension means that Nvim will not allocate screen space for
the cmdline or messages, 'cmdheight' will be zero. Attempting to change
'cmdheight' will be silently ignored. |ui-cmdline| events represent the state
of the cmdline.
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.
Justin M. Keyes