@@ -11,22 +11,23 @@ Nvim UI protocol *ui*
==============================================================================
==============================================================================
UI Events *ui-events*
UI Events *ui-events*
G UIs can be implemented as external processes communicating with Nvim over the UIs can be implemented as external client processes communicating with Nvim
RPC API. The default UI model consists of a terminal-like grid with a single,
over the RPC API. The default UI model is a terminal-like grid with a single,
monospace font size . The UI can opt-in to have windows drawn on separate
monospace font. The UI can opt-in to have windows drawn on separate grids, and
grids, as well as to have some elements (UI "widgets") be drawn by the UIhave some elements ("widgets") presented by the UI itself rather than by Nvim
itself rather than by nvim ("externalized").("externalized").
*ui-option*
*ui-options* Call |nvim_ui_attach()| to tell Nvim that your program wants to draw the Nvim
The |nvim_ui_attach()| API method is used to tell Nvim that your program wants to screen grid with a size of width ×
draw the Nvim screen grid with a size of width × embedder at startup (see |ui-startup|), but UIs can also connect to a running
done by an embedder, see |ui-startup| below for details, but an UI can also Nvim instance and invoke nvim_ui_attach(). The `options` parameter is a map
connect to a running nvim instance and invoke this method. `options` must be with these (optional) keys:
a dictionary with these (optional) keys: *ui-rgb*
`rgb` Decides the color format. *ui-rgb*
`rgb` Decides the color format.
true: (default) 24-bit RGB colors
true: (default) 24-bit RGB colors
false: Terminal colors (8-bit, max 256)
false: Terminal colors (8-bit, max 256)
*ui-override*
`override` Decides how UI capabilities are resolved.
`override` Decides how UI capabilities are resolved.
true: Enable requested UI capabilities, even
true: Enable requested UI capabilities, even
if not supported by all connected UIs
if not supported by all connected UIs
@@ -34,54 +35,74 @@ a dictionary with these (optional) keys:
false: (default) Disable UI capabilities not
false: (default) Disable UI capabilities not
supported by all connected UIs
supported by all connected UIs
(including TUI).
(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
`ext_popupmenu` Externalize |popupmenu-completion| and
'wildmenu'. |ui-popupmenu|
'wildmenu'. |ui-popupmenu|
`ext_tabline` Externalize the tabline. |ui-tabline|
`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.
`ext_termcolors` Use external default colors.
Specifying a non-existent option is an error. UIs can check the |api-metadata|
Specifying an unknown option is an error; UIs can check the |api-metadata|
`ui_options` key for supported options. Additionally Nvim (currently) requires
`ui_options` key for supported options.
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 By default Nvim requires all connected UIs to support the same capabilities,
"redraw" and a single argument: an array (batch) of screen "update events". thus the active capabilities are the intersection of those requested. UIs may
Each update e ven t is itself an array whose first element is the event name and specify |ui-override| to in ver t th is behavior (useful for debugging). The
remaining elements are event-parameter tuples. This allows multiple events of "option_set" event announces which capabilities are active.
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.
Ev ent s must be handled in-order. A "flush" event is sent when nvim is done Nvim s end s RPC notifications to all attached UIs, with method name "redraw"
redrawing the entire screen (so that all windows have a consistent view of and a single argument: an array (batch) of screen "update events". Each update
buffer state, options etc). Clients should be prepared that several "redraw" event is itself an array whose first element is the event name and remaining
batche s are s ent before the entire screen has been redrawn, and only the last element s are ev ent-parameter tuples. Thus multiple events of the same kind can
batch will end in "flush". The user should only see the final state when
be sent contiguously without repeating the event name.
"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 Example of a typical "redraw" batch in a single RPC notification: >
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.
The older revision is available and used by default only for backwards ['notification', 'redraw',
compatibility reasons. New UIs are strongly recommended to use |ui-linegrid|, [
as further protocol extensions require it. The |ui-multigrid| extension ['grid_resize', [2, 77, 36]],
enables |ui-linegrid| implicitly. ['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 sEvents must be handled in-order. Nvim sends a "flush" event when it ha s
ins tea d of raw grid-lines, controlled by |ui-ext-options|. The UI must present comple ted a redraw of the entire screen (so all windows have a consistent view
those elements itself; Nvim will not draw those elements on the grid. 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
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,
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
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
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:
procedure:
1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or
1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or
@@ -119,7 +140,7 @@ procedure:
==============================================================================
==============================================================================
Global Events *ui-global*
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.
the editor.
["set_title", title]
["set_title", title]
@@ -192,7 +213,7 @@ the editor.
["mouse_off"]
["mouse_off"]
Tells the client whether mouse support, as determined by |'mouse'|
Tells the client whether mouse support, as determined by |'mouse'|
option, is considered to be active in the current mode. This is mostly
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
would conflict with other usages of the mouse. It is safe for a client
to ignore this and always send mouse events.
to ignore this and always send mouse events.
@@ -221,17 +242,17 @@ the editor.
==============================================================================
==============================================================================
Grid Events (line-based) *ui-linegrid*
Grid Events (line-based) *ui-linegrid*
These events are used if `ext_linegrid` option is set (r ecommended for all newActivated by the `ext_linegrid` |ui- option|. R ecommended for all new UIs.
UIs). The biggest change compared to previous revision is to use a single Deactivates |ui-grid-old| implicitly.
`grid_line` event to update the contents of a screen line (where the old
protocol used a combination of cursor, highlight and text events) 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
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
global grid used by default for the entire editor screen state. T he
than that will be defined by future extensions. Just activating the `ext_linegrid` capability by itself will never cause any additional grids to
`ext_linegrid` option by itself will never cause any additional grids to be be created; to enable per-window grids, activate |ui-multigrid|.
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
Highlight attribute groups are predefined. UIs should maintain a table to map
numerical highlight ids to the actual attributes.
numerical highlight ids to the actual attributes.
@@ -375,10 +396,10 @@ numerical highlight ids to the actual attributes.
part of handling the scroll event.
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`
This is the legacy representation of the screen grid, emitt ed if |ui- linegrid|
option is not set . New UIs should use |ui-linegrid|.is not active . New UIs should implement |ui-linegrid| instead .
["resize", width, height]
["resize", width, height]
The grid is resized to `width` and `height` cells.
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*
Detailed highlight state Extension *ui-hlstate*
Only sent if `ext_hlstate` option is set in |ui-options |. `ext_hlstate` implies Activated by the `ext_hlstate` |ui-option|.
`ext_linegrid` .Activates |ui-linegrid| implicitly .
By default Nvim will only describe grid cells using the final calculated
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|.
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*
Multigrid Events *ui-multigrid*
Only sent if `ext_multigrid` option is set in |ui-options |. Enables the Activated by the `ext_multigrid` |ui-option|.
`ext_linegrid` extension implicitly.Activates |ui-linegrid| implicitly.
The multigrid extension gives the UIs more control over how windows are See |ui-linegrid| for grid events.
displayed. The UIs receive updates on a separate grid for each window. The UIs See |nvim_ui_try_resize_grid()| to request changing the grid size.
can set the grid size independently of how much space the window occupies on See |nvim_input_mouse()| for sending mouse events to Nvim.
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 The multigrid extension gives UIs more control over how windows are displayed:
(i.e. the size of the window frame in nvim) whenever the split is created .- UIs receive updates on a separate grid for each window .
Once a UI sets a grid size, nvim does not handle the size for that grid and - 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
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
delegate grid-siz e handling back to N vim, request the size (0, 0).
size (0, 0).
A window can be hidden and redisplayed without its grid being deallocated.
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
This can happen multiple times for the same window, for instance when switching
tabs.
tabs.
["win_pos", grid, win, start_row, start_col, width, height]
["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
size). If the window was previously hidden, it should now be shown
again.
again.
@@ -553,15 +576,13 @@ tabs.
["win_close", grid]
["win_close", grid]
Close the window.
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*
Popupmenu Events *ui-popupmenu*
Only sent if `ext_popupmenu` option is set in |ui-options |.Activated by the `ext_popupmenu` |ui-option|.
Events for |popupmenu-completion| and command-line 'wildmenu'.
This UI extension delegates presentation of the |popupmenu-completion| and
command-line 'wildmenu'.
["popupmenu_show", items, selected, row, col, grid]
["popupmenu_show", items, selected, row, col, grid]
Show |popupmenu-completion|. `items` is an array of completion items
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*
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_update", curtab, tabs]
Tabline was updated. UIs should present this data in a custom tabline
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*
Cmdline Events *ui-cmdline*
Only sent if `ext_cmdline` option is set in |ui-options |. To handle Activated by the `ext_cmdline` |ui-option|.
command-line 'wildmenu', enable |ui-popupmenu| and handle its events.
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]
["cmdline_show", content, pos, firstc, prompt, indent, level]
content: List of [attrs, string]
content: List of [attrs, string]
@@ -654,20 +677,18 @@ command-line 'wildmenu', enable |ui-popupmenu| and handle its events.
Hide the block.
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 Activated by the `ext_messages` |ui-option|.
implicitly enables `ext_ linegrid` and `ext_ cmdline`. |ui-linegrid| and Activates |ui- linegrid| and |ui- cmdline| implicitly.
|ui-cmdline| events will thus also be sent.
This extension allows the UI to control the display of messages that otherwise
This UI extension delegates presentation of messages and dialogs. Messages
would have been displayed in the message/cmdline area in the bottom of the
that would otherwise render in the message/cmdline screen space, are emitted
screen .as UI events .
Activating this extension means that Nvim will not allocate screen space forNvim will not allocate screen space for the cmdline or messages, and
the cmdline or messages, 'cmdheight' will be zero. Attempting to change 'cmdheight' will be forced zero. Cmdline state is emitted as |ui-cmdline|
'cmdheight' will be silently ignored. |ui-cmdline| events represent the state events, which the UI must handle.
of the cmdline.
["msg_show", kind, content, replace_last]
["msg_show", kind, content, replace_last]
Display a message to the user.
Display a message to the user.
Justin M. Keyes