From 47c053cc39c9b3aa78eb4f64ec98c574506729ae Mon Sep 17 00:00:00 2001 From: Utkarsh Maheshwari Date: Thu, 28 Jun 2018 15:35:19 +0530 Subject: [PATCH] multigrid: Add multigrid documentation --- runtime/doc/ui.txt | 58 +++++++++++++++++++++++++++++++++++++++++++--- src/nvim/api/ui.c | 11 +++++++-- 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