*ui.txt*	Nvim


			    NVIM REFERENCE MANUAL


Nvim UI protocol					*UI* *ui*

                                      Type |gO| to see the table of contents.

==============================================================================
UI Events						*ui-protocol* *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.
- `term_name`		Sets the name of the terminal 'term'.
- `term_colors`		Sets the number of supported colors 't_Co'.
- `stdin_fd`		Read buffer 1 from this fd as if it were stdin |--|.
			Only from |--embed| UI on startup. |ui-startup-stdin|
- `stdin_tty`		Tells if `stdin` is a `tty` or not.
- `stdout_tty`		Tells if `stdout` is a `tty` or not.

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]], false],
	  [2, 1, 0, [['~', 7], [' ', 7, 76]], false],
	  [2, 9, 0, [['~', 7], [' ', 7, 76]], false],
	  ...
	  [2, 35, 0, [['~', 7], [' ', 7, 76]], false],
	  [1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']], false],
	  [1, 36, 9, [[' ', 9, 50]], false],
	  [1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]], false]
	],
	['msg_showmode', [[]]],
	['win_pos', [2, 1000, 0, 0, 77, 36]],
	['grid_cursor_goto', [2, 0, 0]],
	['flush', []]
      ]
    ]

Events must be handled in-order. Nvim sends a "flush" event when it has
completed a redraw of the entire screen (so all windows have a consistent