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