1
mirror of https://github.com/neovim/neovim.git synced 2024-12-31 17:13:26 -07:00

docs: breakout ui.txt from msgpack_rpc.txt

This commit is contained in:
Björn Linse 2017-09-10 10:01:18 +02:00
parent 445f25998c
commit f640ae0d6e
3 changed files with 285 additions and 256 deletions

View File

@ -48,7 +48,7 @@ version.api_compatible API is backwards-compatible with this level
version.api_prerelease Declares the current API level as unstable >
(version.api_prerelease && fn.since == version.api_level)
functions API function signatures
ui_events UI event signatures |rpc-remote-ui|
ui_events UI event signatures |ui|
{fn}.since API level where function {fn} was introduced
{fn}.deprecated_since API level where function {fn} was deprecated
types Custom handle types defined by Nvim

View File

@ -243,259 +243,4 @@ Even for statically compiled clients it is good practice to avoid hardcoding
the type codes, because a client may be built against one Nvim version but
connect to another with different type codes.
==============================================================================
6. Remote UIs *rpc-remote-ui*
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").
After connecting to Nvim (usually a spawned, embedded instance) use the
|nvim_ui_attach| API method to tell Nvim that your program wants to draw the
Nvim screen on a grid of width × height cells. `options` must be
a dictionary with these (optional) keys:
`rgb` Controls what color format to use.
Set to true (default) to use 24-bit rgb
colors.
Set to false to use terminal color codes (at
most 256 different colors).
`ext_popupmenu` Externalize the popupmenu. |ui-ext-popupmenu|
`ext_tabline` Externalize the tabline. |ui-ext-tabline|
`ext_cmdline` Externalize the cmdline. |ui-ext-cmdline|
Externalized widgets will not be drawn by
Nvim; only high-level data will be published
in new UI event kinds.
Nvim will then send msgpack-rpc notifications, with the method name "redraw"
and a single argument, an array of screen updates (described below). These
should be processed in order. Preferably the user should only be able to see
the screen state after all updates in the same "redraw" event are processed
(not any intermediate state after processing only a part of the array).
Future versions of Nvim may add new update kinds and may append new parameters
to existing update kinds. Clients must be prepared to ignore such extensions
to be forward-compatible. |api-contract|
Screen updates are tuples whose first element is the string name of the update
kind.
["resize", width, height]
The grid is resized to `width` and `height` cells.
["clear"]
Clear the screen.
["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 screen 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.
["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
+-------------------------+
<
["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.
["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.
["busy_on"]
["busy_off"]
Nvim started or stopped being busy, and possibly not responsible to user
input. This could be indicated to the user by hiding the cursor.
["suspend"]
|:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other
client where it makes sense) could suspend itself. Other clients can
safely ignore it.
["bell"]
["visual_bell"]
Notify the user with an audible or visual bell, respectively.
["update_menu"]
The menu mappings changed.
["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|.
`hl_id`: Cursor highlight group.
`hl_lm`: Cursor highlight group if 'langmap' is active.
`short_name`: Mode code name, see 'guicursor'.
`name`: Mode descriptive name.
`mouse_shape`: (To be implemented.)
Some keys are missing in some modes.
["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.
*ui-ext-popupmenu*
["popupmenu_show", items, selected, row, col]
When `popupmenu_external` is set to true, nvim will not draw the
popupmenu on the grid, instead when the popupmenu is to be displayed
this update is sent. `items` is an array of the items to show, the
items are themselves arrays 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, either a
zero-based index into the array of items, or -1 if no item is
selected. `row` and `col` is the anchor position, where the first
character of the completed word will be.
["popupmenu_select", selected]
An item in the currently displayed popupmenu is selected. `selected`
is either a zero-based index into the array of items from the last
`popupmenu_show` event, or -1 if no item is selected.
["popupmenu_hide"]
The popupmenu is hidden.
*ui-ext-tabline*
["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 }, ...]
*ui-ext-cmdline*
["cmdline_show", content, pos, firstc, prompt, indent, level]
content: List of [attrs, string]
[[{}, "t"], [attrs, "est"], ...]
When cmdline_external is set to true, nvim will not draw the cmdline
on the grid, instead nvim will send ui events of the cmdline content
and cursor position to the remote ui. 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. This event will be triggered when
you type 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. `indent` tells how many spaces
the content should be indented
The command line in nvim 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 will always have level 1, and the next
recursively invoked prompt will have level 2. Also, a command line
invoked while in command line window will have a higher level than
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, like right after Ctrl-V.
if shift is true the text after the cursor should be shifted,
otherwise it should overshadow the char at the cursor.
Should be hidden at next cmdline_char
["cmdline_hide"]
Hide the cmdline.
["cmdline_block_show", lines]
Show a block of context to the current command line. This occurs for
instance if a function is interactively defined at the command line.
`lines` is a list of lines where each line is represented as a list of
highlighted chunks, just like `contents` of |ui-event-cmdline_show|.
["cmdline_block_append", line]
Append a line at the end of the currently shown block.
["cmdline_block_hide"]
Hide the block.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

284
runtime/doc/ui.txt Normal file
View File

@ -0,0 +1,284 @@
*ui.txt* Nvim
NVIM REFERENCE MANUAL by Thiago de Arruda
UI protocol *ui*
Type <M-]> to see the table of contents.
==============================================================================
Introduction *ui-intro*
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").
*ui-options*
After connecting to Nvim (usually a spawned, embedded instance) use the
|nvim_ui_attach| API method to tell Nvim that your program wants to draw the
Nvim screen grid with a size of width × height cells. `options` must be
a dictionary with these (optional) keys:
`rgb` Controls what color format to use.
Set to true (default) to use 24-bit rgb
colors.
Set to false to use terminal color codes (at
most 256 different colors).
`ext_popupmenu` Externalize the popupmenu. |ui-popupmenu|
`ext_tabline` Externalize the tabline. |ui-tabline|
`ext_cmdline` Externalize the cmdline. |ui-cmdline|
Nvim will then send msgpack-rpc notifications, with the method name "redraw"
and a single argument, an array of screen update events.
Update events are tuples whose first element is the string name of the update
kind. The rest are parameters for each update, described in the sections below.
These should be processed in order. Preferably the user should only be able to
see the screen state after all update events in the same "redraw" event are
processed (not any intermediate state after processing only a part of the
array).
Section 2 and 3 describes grid and mode events that are send unconditionally,
and suffice to implement a terminal-like interface. Nvim also allows a number
of screen elements to be sent as descriptive events for the GUI to draw
itself, rather than Nvim drawing itself on the grid. This is controlled by the
`ext_` options.
Future versions of Nvim may add new update kinds and may append new parameters
to existing update kinds. Clients must be prepared to ignore such extensions
to be forward-compatible. |api-contract|
==============================================================================
Global Events *ui-global*
["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|.
`hl_id`: Cursor highlight group.
`hl_lm`: Cursor highlight group if 'langmap' is active.
`short_name`: Mode code name, see 'guicursor'.
`name`: Mode descriptive name.
`mouse_shape`: (To be implemented.)
Some keys are missing in some modes.
["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.
["busy_on"]
["busy_off"]
Nvim started or stopped being busy, and possibly not responsible to user
input. This could be indicated to the user by hiding the cursor.
["suspend"]
|:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other
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.
==============================================================================
Grid Events *ui-grid*
["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`: 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.
["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
+-------------------------+
<
==============================================================================
Popupmenu Events *ui-popupmenu*
Only sent if `ext_popupmenu` option is set in |ui-options|
["popupmenu_show", items, selected, row, col]
`items` is an array of the items to show, the
items are themselves arrays 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, either a
zero-based index into the array of items, or -1 if no item is
selected. `row` and `col` is the anchor position, where the first
character of the completed word will be.
["popupmenu_select", selected]
An item in the currently displayed popupmenu is selected. `selected`
is either a zero-based index into the array of items from the last
`popupmenu_show` event, or -1 if no item is selected.
["popupmenu_hide"]
The popupmenu is hidden.
==============================================================================
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"], ...]
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. This event will be triggered when you type 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. `indent` tells how many spaces
the content should be indented
The command line in nvim 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 will always have level 1, and the next
recursively invoked prompt will have level 2. Also, a command line
invoked while in command line window will have a higher level than
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, like right after Ctrl-V.
if shift is true the text after the cursor should be shifted,
otherwise it should overshadow the char at the cursor.
Should be hidden at next cmdline_char
["cmdline_hide"]
Hide the cmdline.
["cmdline_block_show", lines]
Show a block of context to the current command line. This occurs for
instance if a function is interactively defined at the command line.
`lines` is a list of lines where each line is represented as a list of
highlighted chunks, just like `contents` of |ui-event-cmdline_show|.
["cmdline_block_append", line]
Append a line at the end of the currently shown block.
["cmdline_block_hide"]
Hide the block.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl: