mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-12-16 03:15:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

api/ui: add documentation for remote ui redraw events

Browse Source
This commit is contained in:
Björn Linse
2016-08-15 14:02:43 +02:00
parent c41bacc67c
commit 8d6e3f2b88
1 changed files with 166 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
runtime/doc/msgpack_rpc.txt
View File

@@ -11,6 +11,7 @@ RPC API for Nvim *RPC* *rpc* *msgpack-rpc*
3. Connecting |rpc-connecting|
4. Clients |rpc-api-client|
5. Types |rpc-types|
6. Remote UIs |rpc-remote-ui|
==============================================================================
1. Introduction *rpc-intro*
@@ -237,5 +238,170 @@ 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*
Nvim allows Graphical user interfaces to be implemented by separate processes
communicating with Nvim over the RPC API. Currently the ui model conists of a
terminal-like grid with one single, monospace font size, with a few elements
that could be drawn separately from the grid (for the momemnt only the popup
menu)
After connecting to a nvim instance (typically a spawned, embedded instance)
use the |nvim_ui_attach|(width, height, options) API method to tell nvim that your
program wants to draw the nvim screen on a grid with "width" times
"height" cells. "options" should be a dictionary with the following (all
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).
`popupmenu_external`: Instead of drawing the completion popupmenu on
the grid, Nvim will send higher-level events to
the ui and let it draw the popupmenu.
Defaults to false.
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 are processed (not any intermediate
state after processing only a part of the array).
Screen updates are arrays. The first element a string describing the kind
of update.
["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.
["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_change", mode]
The mode changed. Currently sent when "insert", "replace" and "normal"
modes are entered. A client could for instance change the cursor shape.
["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.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl: