Merge pull request #8455 from UtkarshMe/grid-split

implement ext_multigrid: draw each window on a separate resizable grid.

1 files changed, 63 insertions, 11 deletions

diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index c021f236c8..9acd8b2c5a 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -12,9 +12,10 @@ Nvim UI protocol							  *ui*
 UI Events							    *ui-events*
 
 GUIs can be implemented as external processes communicating with Nvim over the
-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").
+RPC API. The default UI model consists of a terminal-like grid with a single,
+monospace font size. The UI can opt-in to have windows drawn on separate
+grids, as well as to have some elements (UI "widgets") be drawn by the UI
+itself rather than by nvim ("externalized").
 
 
 								  *ui-options*
@@ -32,6 +33,7 @@ a dictionary with these (optional) keys:
 	`ext_cmdline`		Externalize the cmdline. |ui-cmdline|
 	`ext_wildmenu`		Externalize the wildmenu. |ui-wildmenu|
 	`ext_linegrid`		Use new revision of the grid events. |ui-linegrid|
+	`ext_multigrid`		Use per-window grid based events. |ui-multigrid|
 	`ext_hlstate`		Use detailed highlight state. |ui-hlstate|
 
 Specifying a non-existent option is an error. UIs can check the |api-metadata|
@@ -46,7 +48,7 @@ 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 "grid_line", because each "grid_line" event puts
-contents in one screen line, but clients must be prepared for multiple argument
+contents in one grid 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
@@ -61,10 +63,12 @@ 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-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.
+highlighted text), and allows extensions that 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 require it. The |ui-multigrid| extension
+enables |ui-linegrid| implicitly.
 
 Nvim optionally sends screen elements "semantically" as structured events
 instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present
@@ -220,7 +224,8 @@ 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_linegrid` option by itself will never cause any additional grids to be
-created.
+created.  To enable per-window grids, `ext_multigrid` option should be set (see
+|ui-multigrid|).
 
 Highlight attribute groups are predefined. UIs should maintain a table to map
 numerical highlight `id`:s to the actual attributes.
@@ -476,18 +481,65 @@ highlight group is cleared, so `ui_name` can always be used to reliably identify
 screen elements, even if no attributes have been applied.
 
 ==============================================================================
+Multigrid Events 	  					 *ui-multigrid*
+
+Only sent if `ext_multigrid` option is set in |ui-options|. Enables the
+`ext_linegrid` extension implicitly.
+
+The multigrid extension gives the UIs more control over how windows are
+displayed. The UIs receive updates on a separate grid for each window. The UIs
+can set the grid size independently of how much space the window occupies on
+the global layout. This enables the UIs to set a different font size for each
+window if the UI so desires. The UI can also reserve space around the border
+of the window for its own elements, for instance scrollbars from the UI
+toolkit.
+
+By default, the grid size is handled by nvim and set to the outer grid size
+(i.e. the size of the window frame in nvim) whenever the split is created.
+Once a UI sets a grid size, nvim does not handle the size for that grid and
+the UI must change the grid size whenever the outer size is changed. To
+delegate the handling of grid size back to nvim, the UIs should request the
+size (0, 0).
+
+A window can be hidden and redisplayed without its grid being deallocated.
+This can happen multiple times for the same window, for instance when switching
+tabs.
+
+["win_pos", grid, win, start_row, start_col, width, height]
+	Set the position and size of the grid in nvim (i.e. the outer grid
+	size). If the window was previously hidden, it should now be shown
+	again.
+
+["win_hide", grid]
+	Stop displaying the window.
+
+["win_scroll_over_start"]
+	Hint that following `grid_scroll` on the default grid should
+	scroll over windows. This is a temporary workaround to allow
+	UIs to use the builtin message drawing. Later on, messages will be
+	drawn on a dedicated grid.
+
+["win_scroll_over_reset"]
+	Hint that scrolled over windows should be redrawn again, and not be
+	overdrawn by default grid scrolling anymore.
+
+See |ui-linegrid| for grid events.
+See |nvim_ui_try_resize_grid| in |api-ui| to request changing the grid size.
+
+==============================================================================
 Popupmenu Events						 *ui-popupmenu*
 
 Only sent if `ext_popupmenu` option is set in |ui-options|
 
-["popupmenu_show", items, selected, row, col]
+["popupmenu_show", items, selected, row, col, grid]
 	Show |popupmenu-completion|. `items` is an array of completion items
 	to show; each item is an array 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, a zero-based
 	index into the array of items (-1 if no item is selected). `row` and
 	`col` give the anchor position, where the first character of the
-	completed word will be.
+	completed word will be. When |ui-multigrid| is used, `grid` is the
+	grid for the anchor position.
 
 ["popupmenu_select", selected]
 	Select an item in the current popupmenu. `selected` is a zero-based