diff options
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 18c0ff8a58..30f68ca942 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -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* @@ -238,4 +239,169 @@ 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: |