diff options
Diffstat (limited to 'runtime/doc/msgpack_rpc.txt')
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 53 |
1 files changed, 29 insertions, 24 deletions
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 77cbc2f3d8..856476c6ae 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -6,12 +6,7 @@ RPC API for Nvim *RPC* *rpc* *msgpack-rpc* -1. Introduction |rpc-intro| -2. API mapping |rpc-api| -3. Connecting |rpc-connecting| -4. Clients |rpc-api-client| -5. Types |rpc-types| -6. Remote UIs |rpc-remote-ui| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *rpc-intro* @@ -33,7 +28,7 @@ programs can: The RPC API is like a more powerful version of Vim's `clientserver` feature. ============================================================================== - 2. API mapping *rpc-api* +2. API mapping *rpc-api* The Nvim C |API| is automatically exposed to the RPC API by the build system, which parses headers at src/nvim/api/*. A dispatch function is generated which @@ -197,7 +192,7 @@ prefix is stripped off. 5. Types *rpc-types* The Nvim C API uses custom types for all functions. |api-types| -For the purpose of mapping to msgpack, the types can be split into two groups: +At the RPC layer, the types can be split into two groups: - Basic types that map natively to msgpack (and probably have a default representation in msgpack-supported programming languages) @@ -219,15 +214,16 @@ Special types (msgpack EXT) ~ Window -> enum value kObjectTypeWindow Tabpage -> enum value kObjectTypeTabpage -An API method expecting one of these types may be passed an integer instead, -although they are not interchangeable. For example, a Buffer may be passed as -an integer, but not a Window or Tabpage. +API functions expecting one of the special EXT types may be passed an integer +instead, but not another EXT type. E.g. Buffer may be passed as an integer but +not as a Window or Tabpage. The EXT object data is the object id encoded as +a msgpack integer: For buffers this is the |bufnr()| and for windows the +|window-ID|. For tabpages the id is an internal handle, not the tabpage +number. + +To determine the type codes of the special EXT types, inspect the `types` key +of the |api-metadata| at runtime. Example JSON representation: > -The most reliable way of determining the type codes for the special Nvim types -is to inspect the `types` key of metadata dictionary returned by the -`nvim_get_api_info` method at runtime. Here's a sample JSON representation of -the `types` object: -> "types": { "Buffer": { "id": 0, @@ -242,7 +238,7 @@ the `types` object: "prefix": "nvim_tabpage_" } } -< + 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. @@ -251,9 +247,9 @@ 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. Currently the UI model consists of a terminal-like grid with one -single, monospace font size. Some elements (UI "widgets") can be drawn -separately from the grid. +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 @@ -264,10 +260,11 @@ a dictionary with these (optional) keys: 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. + `ext_popupmenu` Externalize the popupmenu. |ui-ext-popupmenu| + `ext_tabline` Externalize the tabline. |ui-ext-tabline| + 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 @@ -417,6 +414,7 @@ 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 @@ -436,5 +434,12 @@ states might be represented as separate modes. ["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 }, ...] + ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: |