multigrid: Add multigrid documentation

2 files changed, 64 insertions, 5 deletions

diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index c021f236c8..ce9a7d9f26 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -32,6 +32,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|
@@ -66,6 +67,9 @@ 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.
 
+The new grid-based events |ui-multigrid| enables the newer revision |ui-linegrid|
+implicitly. The UIs need not enable them and must be prepared to handle them.
+
 Nvim optionally sends screen elements "semantically" as structured events
 instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present
 those elements itself; Nvim will not draw those elements on the grid.
@@ -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.
@@ -475,19 +480,66 @@ because 'winhighlight' was used. UI items will be transmitted, even if the
 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` implicitly.
+
+The multigrid enables the UIs to manipulate window grids individually. The UIs
+receive a grid update for each new window. The UIs can set a grid size
+independent of how a window is positioned in the UI. This enables the UIs to
+set a different font size for each window if the UI so desires. The UIs can
+also utilize this feature to reserve space for scrollbars consitent with their
+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 a new split is created. To delegate
+the handling of grid size back to nvim, the UIs can request the size to be set
+to (0, 0).
+
+The same window can be hiden and redisplayed multiple times. This happens 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
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index 48a4708dbf..c374bede99 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -245,8 +245,15 @@ static void ui_set_option(UI *ui, bool init, String name, Object value,
                 name.data);
 }
 
-/// Sets the inner "width" and "height" of the window grid identified by
-/// "grid" handle. If the grid does not exist, set error.
+/// Tell nvim to resize a grid. Nvim sends grid_resize event with the
+/// requested grid size is within size limits and with maximum allowed size
+/// otherwise.
+///
+/// On invalid grid handle, fails with error.
+///
+/// @param grid    The handle of the grid to be changed.
+/// @param width   The new requested width.
+/// @param height  The new requested height.
 void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width,
                              Integer height, Error *error)
   FUNC_API_SINCE(5) FUNC_API_REMOTE_ONLY