commit e78c877688123c092b1be9f11d2e8c85b70d63e8
parent 58df501913c17cb3a79f41548088d0f0bcf3a305
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Tue, 24 Jun 2025 22:11:24 +0200
docs: rename ui.txt => api-ui-events.txt
Diffstat:
2 files changed, 906 insertions(+), 903 deletions(-)
diff --git a/runtime/doc/api-ui-events.txt b/runtime/doc/api-ui-events.txt
@@ -0,0 +1,906 @@
+*api-ui-events.txt* Nvim
+
+
+ NVIM REFERENCE MANUAL
+
+
+Nvim UI protocol *UI* *ui* *api-ui-events*
+
+This document describes the UI protocol. See |gui| and |tui| for user-facing
+UI components and features.
+
+ 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 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|: >bash
+ 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 when 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: >lua
+ 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.
+
+ *ui-startup-stdin*
+UIs can support reading from stdin (like `command | nvim -`, see |--|) as follows:
+
+1. The embedding process detects that the stdin fd is not a terminal.
+2. It then needs to forward this fd to Nvim. Because fd=0 is already is used
+ to send RPC data from embedder to Nvim, it must use some other file
+ descriptor, like fd=3 or higher.
+3. Then pass the fd as the `stdin_fd` parameter of `nvim_ui_attach`. Nvim will
+ read it as text into buffer 1.
+
+==============================================================================
+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 |:lmap| is on.
+ `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.
+ `id_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'
+ - 'mousefocus'
+ - 'mousehide'
+ - 'mousemoveevent'
+ - '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|.
+
+["chdir", path] ~
+ The |current-directory| changed to `path`.
+
+["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 embedding into an application where Nvim mouse would
+ conflict with other usages of the mouse. Other UI:s may ignore this event.
+
+["busy_start"] ~
+["busy_stop"] ~
+ Indicates to the UI that it must stop rendering the cursor. This event
+ is misnamed and does not actually have anything to do with busyness.
+
+["restart", progpath, argv] ~
+ |:restart| command has been used and the Nvim server is about to exit.
+ The UI should wait for the server to exit, and then start a new server
+ using `progpath` as the full path to the Nvim executable |v:progpath| and
+ `argv` as its arguments |v:argv|, and reattach to the new server.
+ Note: |--embed| and |--headless| are excluded from `argv`, and the client
+ should decide itself whether to add either flag.
+
+["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.
+
+Unlike |ui-grid-old|, this UI extension emits a single `grid_line` event to
+update a screen-line (whereas the old protocol emitted separate cursor,
+highlight and text events per screen-line).
+
+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 various underlines, 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.
+ `underdouble`: double underlined text. The lines have `special` color.
+ `underdotted`: underdotted text. The dots have `special` color.
+ `underdashed`: underdashed text. The dashes have `special` color.
+ `altfont`: alternative font.
+ `blend`: blend level (0-100). Could be used by UIs to
+ support blending floating windows to the
+ background or to signal a transparent cursor.
+ `url`: URL associated with this highlight. UIs should
+ present the region as a clickable hyperlink.
+
+ 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 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 unless |ui-hlstate| is enabled.
+
+["hl_group_set", name, hl_id] ~
+ The built-in 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 a UI who want to render its own elements with consistent
+ highlighting. For instance a 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, wrap] ~
+ 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.
+
+ `wrap` is a boolean indicating that this line wraps to the next row.
+ When redrawing a line which wraps to the next row, Nvim will emit a
+ `grid_line` event covering the last column of the line with `wrap` set
+ to true, followed immediately by a `grid_line` event starting at the
+ first column of the next row.
+
+["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, col] ~
+ Makes `grid` the current grid and `row, col` 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 various underlines, 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.
+ `underdouble`: double underlined text. The lines have `special` color.
+ `underdotted`: underdotted text. The dots have `special` color.
+ `underdashed`: underdashed text. The dashes have `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
+ +-------------------------+
+<
+==============================================================================
+Highlight Events *ui-hlstate*
+
+Activated by the `ext_hlstate` |ui-option|.
+Activates |ui-linegrid| implicitly.
+
+If `ext_hlstate` is enabled, Nvim will emit detailed highlight state in
+|ui-linegrid| events. Otherwise (by default) Nvim only describes grid cells
+using the final calculated highlight attributes described at
+|ui-event-highlight_set|.
+
+`ext_hlstate` provides a semantic description of active highlights for each
+grid cell. Highlights are predefined in a table, see |ui-event-hl_attr_define|
+and |ui-event-grid_line|.
+
+The `info` parameter in `hl_attr_define` contains a semantic description of
+the highlights. Because highlight groups can be combined, this is an array
+where the highest-priority item is last. Each item is a dict with these 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_set_extmark()|
+ "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 |ui-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, mouse_enabled, zindex, compindex, screen_row, screen_col] ~
+ Display or reconfigure floating window `win`.
+
+ There are two alternative ways of positioning the window
+ - Manually - 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()|. NOTE: you have to manually
+ ensure that the window fits the screen, possibly by further
+ reposition it. Ignore `screen_row` and `screen_col` in this case.
+ - Let nvim take care of the positioning - You can ignore `anchor`
+ and display the window at `screen_row` and `screen_col`.
+
+ `mouse_enabled` is true if the window can receive mouse events.
+
+ `zindex` is the configured zindex, while `compindex` is the exact
+ rendering order of the windows determined by nvim. To render exactly
+ like the TUI, first render all the non-floating windows, then render
+ in the `compindex` order, overwriting any floating window cells.
+ Finally, blend the floating window cells against the non-floating
+ background. To add more blending, you can group the windows by zindex,
+ and blend between the layers. But note that windows inside the same
+ zindex should still overwrite previous cells inside the same layer
+ without blending. This ensures that plugins that render multiple
+ windows, to add borders for example, work as expected.
+
+["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, zindex, compindex] ~
+ 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 |msgsep|. The Builtin
+ TUI draws a full line filled with `sep_char` ('fillchars' msgsep
+ field) and |hl-MsgSeparator| highlight.
+
+ When |ui-messages| is active, no message grid is used, and this event
+ will not be sent.
+
+ `zindex` and `compindex` have the same meaning as for `win_float_pos`.
+ The `zindex` always has a fixed value of 200 and included for
+ completeness.
+
+["win_viewport", grid, win, topline, botline, curline, curcol, line_count, scroll_delta] ~
+ 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. `scroll_delta` contains how much
+ the top line of a window moved since `win_viewport` was last emitted.
+ It is intended to be used to implement smooth scrolling. For this
+ purpose it only counts "virtual" or "displayed" lines, so folds
+ only count as one line. When scrolling more than a full screen it is
+ an approximate value.
+
+ All updates, such as `grid_line`, in a batch affects the new viewport,
+ despite the fact that `win_viewport` is received after the updates.
+ Applications implementing, for example, smooth scrolling should take
+ this into account and keep the grid separated from what's displayed on
+ the screen and copy it to the viewport destination once `win_viewport`
+ is received.
+
+["win_viewport_margins", grid, win, top, bottom, left, right] ~
+ Indicates the margins of a window grid which are _not_ part of the
+ viewport as indicated by the `win_viewport` event. This happens
+ e.g. in the presence of 'winbar' and floating window borders.
+
+["win_extmark", grid, win, ns_id, mark_id, row, col] ~
+ Updates the position of an extmark which is currently visible in a
+ window. Only emitted if the mark has the `ui_watched` attribute.
+
+==============================================================================
+Popupmenu Events *ui-popupmenu*
+
+Activated by the `ext_popupmenu` |ui-option|.
+
+This UI extension delegates presentation of the |popupmenu-completion| and
+command-line 'wildmenu'.
+
+The UI decides how to present the menu. For example, depending on the last
+`mode_change` event, command-line wildmenu may be presented horizontally,
+while insert-mode completion would show a vertical popupmenu.
+
+["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, curbuf, buffers] ~
+ Tabline was updated. UIs should present this data in a custom tabline
+ widget. Note: options `curbuf` + `buffers` were added in API7.
+ curtab: Current Tabpage
+ tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...]
+ curbuf: Current buffer handle.
+ buffers: List of Dicts [{ "buffer": buffer handle, "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, hl_id] ~
+ content: List of [attrs, string, hl_id]
+ [[{}, "t", hl_id], [attrs, "est", hl_id], ...]
+
+ 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, highlighted with `hl_id`.
+ `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 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", level, abort] ~
+ Hide the cmdline. `level` is the nesting level of the cmdline being hidden.
+ `abort` is true if the cmdline is hidden after an aborting condition
+ (|c_Esc| or |c_CTRL-C|).
+
+["cmdline_block_show", lines] ~
+ Show a block of context to the current command line. For example if
+ the user defines a |:function| interactively: >vim
+ :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. 'cmdheight'
+will be set to zero, but can be changed and used for the replacing cmdline or
+message window. Cmdline state is emitted as |ui-cmdline| events, which the UI
+must handle.
+
+["msg_show", kind, content, replace_last, history, append] ~
+ Display a message to the user.
+
+ kind
+ Name indicating the message kind:
+ "" (empty) Unknown (consider a |feature-request|)
+ "empty" Empty message (`:echo ""`), with empty `content`.
+ Should clear messages sharing the 'cmdheight'
+ area if it is the only message in a batch.
+ "bufwrite" |:write| message
+ "confirm" Message preceding a prompt (|:confirm|,
+ |confirm()|, |inputlist()|, |z=|, …)
+ "emsg" Error (|errors|, internal error, |:throw|, …)
+ "echo" |:echo| message
+ "echomsg" |:echomsg| message
+ "echoerr" |:echoerr| message
+ "completion" |ins-completion-menu| message
+ "list_cmd" List output for various commands (|:ls|, |:set|, …)
+ "lua_error" Error in |:lua| code
+ "lua_print" |print()| from |:lua| code
+ "rpc_error" Error response from |rpcrequest()|
+ "quickfix" Quickfix navigation message
+ "search_cmd" Entered search command
+ "search_count" Search count message ("S" flag of 'shortmess')
+ "shell_cmd" |:!cmd| executed command
+ "shell_err" |:!cmd| shell stderr output
+ "shell_out" |:!cmd| shell stdout output
+ "shell_ret" |:!cmd| shell return code
+ "undo" |:undo| and |:redo| message
+ "verbose" 'verbose' message
+ "wildlist" 'wildmode' "list" message
+ "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, hl_id]` 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.
+
+ history
+ True if the message was added to the |:messages| history.
+
+ append
+ True if the message should be appeneded to the previous message,
+ rather than started on a new line. Is set for |:echon|.
+
+["msg_clear"] ~
+ Clear all messages currently displayed by "msg_show", emitted after
+ clearing the screen (messages sent by other "msg_" events below should
+ 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, prev_cmd] ~
+ Sent when |:messages| or |g<| command is invoked. History is sent as a
+ list of entries, where each entry is a `[kind, content, append]` tuple.
+
+ prev_cmd
+ True when sent with |g<| command, false with |:messages|.
+
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
@@ -1,903 +0,0 @@
-*ui.txt* Nvim
-
-
- NVIM REFERENCE MANUAL
-
-
-Nvim UI protocol *UI* *ui* *api-ui-events*
-
- 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 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|: >bash
- 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 when 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: >lua
- 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.
-
- *ui-startup-stdin*
-UIs can support reading from stdin (like `command | nvim -`, see |--|) as follows:
-
-1. The embedding process detects that the stdin fd is not a terminal.
-2. It then needs to forward this fd to Nvim. Because fd=0 is already is used
- to send RPC data from embedder to Nvim, it must use some other file
- descriptor, like fd=3 or higher.
-3. Then pass the fd as the `stdin_fd` parameter of `nvim_ui_attach`. Nvim will
- read it as text into buffer 1.
-
-==============================================================================
-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 |:lmap| is on.
- `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.
- `id_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'
- - 'mousefocus'
- - 'mousehide'
- - 'mousemoveevent'
- - '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|.
-
-["chdir", path] ~
- The |current-directory| changed to `path`.
-
-["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 embedding into an application where Nvim mouse would
- conflict with other usages of the mouse. Other UI:s may ignore this event.
-
-["busy_start"] ~
-["busy_stop"] ~
- Indicates to the UI that it must stop rendering the cursor. This event
- is misnamed and does not actually have anything to do with busyness.
-
-["restart", progpath, argv] ~
- |:restart| command has been used and the Nvim server is about to exit.
- The UI should wait for the server to exit, and then start a new server
- using `progpath` as the full path to the Nvim executable |v:progpath| and
- `argv` as its arguments |v:argv|, and reattach to the new server.
- Note: |--embed| and |--headless| are excluded from `argv`, and the client
- should decide itself whether to add either flag.
-
-["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.
-
-Unlike |ui-grid-old|, this UI extension emits a single `grid_line` event to
-update a screen-line (whereas the old protocol emitted separate cursor,
-highlight and text events per screen-line).
-
-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 various underlines, 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.
- `underdouble`: double underlined text. The lines have `special` color.
- `underdotted`: underdotted text. The dots have `special` color.
- `underdashed`: underdashed text. The dashes have `special` color.
- `altfont`: alternative font.
- `blend`: blend level (0-100). Could be used by UIs to
- support blending floating windows to the
- background or to signal a transparent cursor.
- `url`: URL associated with this highlight. UIs should
- present the region as a clickable hyperlink.
-
- 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 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 unless |ui-hlstate| is enabled.
-
-["hl_group_set", name, hl_id] ~
- The built-in 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 a UI who want to render its own elements with consistent
- highlighting. For instance a 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, wrap] ~
- 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.
-
- `wrap` is a boolean indicating that this line wraps to the next row.
- When redrawing a line which wraps to the next row, Nvim will emit a
- `grid_line` event covering the last column of the line with `wrap` set
- to true, followed immediately by a `grid_line` event starting at the
- first column of the next row.
-
-["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, col] ~
- Makes `grid` the current grid and `row, col` 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 various underlines, 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.
- `underdouble`: double underlined text. The lines have `special` color.
- `underdotted`: underdotted text. The dots have `special` color.
- `underdashed`: underdashed text. The dashes have `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
- +-------------------------+
-<
-==============================================================================
-Highlight Events *ui-hlstate*
-
-Activated by the `ext_hlstate` |ui-option|.
-Activates |ui-linegrid| implicitly.
-
-If `ext_hlstate` is enabled, Nvim will emit detailed highlight state in
-|ui-linegrid| events. Otherwise (by default) Nvim only describes grid cells
-using the final calculated highlight attributes described at
-|ui-event-highlight_set|.
-
-`ext_hlstate` provides a semantic description of active highlights for each
-grid cell. Highlights are predefined in a table, see |ui-event-hl_attr_define|
-and |ui-event-grid_line|.
-
-The `info` parameter in `hl_attr_define` contains a semantic description of
-the highlights. Because highlight groups can be combined, this is an array
-where the highest-priority item is last. Each item is a dict with these 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_set_extmark()|
- "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 |ui-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, mouse_enabled, zindex, compindex, screen_row, screen_col] ~
- Display or reconfigure floating window `win`.
-
- There are two alternative ways of positioning the window
- - Manually - 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()|. NOTE: you have to manually
- ensure that the window fits the screen, possibly by further
- reposition it. Ignore `screen_row` and `screen_col` in this case.
- - Let nvim take care of the positioning - You can ignore `anchor`
- and display the window at `screen_row` and `screen_col`.
-
- `mouse_enabled` is true if the window can receive mouse events.
-
- `zindex` is the configured zindex, while `compindex` is the exact
- rendering order of the windows determined by nvim. To render exactly
- like the TUI, first render all the non-floating windows, then render
- in the `compindex` order, overwriting any floating window cells.
- Finally, blend the floating window cells against the non-floating
- background. To add more blending, you can group the windows by zindex,
- and blend between the layers. But note that windows inside the same
- zindex should still overwrite previous cells inside the same layer
- without blending. This ensures that plugins that render multiple
- windows, to add borders for example, work as expected.
-
-["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, zindex, compindex] ~
- 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 |msgsep|. The Builtin
- TUI draws a full line filled with `sep_char` ('fillchars' msgsep
- field) and |hl-MsgSeparator| highlight.
-
- When |ui-messages| is active, no message grid is used, and this event
- will not be sent.
-
- `zindex` and `compindex` have the same meaning as for `win_float_pos`.
- The `zindex` always has a fixed value of 200 and included for
- completeness.
-
-["win_viewport", grid, win, topline, botline, curline, curcol, line_count, scroll_delta] ~
- 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. `scroll_delta` contains how much
- the top line of a window moved since `win_viewport` was last emitted.
- It is intended to be used to implement smooth scrolling. For this
- purpose it only counts "virtual" or "displayed" lines, so folds
- only count as one line. When scrolling more than a full screen it is
- an approximate value.
-
- All updates, such as `grid_line`, in a batch affects the new viewport,
- despite the fact that `win_viewport` is received after the updates.
- Applications implementing, for example, smooth scrolling should take
- this into account and keep the grid separated from what's displayed on
- the screen and copy it to the viewport destination once `win_viewport`
- is received.
-
-["win_viewport_margins", grid, win, top, bottom, left, right] ~
- Indicates the margins of a window grid which are _not_ part of the
- viewport as indicated by the `win_viewport` event. This happens
- e.g. in the presence of 'winbar' and floating window borders.
-
-["win_extmark", grid, win, ns_id, mark_id, row, col] ~
- Updates the position of an extmark which is currently visible in a
- window. Only emitted if the mark has the `ui_watched` attribute.
-
-==============================================================================
-Popupmenu Events *ui-popupmenu*
-
-Activated by the `ext_popupmenu` |ui-option|.
-
-This UI extension delegates presentation of the |popupmenu-completion| and
-command-line 'wildmenu'.
-
-The UI decides how to present the menu. For example, depending on the last
-`mode_change` event, command-line wildmenu may be presented horizontally,
-while insert-mode completion would show a vertical popupmenu.
-
-["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, curbuf, buffers] ~
- Tabline was updated. UIs should present this data in a custom tabline
- widget. Note: options `curbuf` + `buffers` were added in API7.
- curtab: Current Tabpage
- tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...]
- curbuf: Current buffer handle.
- buffers: List of Dicts [{ "buffer": buffer handle, "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, hl_id] ~
- content: List of [attrs, string, hl_id]
- [[{}, "t", hl_id], [attrs, "est", hl_id], ...]
-
- 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, highlighted with `hl_id`.
- `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 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", level, abort] ~
- Hide the cmdline. `level` is the nesting level of the cmdline being hidden.
- `abort` is true if the cmdline is hidden after an aborting condition
- (|c_Esc| or |c_CTRL-C|).
-
-["cmdline_block_show", lines] ~
- Show a block of context to the current command line. For example if
- the user defines a |:function| interactively: >vim
- :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. 'cmdheight'
-will be set to zero, but can be changed and used for the replacing cmdline or
-message window. Cmdline state is emitted as |ui-cmdline| events, which the UI
-must handle.
-
-["msg_show", kind, content, replace_last, history, append] ~
- Display a message to the user.
-
- kind
- Name indicating the message kind:
- "" (empty) Unknown (consider a |feature-request|)
- "empty" Empty message (`:echo ""`), with empty `content`.
- Should clear messages sharing the 'cmdheight'
- area if it is the only message in a batch.
- "bufwrite" |:write| message
- "confirm" Message preceding a prompt (|:confirm|,
- |confirm()|, |inputlist()|, |z=|, …)
- "emsg" Error (|errors|, internal error, |:throw|, …)
- "echo" |:echo| message
- "echomsg" |:echomsg| message
- "echoerr" |:echoerr| message
- "completion" |ins-completion-menu| message
- "list_cmd" List output for various commands (|:ls|, |:set|, …)
- "lua_error" Error in |:lua| code
- "lua_print" |print()| from |:lua| code
- "rpc_error" Error response from |rpcrequest()|
- "quickfix" Quickfix navigation message
- "search_cmd" Entered search command
- "search_count" Search count message ("S" flag of 'shortmess')
- "shell_cmd" |:!cmd| executed command
- "shell_err" |:!cmd| shell stderr output
- "shell_out" |:!cmd| shell stdout output
- "shell_ret" |:!cmd| shell return code
- "undo" |:undo| and |:redo| message
- "verbose" 'verbose' message
- "wildlist" 'wildmode' "list" message
- "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, hl_id]` 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.
-
- history
- True if the message was added to the |:messages| history.
-
- append
- True if the message should be appeneded to the previous message,
- rather than started on a new line. Is set for |:echon|.
-
-["msg_clear"] ~
- Clear all messages currently displayed by "msg_show", emitted after
- clearing the screen (messages sent by other "msg_" events below should
- 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, prev_cmd] ~
- Sent when |:messages| or |g<| command is invoked. History is sent as a
- list of entries, where each entry is a `[kind, content, append]` tuple.
-
- prev_cmd
- True when sent with |g<| command, false with |:messages|.
-
- vim:tw=78:ts=8:noet:ft=help:norl:
