Merge #6539 'More cursor shape modes'

1 files changed, 35 insertions, 10 deletions

diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 3f3c41f566..77cbc2f3d8 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -270,13 +270,17 @@ a dictionary with these (optional) keys:
 				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).
+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).
 
-Screen updates are arrays. The first element a string describing the kind
-of update.
+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.
@@ -387,10 +391,31 @@ of update.
 ["update_menu"]
 	The menu mappings changed.
 
-["mode_change", mode]
-	The mode changed. Currently sent when "insert", "replace", "cmdline" and
-	"normal" modes are entered. A client could for instance change the cursor
-	shape.
+["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.
 
 ["popupmenu_show", items, selected, row, col]
 	When `popupmenu_external` is set to true, nvim will not draw the