kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-29 14:41:06 -07:00
Code Issues Packages Projects Releases Wiki Activity

multigrid: Add multigrid documentation

Browse Source
This commit is contained in:
Utkarsh Maheshwari 2018-06-28 15:35:19 +05:30 committed by Björn Linse
parent db14d78e4f
commit 47c053cc39
2 changed files with 64 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
runtime/doc/ui.txt
View File

@ -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

11
src/nvim/api/ui.c
View File

@ -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