2017-09-10 04:01:18 -04:00
|
|
|
|
*ui.txt* Nvim
|
|
|
|
|
|
|
|
|
|
|
2017-10-28 17:49:41 -04:00
|
|
|
|
NVIM REFERENCE MANUAL
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
|
2017-10-28 17:49:41 -04:00
|
|
|
|
Nvim UI protocol *ui*
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
2017-10-28 17:49:41 -04:00
|
|
|
|
Type |gO| to see the table of contents.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
==============================================================================
|
2017-11-14 04:47:49 -05:00
|
|
|
|
UI Events *ui-events*
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
GUIs can be implemented as external processes communicating with Nvim over the
|
|
|
|
|
RPC API. The UI model consists of a terminal-like grid with a single,
|
|
|
|
|
monospace font size. Some elements (UI "widgets") can be drawn separately from
|
|
|
|
|
the grid ("externalized").
|
|
|
|
|
|
2018-09-28 07:17:16 -04:00
|
|
|
|
|
2017-10-28 17:49:41 -04:00
|
|
|
|
*ui-options*
|
2018-09-29 07:28:53 -04:00
|
|
|
|
The |nvim_ui_attach()| API method is used to tell Nvim that your program wants to
|
|
|
|
|
draw the Nvim screen grid with a size of width × height cells. This is typically
|
|
|
|
|
done by an embedder, see |ui-startup| below for details, but an UI can also
|
2018-09-28 07:17:16 -04:00
|
|
|
|
connect to a running nvim instance and invoke this method. `options` must be
|
2017-09-10 04:01:18 -04:00
|
|
|
|
a dictionary with these (optional) keys:
|
2018-08-25 10:38:24 -04:00
|
|
|
|
`rgb` Decides the color format. *ui-rgb*
|
2017-10-28 17:49:41 -04:00
|
|
|
|
Set true (default) for 24-bit RGB colors.
|
|
|
|
|
Set false for terminal colors (max of 256).
|
|
|
|
|
*ui-ext-options*
|
2017-09-10 04:01:18 -04:00
|
|
|
|
`ext_popupmenu` Externalize the popupmenu. |ui-popupmenu|
|
|
|
|
|
`ext_tabline` Externalize the tabline. |ui-tabline|
|
|
|
|
|
`ext_cmdline` Externalize the cmdline. |ui-cmdline|
|
2018-08-25 10:38:24 -04:00
|
|
|
|
`ext_wildmenu` Externalize the wildmenu. |ui-wildmenu|
|
2018-09-28 08:19:37 -04:00
|
|
|
|
`ext_linegrid` Use new revision of the grid events. |ui-linegrid|
|
2018-04-30 17:01:47 -04:00
|
|
|
|
`ext_hlstate` Use detailed highlight state. |ui-hlstate|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
2018-06-27 18:48:17 -04:00
|
|
|
|
Specifying a non-existent option is an error. UIs can check the |api-metadata|
|
|
|
|
|
`ui_options` key for supported options. Additionally Nvim (currently) requires
|
2018-02-13 07:45:49 -05:00
|
|
|
|
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
|
2018-06-27 18:48:17 -04:00
|
|
|
|
UIs. The "option_set" event announces which widgets actually are active.
|
|
|
|
|
|
|
|
|
|
Nvim sends msgpack-rpc notifications to all attached UIs, with method name
|
|
|
|
|
"redraw" and a single argument: an array (batch) of screen "update events".
|
|
|
|
|
Each update event is itself an array whose first element is the event name and
|
|
|
|
|
remaining elements are event-parameter tuples. This allows multiple events of
|
|
|
|
|
the same kind to be sent in a row without the event name being repeated. This
|
2018-09-29 07:28:53 -04:00
|
|
|
|
batching is mostly used for "grid_line", because each "grid_line" event puts
|
|
|
|
|
contents in one screen line, but clients must be prepared for multiple argument
|
|
|
|
|
sets being batched for all event kinds.
|
|
|
|
|
|
|
|
|
|
Events must be handled in-order. A "flush" event is sent when nvim is done
|
|
|
|
|
redrawing the entire screen (so that all windows have a consistent view of
|
|
|
|
|
buffer state, options etc). Clients should be prepared that several "redraw"
|
|
|
|
|
batches are sent before the entire screen has been redrawn, and only the last
|
|
|
|
|
batch will end in "flush". The user should only see the final state when
|
|
|
|
|
"flush" is sent, and not any intermediate state after processing only part of
|
|
|
|
|
the batch array, nor after a batch not ending with "flush".
|
2017-10-28 17:49:41 -04:00
|
|
|
|
|
2018-04-30 17:01:47 -04:00
|
|
|
|
By default, Nvim sends |ui-global| and |ui-grid-old| events; these suffice to
|
|
|
|
|
implement a terminal-like interface. However there are two revisions of the
|
2018-09-28 08:19:37 -04:00
|
|
|
|
grid part of the protocol. The newer revision |ui-linegrid|, enabled by
|
|
|
|
|
`ext_linegrid` option, has a more effecient representation of text (especially
|
|
|
|
|
highlighted text), and room for futher enhancements that will use
|
|
|
|
|
multiple grids. The older revision is available and used by default only for
|
|
|
|
|
backwards compatibility reasons. New UIs are strongly recommended to use
|
|
|
|
|
|ui-linegrid|, as further protocol extensions will require it.
|
2017-10-28 17:49:41 -04:00
|
|
|
|
|
|
|
|
|
Nvim optionally sends screen elements "semantically" as structured events
|
2018-06-27 18:48:17 -04:00
|
|
|
|
instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present
|
2018-04-30 17:01:47 -04:00
|
|
|
|
those elements itself; Nvim will not draw those elements on the grid.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
Future versions of Nvim may add new update kinds and may append new parameters
|
2017-12-27 13:30:23 -05:00
|
|
|
|
to existing update kinds. Clients must be prepared to ignore such extensions,
|
|
|
|
|
for forward-compatibility. |api-contract|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
2018-09-28 07:17:16 -04:00
|
|
|
|
==============================================================================
|
|
|
|
|
UI startup *ui-startup*
|
|
|
|
|
|
|
|
|
|
Nvim defines a standard procedure for how an embedding UI should interact with
|
|
|
|
|
the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag
|
2018-09-28 08:19:37 -04:00
|
|
|
|
but not the |--headless| flag. The started Nvim process will pause before loading
|
|
|
|
|
startup files and reading buffers, and give the UI a chance to invoke requests
|
|
|
|
|
to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the
|
|
|
|
|
startup will continue.
|
2018-09-28 07:17:16 -04:00
|
|
|
|
|
|
|
|
|
A simple UI only need to do a single |nvim_ui_attach()| request and then
|
2018-09-29 07:28:53 -04:00
|
|
|
|
be prepared to handle any UI event. A more featureful UI, which might need
|
2018-09-28 07:17:16 -04:00
|
|
|
|
additional configuration of the nvim process, should use the following startup
|
|
|
|
|
procedure:
|
|
|
|
|
|
|
|
|
|
1. Invoke |nvim_get_api_info()|, if this is needed to setup the client library
|
|
|
|
|
and/or to get the list of supported UI extensions.
|
|
|
|
|
2. At this time, any configuration that should be happen before init.vim
|
|
|
|
|
loading should be done. Buffers and windows are not available at this
|
|
|
|
|
point, but this could be used to set |g:| variables visible to init.vim
|
|
|
|
|
3. If the UI wants to do additional setup after the init.vim file was loaded
|
|
|
|
|
register an autocmd for VimEnter at this point: >
|
|
|
|
|
|
|
|
|
|
nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
|
|
|
|
|
|
|
|
|
|
<4. Now invoke |nvim_ui_attach()|. The UI will need to handle keyboard input
|
|
|
|
|
at this point, as sourcing init.vim and loading buffers might lead to
|
|
|
|
|
blocking prompts.
|
|
|
|
|
5. If step 3 was used, nvim will send a blocking "vimenter" request to the
|
|
|
|
|
UI. Inside this request handler, the UI can safely do any initialization
|
|
|
|
|
before entering normal mode, for instance reading variables set by
|
|
|
|
|
init.vim.
|
|
|
|
|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
==============================================================================
|
|
|
|
|
Global Events *ui-global*
|
|
|
|
|
|
2018-09-28 08:19:37 -04:00
|
|
|
|
The following events will always be available, and describe global state of
|
|
|
|
|
the editor.
|
|
|
|
|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
["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.
|
|
|
|
|
|
2017-10-28 17:49:41 -04:00
|
|
|
|
Each mode property map may contain these keys:
|
|
|
|
|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
KEY DESCRIPTION ~
|
|
|
|
|
`cursor_shape`: "block", "horizontal", "vertical"
|
|
|
|
|
`cell_percentage`: Cell % occupied by the cursor.
|
|
|
|
|
`blinkwait`, `blinkon`, `blinkoff`: See |cursor-blinking|.
|
2018-07-26 15:27:41 -04:00
|
|
|
|
`attr_id`: Cursor attribute id (defined by `hl_attr_define`)
|
|
|
|
|
`attr_id_lm`: Cursor attribute id for when 'langmap' is active.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
`short_name`: Mode code name, see 'guicursor'.
|
|
|
|
|
`name`: Mode descriptive name.
|
|
|
|
|
`mouse_shape`: (To be implemented.)
|
|
|
|
|
|
2017-10-28 17:49:41 -04:00
|
|
|
|
Some keys are missing in some modes.
|
2018-07-26 15:27:41 -04:00
|
|
|
|
|
|
|
|
|
The following keys are deprecated:
|
|
|
|
|
|
|
|
|
|
`hl_id`: Use `attr_id` instead.
|
|
|
|
|
`hl_lm`: Use `attr_id_lm` instead.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
2017-12-12 12:23:19 -05:00
|
|
|
|
["option_set", name, value]
|
2018-06-27 18:48:17 -04:00
|
|
|
|
UI-related option changed, where `name` is one of:
|
2017-12-12 12:23:19 -05:00
|
|
|
|
|
|
|
|
|
'arabicshape'
|
2017-12-27 13:30:23 -05:00
|
|
|
|
'ambiwidth'
|
2017-12-12 12:23:19 -05:00
|
|
|
|
'emoji'
|
|
|
|
|
'guifont'
|
|
|
|
|
'guifontset'
|
|
|
|
|
'guifontwide'
|
2018-01-21 01:31:57 -05:00
|
|
|
|
'linespace'
|
2017-12-12 12:23:19 -05:00
|
|
|
|
'showtabline'
|
|
|
|
|
'termguicolors'
|
2018-06-27 18:48:17 -04:00
|
|
|
|
"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
|
2018-11-04 20:47:22 -05:00
|
|
|
|
sent from Nvim, like for |ui-cmdline|.
|
2017-12-12 12:23:19 -05:00
|
|
|
|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
["mode_change", mode, mode_idx]
|
|
|
|
|
The mode changed. The first parameter `mode` is a string representing
|
|
|
|
|
the current mode. `mode_idx` is an index into the array received in
|
|
|
|
|
the `mode_info_set` event. UIs should change the cursor style
|
|
|
|
|
according to the properties specified in the corresponding item. The
|
|
|
|
|
set of modes reported will change in new versions of Nvim, for
|
|
|
|
|
instance more submodes and temporary states might be represented as
|
|
|
|
|
separate modes.
|
|
|
|
|
|
|
|
|
|
["mouse_on"]
|
|
|
|
|
["mouse_off"]
|
|
|
|
|
Tells the client whether mouse support, as determined by |'mouse'|
|
|
|
|
|
option, is considered to be active in the current mode. This is mostly
|
|
|
|
|
useful for a terminal frontend, or other situations where nvim mouse
|
|
|
|
|
would conflict with other usages of the mouse. It is safe for a client
|
|
|
|
|
to ignore this and always send mouse events.
|
|
|
|
|
|
2018-09-28 07:17:16 -04:00
|
|
|
|
["busy_start"]
|
|
|
|
|
["busy_stop"]
|
2017-10-28 17:49:41 -04:00
|
|
|
|
Nvim started or stopped being busy, and possibly not responsive to
|
|
|
|
|
user input. This could be indicated to the user by hiding the cursor.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["suspend"]
|
2018-09-28 07:17:16 -04:00
|
|
|
|
|: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.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["update_menu"]
|
|
|
|
|
The menu mappings changed.
|
|
|
|
|
|
|
|
|
|
["bell"]
|
|
|
|
|
["visual_bell"]
|
|
|
|
|
Notify the user with an audible or visual bell, respectively.
|
|
|
|
|
|
2018-09-29 07:28:53 -04:00
|
|
|
|
["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.
|
|
|
|
|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
==============================================================================
|
2018-09-28 08:19:37 -04:00
|
|
|
|
Grid Events (line-based) *ui-linegrid*
|
2018-04-30 17:01:47 -04:00
|
|
|
|
|
2018-09-28 08:19:37 -04:00
|
|
|
|
These events are used if `ext_linegrid` option is set (recommended for all new
|
|
|
|
|
UIs). The biggest change compared to previous revision is to use a single
|
|
|
|
|
event `grid_line` to update the contents of a screen line (where the old
|
|
|
|
|
protocol used a combination of cursor, highlight and text events)
|
2018-04-30 17:01:47 -04:00
|
|
|
|
|
|
|
|
|
Most of these events take a `grid` index as first parameter. Grid 1 is the
|
|
|
|
|
global grid used by default for the entire editor screen state. Grids other
|
2018-09-28 08:19:37 -04:00
|
|
|
|
than that will be defined by future extensions. Just activating the
|
|
|
|
|
`ext_linegrid` option by itself will never cause any additional grids to be
|
|
|
|
|
created.
|
2018-04-30 17:01:47 -04:00
|
|
|
|
|
|
|
|
|
Highlight attribute groups are predefined. UIs should maintain a table to map
|
|
|
|
|
numerical highlight `id`:s to the actual attributes.
|
|
|
|
|
|
|
|
|
|
["grid_resize", grid, width, height]
|
|
|
|
|
Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is
|
|
|
|
|
being created with this size.
|
|
|
|
|
|
|
|
|
|
["default_colors_set", rgb_fg, rgb_bg, rgb_sp, cterm_fg, cterm_bg]
|
|
|
|
|
The first three arguments set the default foreground, background and
|
|
|
|
|
special colors respectively. `cterm_fg` and `cterm_bg` specifies the
|
|
|
|
|
default color codes to use in a 256-color terminal.
|
|
|
|
|
|
|
|
|
|
Note: unlike the corresponding events in the first revision, the
|
|
|
|
|
screen is not always cleared after sending this event. The GUI has to
|
|
|
|
|
repaint the screen with changed background color itself.
|
|
|
|
|
|
|
|
|
|
*ui-event-hl_attr_define*
|
|
|
|
|
["hl_attr_define", id, rgb_attr, cterm_attr, info]
|
|
|
|
|
Add a highlight with `id` to the highlight table, with the
|
|
|
|
|
attributes specified by the `rgb_attr` and `cterm_attr` dicts, with the
|
|
|
|
|
following (all optional) keys.
|
|
|
|
|
|
|
|
|
|
`foreground`: foreground color.
|
|
|
|
|
`background`: background color.
|
|
|
|
|
`special`: color to use for underline and undercurl, when present.
|
|
|
|
|
`reverse`: reverse video. Foreground and background colors are
|
|
|
|
|
switched.
|
|
|
|
|
`italic`: italic text.
|
|
|
|
|
`bold`: bold text.
|
|
|
|
|
`underline`: underlined text. The line has `special` color.
|
|
|
|
|
`undercurl`: undercurled text. The curl has `special` color.
|
|
|
|
|
|
|
|
|
|
For absent color keys the default color should be used. Don't store
|
|
|
|
|
the default value in the table, rather a sentinel value, so that
|
|
|
|
|
a changed default color will take effect.
|
|
|
|
|
All boolean keys default to false, and will only be sent when they
|
|
|
|
|
are true.
|
|
|
|
|
|
|
|
|
|
Highlights are always transmitted both for both the rgb format and as
|
|
|
|
|
terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters
|
|
|
|
|
respectively. The |ui-rgb| option has no effect effect anymore.
|
|
|
|
|
Most external UIs will only need to store and use the `rgb_attr`
|
|
|
|
|
attributes.
|
|
|
|
|
|
|
|
|
|
`id` 0 will always be used for the default highlight with colors defined
|
|
|
|
|
by `default_colors_set` and no styles applied.
|
|
|
|
|
|
|
|
|
|
Note: `id`:s can be reused if Nvim's internal highlight table is full.
|
|
|
|
|
In this case, Nvim will always issue redraws of screen cells that are
|
|
|
|
|
affected by redefined `id`:s, so UIs do not need to keep track of this
|
|
|
|
|
themselves.
|
|
|
|
|
|
|
|
|
|
`info` is an empty array per default, and will be used by the
|
|
|
|
|
|ui-hlstate| extension explaned below.
|
|
|
|
|
|
|
|
|
|
*ui-event-grid_line*
|
|
|
|
|
["grid_line", grid, row, col_start, cells]
|
|
|
|
|
Redraw a continous part of a `row` on a `grid`, starting at the column
|
|
|
|
|
`col_start`. `cells` is an array of arrays each with 1 to 3 items:
|
|
|
|
|
`[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in
|
|
|
|
|
a cell, with the highlight `hl_id` defined by a previous `hl_attr_define`
|
|
|
|
|
call. If `hl_id` is not present the most recently seen `hl_id` in
|
|
|
|
|
the same call should be used (it is always sent for the first
|
|
|
|
|
cell in the event). If `repeat` is present, the cell should be
|
|
|
|
|
repeated `repeat` times (including the first time), otherwise just
|
|
|
|
|
once.
|
|
|
|
|
|
|
|
|
|
The right cell of a double-width char will be represented as the empty
|
|
|
|
|
string. Double-width chars never use `repeat`.
|
|
|
|
|
|
|
|
|
|
If the array of cell changes doesn't reach to the end of the line, the
|
|
|
|
|
rest should remain unchanged. A whitespace char, repeated
|
|
|
|
|
enough to cover the remaining line, will be sent when the rest of the
|
|
|
|
|
line should be cleared.
|
|
|
|
|
|
|
|
|
|
["grid_clear", grid]
|
|
|
|
|
Clear a `grid`.
|
|
|
|
|
|
|
|
|
|
["grid_destroy", grid]
|
|
|
|
|
`grid` will not be used anymore and the UI can free any data associated
|
|
|
|
|
with it.
|
|
|
|
|
|
|
|
|
|
["grid_cursor_goto", grid, row, column]
|
|
|
|
|
Makes `grid` the current grid and `row, column` the cursor position on this
|
|
|
|
|
grid. This event will be sent at most once in a `redraw` batch and
|
|
|
|
|
indicates the visible cursor position.
|
|
|
|
|
|
|
|
|
|
["grid_scroll", grid, top, bot, left, right, rows, cols]
|
|
|
|
|
Scroll the text in the a region of `grid`. The diagrams below illustrate
|
|
|
|
|
what will happen, depending on the scroll direction. "=" is used to
|
|
|
|
|
represent the SR(scroll region) boundaries and "-" the moved rectangles.
|
|
|
|
|
Note that dst and src share a common region.
|
|
|
|
|
|
|
|
|
|
If `rows` is bigger than 0, move a rectangle in the SR up, this can
|
|
|
|
|
happen while scrolling down.
|
|
|
|
|
>
|
|
|
|
|
+-------------------------+
|
|
|
|
|
| (clipped above SR) | ^
|
|
|
|
|
|=========================| dst_top |
|
|
|
|
|
| dst (still in SR) | |
|
|
|
|
|
+-------------------------+ src_top |
|
|
|
|
|
| src (moved up) and dst | |
|
|
|
|
|
|-------------------------| dst_bot |
|
|
|
|
|
| src (cleared) | |
|
|
|
|
|
+=========================+ src_bot
|
|
|
|
|
<
|
|
|
|
|
If `rows` 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
|
|
|
|
|
+-------------------------+
|
|
|
|
|
<
|
|
|
|
|
`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.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
2018-09-28 08:19:37 -04:00
|
|
|
|
Legacy Grid Events (cell based) *ui-grid-old*
|
2018-04-30 17:01:47 -04:00
|
|
|
|
|
2018-09-28 08:19:37 -04:00
|
|
|
|
This is an older representation of the screen grid, used if `ext_linegrid`
|
|
|
|
|
option is not set. New UIs should use |ui-linegrid|.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["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.
|
|
|
|
|
|
2018-04-30 17:01:47 -04:00
|
|
|
|
*ui-event-highlight_set*
|
2017-09-10 04:01:18 -04:00
|
|
|
|
["highlight_set", attrs]
|
|
|
|
|
Set the attributes that the next text put on the grid will have.
|
|
|
|
|
`attrs` is a dict with the keys below. Any absent key is reset
|
|
|
|
|
to its default value. Color defaults are set by the `update_fg` etc
|
|
|
|
|
updates. All boolean keys default to false.
|
|
|
|
|
|
|
|
|
|
`foreground`: foreground color.
|
|
|
|
|
`background`: backround color.
|
|
|
|
|
`special`: color to use for underline and undercurl, when present.
|
|
|
|
|
`reverse`: reverse video. Foreground and background colors are
|
|
|
|
|
switched.
|
|
|
|
|
`italic`: italic text.
|
|
|
|
|
`bold`: bold text.
|
|
|
|
|
`underline`: underlined text. The line has `special` color.
|
|
|
|
|
`undercurl`: undercurled text. The curl has `special` color.
|
|
|
|
|
|
|
|
|
|
["put", text]
|
|
|
|
|
The (utf-8 encoded) string `text` is put at the cursor position
|
|
|
|
|
(and the cursor is advanced), with the highlights as set by the
|
|
|
|
|
last `highlight_set` update.
|
|
|
|
|
|
|
|
|
|
["set_scroll_region", top, bot, left, right]
|
|
|
|
|
Define the scroll region used by `scroll` below.
|
2018-04-30 17:01:47 -04:00
|
|
|
|
|
|
|
|
|
Note: ranges are end-inclusive, which is inconsistent with API
|
|
|
|
|
conventions.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["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
|
|
|
|
|
+-------------------------+
|
|
|
|
|
<
|
2018-04-30 17:01:47 -04:00
|
|
|
|
==============================================================================
|
|
|
|
|
Detailed highlight state Extension *ui-hlstate*
|
|
|
|
|
|
|
|
|
|
Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies
|
2018-09-28 08:19:37 -04:00
|
|
|
|
`ext_linegrid`.
|
2018-04-30 17:01:47 -04:00
|
|
|
|
|
|
|
|
|
By default, nvim will only describe grid cells using the final calculated
|
|
|
|
|
higlight attributes, as described by the dict keys in |ui-event-highlight_set|.
|
|
|
|
|
The `ext_hlstate` extension allows to the UI to also receive a semantic
|
|
|
|
|
describtion of the higlights active in a cell. In this mode highlights will be
|
|
|
|
|
predefined in a table, see |ui-event-hl_attr_define| and |ui-event-grid_line|.
|
|
|
|
|
The `info` parameter in `hl_attr_define` will contain a semantic description
|
|
|
|
|
of the highlights. As highlight groups can be combined, this will be an array
|
|
|
|
|
of items, with the item with highest priority last. Each item is a dictionary
|
|
|
|
|
with the following possible keys:
|
|
|
|
|
|
|
|
|
|
`kind`: always present. One of the following values:
|
|
|
|
|
"ui": A builtin ui highlight.
|
|
|
|
|
"syntax": highlight applied to a buffer by a syntax declaration or
|
|
|
|
|
other runtime/plugin functionallity such as
|
2018-08-25 10:38:24 -04:00
|
|
|
|
|nvim_buf_add_highlight()|
|
2018-04-30 17:01:47 -04:00
|
|
|
|
"terminal": highlight from a process running in a |terminal-emulator|.
|
|
|
|
|
Contains no futher semantic information.
|
|
|
|
|
`ui_name`: Name of the builtin highlight. See |highlight-groups| for
|
|
|
|
|
possible values. Only present for "ui".
|
|
|
|
|
`hi_name`: Name of the final |:highlight| group where the used
|
|
|
|
|
attributes are defined.
|
|
|
|
|
`id`: Unique numeric id representing this item.
|
|
|
|
|
|
|
|
|
|
Note: "ui" items will have both `ui_name` and `hi_name` present. These can
|
2018-08-25 10:38:24 -04:00
|
|
|
|
differ, because the builtin group was linked to another group |:hi-link| , or
|
2018-04-30 17:01:47 -04:00
|
|
|
|
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.
|
|
|
|
|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
==============================================================================
|
|
|
|
|
Popupmenu Events *ui-popupmenu*
|
|
|
|
|
|
|
|
|
|
Only sent if `ext_popupmenu` option is set in |ui-options|
|
|
|
|
|
|
|
|
|
|
["popupmenu_show", items, selected, row, col]
|
2017-10-31 05:45:06 -04:00
|
|
|
|
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.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["popupmenu_select", selected]
|
2017-10-31 05:45:06 -04:00
|
|
|
|
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.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["popupmenu_hide"]
|
2017-10-31 05:45:06 -04:00
|
|
|
|
Hide the popupmenu.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
|
|
|
Tabline Events *ui-tabline*
|
|
|
|
|
|
|
|
|
|
Only sent if `ext_tabline` option is set in |ui-options|
|
|
|
|
|
|
|
|
|
|
["tabline_update", curtab, tabs]
|
|
|
|
|
Tabline was updated. UIs should present this data in a custom tabline
|
|
|
|
|
widget.
|
|
|
|
|
curtab: Current Tabpage
|
|
|
|
|
tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...]
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
|
|
|
Cmdline Events *ui-cmdline*
|
|
|
|
|
|
|
|
|
|
Only sent if `ext_cmdline` option is set in |ui-options|
|
|
|
|
|
|
|
|
|
|
["cmdline_show", content, pos, firstc, prompt, indent, level]
|
|
|
|
|
content: List of [attrs, string]
|
|
|
|
|
[[{}, "t"], [attrs, "est"], ...]
|
2017-10-28 17:49:41 -04:00
|
|
|
|
|
2017-10-29 03:04:42 -04:00
|
|
|
|
Triggered when the cmdline is displayed or changed.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
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
|
2017-10-28 17:49:41 -04:00
|
|
|
|
cmdline. The content is divided into chunks with different highlight
|
|
|
|
|
attributes represented as a dict (see |ui-event-highlight_set|).
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
`firstc` and `prompt` are text, that if non-empty should be
|
|
|
|
|
displayed in front of the command line. `firstc` always indicates
|
2017-10-28 17:49:41 -04:00
|
|
|
|
built-in command lines such as `:` (ex command) and `/` `?` (search),
|
2017-09-10 04:01:18 -04:00
|
|
|
|
while `prompt` is an |input()| prompt. `indent` tells how many spaces
|
2017-10-28 17:49:41 -04:00
|
|
|
|
the content should be indented.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
2017-10-28 17:49:41 -04:00
|
|
|
|
The Nvim command line can be invoked recursively, for instance by
|
2017-09-10 04:01:18 -04:00
|
|
|
|
typing `<c-r>=` at the command line prompt. The `level` field is used
|
|
|
|
|
to distinguish different command lines active at the same time. The
|
2017-10-28 17:49:41 -04:00
|
|
|
|
first invoked command line has level 1, the next recursively-invoked
|
2018-08-25 10:38:24 -04:00
|
|
|
|
prompt has level 2. A command line invoked from the |cmdline-window|
|
2017-10-28 17:49:41 -04:00
|
|
|
|
has a higher level than than the edited command line.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["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
|
2017-10-28 17:49:41 -04:00
|
|
|
|
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.
|
|
|
|
|
|
2017-11-03 04:34:31 -04:00
|
|
|
|
Should be hidden at next cmdline_show.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["cmdline_hide"]
|
|
|
|
|
Hide the cmdline.
|
|
|
|
|
|
|
|
|
|
["cmdline_block_show", lines]
|
2017-10-28 17:49:41 -04:00
|
|
|
|
Show a block of context to the current command line. For example if
|
|
|
|
|
the user defines a |:function| interactively: >
|
|
|
|
|
:function Foo()
|
|
|
|
|
: echo "foo"
|
|
|
|
|
:
|
|
|
|
|
<
|
|
|
|
|
`lines` is a list of lines of highlighted chunks, in the same form as
|
|
|
|
|
the "cmdline_show" `contents` parameter.
|
2017-09-10 04:01:18 -04:00
|
|
|
|
|
|
|
|
|
["cmdline_block_append", line]
|
|
|
|
|
Append a line at the end of the currently shown block.
|
|
|
|
|
|
|
|
|
|
["cmdline_block_hide"]
|
|
|
|
|
Hide the block.
|
|
|
|
|
|
2017-02-24 01:12:34 -05:00
|
|
|
|
==============================================================================
|
|
|
|
|
Wildmenu Events *ui-wildmenu*
|
|
|
|
|
|
|
|
|
|
Only sent if `ext_wildmenu` option is set in |ui-options|
|
|
|
|
|
|
|
|
|
|
["wildmenu_show", items]
|
2017-10-31 05:45:06 -04:00
|
|
|
|
Activate the wildmenu (command-line completion). `items` is an array
|
|
|
|
|
with the completion items.
|
2017-02-24 01:12:34 -05:00
|
|
|
|
|
|
|
|
|
["wildmenu_select", selected]
|
2017-10-31 05:45:06 -04:00
|
|
|
|
Select an item in the current wildmenu. `selected` is a zero-based
|
|
|
|
|
index into the array of items from the last wildmenu_show event, or -1
|
|
|
|
|
if no item is selected.
|
2017-02-24 01:12:34 -05:00
|
|
|
|
|
|
|
|
|
["wildmenu_hide"]
|
2017-10-31 05:45:06 -04:00
|
|
|
|
Hide the wildmenu.
|
2017-02-24 01:12:34 -05:00
|
|
|
|
|
2017-09-10 04:01:18 -04:00
|
|
|
|
==============================================================================
|
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|