diff options
| -rw-r--r-- | runtime/doc/ui.txt | 48 |
1 files changed, 24 insertions, 24 deletions
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index ce9a7d9f26..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* @@ -47,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 @@ -62,13 +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 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. +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 @@ -480,29 +480,30 @@ 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. +`ext_linegrid` extension 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. +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 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 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). -The same window can be hiden and redisplayed multiple times. This happens for -instance when switching tabs. +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 @@ -525,7 +526,6 @@ instance when switching tabs. 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* |