Merge pull request #9064 from bfredl/uidoc

UI: rename ext_newgrid to ext_linegrid and add --embed UI startup recommendations

2 files changed, 83 insertions, 32 deletions

diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index dd9f9ad0f3..34c4db4047 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -358,6 +358,8 @@ argument.
 		instance a `nvim_get_api_info` call so that UI features can be
 		safely detected by the UI before attaching.
 
+		See |ui-startup| for more information about UI startup.
+
 		To embed nvim without using the UI protocol, `--headless` should
 		be supplied together with `--embed`. Then initialization is
 		performed without waiting for an UI. This is also equivalent
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 42ce7a5edf..a0f1b0770e 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -16,10 +16,12 @@ 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
+The |nvim_ui_attach()| API method is used to tell Nvim that your program wants to
+draw the Nvim screen grid with a size of width × height cells. This is typically
+done by an embedder, see |ui-startup| below for details, but an UI can also
+connect to a running nvim instance and invoke this method. `options` must be
 a dictionary with these (optional) keys:
 	`rgb`			Decides the color format. *ui-rgb*
 				Set true (default) for 24-bit RGB colors.
@@ -29,7 +31,7 @@ a dictionary with these (optional) keys:
 	`ext_tabline`		Externalize the tabline. |ui-tabline|
 	`ext_cmdline`		Externalize the cmdline. |ui-cmdline|
 	`ext_wildmenu`		Externalize the wildmenu. |ui-wildmenu|
-	`ext_newgrid`		Use new revision of the grid events. |ui-newgrid|
+	`ext_linegrid`		Use new revision of the grid events. |ui-linegrid|
 	`ext_hlstate`		Use detailed highlight state. |ui-hlstate|
 
 Specifying a non-existent option is an error. UIs can check the |api-metadata|
@@ -43,22 +45,26 @@ Nvim sends msgpack-rpc notifications to all attached UIs, with method name
 Each update event is itself an array whose first element is the event name and
 remaining elements are event-parameter tuples. This allows multiple events of
 the same kind to be sent in a row without the event name being repeated. This
-batching is mostly used for "put", because each "put" event puts contents in
-one screen cell, but clients must be prepared for multiple argument sets being
-batched for all event kinds.
-
-Events must be handled in-order. The user should only see the updated screen
-state after all events in the same "redraw" batch are processed (not any
-intermediate state after processing only part of the array).
+batching is mostly used for "grid_line", because each "grid_line" event puts
+contents in one screen line, but clients must be prepared for multiple argument
+sets being batched for all event kinds.
+
+Events must be handled in-order. A "flush" event is sent when nvim is done
+redrawing the entire screen (so that all windows have a consistent view of
+buffer state, options etc). Clients should be prepared that several "redraw"
+batches are sent before the entire screen has been redrawn, and only the last
+batch will end in "flush". The user should only see the final state when
+"flush" is sent, and not any intermediate state after processing only part of
+the batch array, nor after a batch not ending with "flush".
 
 By default, Nvim sends |ui-global| and |ui-grid-old| events; these suffice to
 implement a terminal-like interface. However there are two revisions of the
-grid part of the protocol. The newer revision |ui-newgrid|, enabled by
-`ext_newgrid` option, has some improvements, such as a more efficient
-representation of highlighted text, simplified events and room for futher
-enhancements that will use multiple grids. The older revision is available and
-used by default only for backwards compatibility reasons. New UIs are strongly
-recommended to use |ui-newgrid|, as further protocol extensions will require it.
+grid part of the protocol. The newer revision |ui-linegrid|, enabled by
+`ext_linegrid` option, has a more effecient representation of text (especially
+highlighted text), and room for futher enhancements that will use
+multiple grids. The older revision is available and used by default only for
+backwards compatibility reasons. New UIs are strongly recommended to use
+|ui-linegrid|, as further protocol extensions will require it.
 
 Nvim optionally sends screen elements "semantically" as structured events
 instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present
@@ -69,8 +75,44 @@ to existing update kinds. Clients must be prepared to ignore such extensions,
 for forward-compatibility. |api-contract|
 
 ==============================================================================
+UI startup							   *ui-startup*
+
+Nvim defines a standard procedure for how an embedding UI should interact with
+the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag
+but not the |--headless| flag. The started Nvim process will pause before loading
+startup files and reading buffers, and give the UI a chance to invoke requests
+to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the
+startup will continue.
+
+A simple UI only need to do a single |nvim_ui_attach()| request and then
+be prepared to handle any UI event. A more featureful UI, which might need
+additional configuration of the nvim process, should use the following startup
+procedure:
+
+1. Invoke |nvim_get_api_info()|, if this is needed to setup the client library
+   and/or to get the list of supported UI extensions.
+2. At this time, any configuration that should be happen before init.vim
+   loading should be done. Buffers and windows are not available at this
+   point, but this could be used to set |g:| variables visible to init.vim
+3. If the UI wants to do additional setup after the init.vim file was loaded
+   register an autocmd for VimEnter at this point: >
+
+    nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
+
+<4.  Now invoke |nvim_ui_attach()|. The UI will need to handle keyboard input
+    at this point, as sourcing init.vim and loading buffers might lead to
+    blocking prompts.
+5.  If step 3 was used, nvim will send a blocking "vimenter" request to the
+    UI. Inside this request handler, the UI can safely do any initialization
+    before entering normal mode, for instance reading variables set by
+    init.vim.
+
+==============================================================================
 Global Events							    *ui-global*
 
+The following events will always be available, and describe global state of
+the editor.
+
 ["set_title", title]
 ["set_icon", icon]
 	Set the window title, and icon (minimized) window title, respectively.
@@ -144,15 +186,15 @@ Global Events							    *ui-global*
 	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"]
+["busy_start"]
+["busy_stop"]
 	Nvim started or stopped being busy, and possibly not responsive 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.
+	|:suspend| command or |CTRL-Z| mapping is used. A terminal client (or
+	another client where it makes sense) could suspend itself.  Other
+	clients can safely ignore it.
 
 ["update_menu"]
 	The menu mappings changed.
@@ -161,16 +203,24 @@ Global Events							    *ui-global*
 ["visual_bell"]
 	Notify the user with an audible or visual bell, respectively.
 
+["flush"]
+	Nvim is done redrawing the screen. For an implementation that renders
+	to an internal buffer, this is the time to display the redrawn parts
+	to the user.
+
 ==============================================================================
-Grid Events (new revision)					  *ui-newgrid*
+Grid Events (line-based)					  *ui-linegrid*
 
-These events are used if `ext_newgrid` option is set (recommended for all new
-UIs).
+These events are used if `ext_linegrid` option is set (recommended for all new
+UIs). The biggest change compared to previous revision is to use a single
+event `grid_line` to update the contents of a screen line (where the old
+protocol used a combination of cursor, highlight and text events)
 
 Most of these events take a `grid` index as first parameter.  Grid 1 is the
 global grid used by default for the entire editor screen state. Grids other
-than that will be defined by future extensions. Just activating the `ext_newgrid`
-option by itself will never cause any additional grids to be created.
+than that will be defined by future extensions. Just activating the
+`ext_linegrid` option by itself will never cause any additional grids to be
+created.
 
 Highlight attribute groups are predefined. UIs should maintain a table to map
 numerical highlight `id`:s to the actual attributes.
@@ -299,10 +349,10 @@ numerical highlight `id`:s to the actual attributes.
 	from `set_scroll_region` which was end-inclusive.
 
 ==============================================================================
-Grid Events (first revision)					   *ui-grid-old*
+Legacy Grid Events (cell based)					   *ui-grid-old*
 
-This is an older representation of the screen grid, used if `ext_newgrid`
-option is not set.
+This is an older representation of the screen grid, used if `ext_linegrid`
+option is not set. New UIs should use |ui-linegrid|.
 
 ["resize", width, height]
 	The grid is resized to `width` and `height` cells.
@@ -389,9 +439,8 @@ option is not set.
 ==============================================================================
 Detailed highlight state Extension 				  *ui-hlstate*
 
-
 Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies
-`ext_newgrid`.
+`ext_linegrid`.
 
 By default, nvim will only describe grid cells using the final calculated
 higlight attributes, as described by the dict keys in |ui-event-highlight_set|.