ui: rename ext_newgrid to ext_linegrid

runtime/doc/ui.txt

@@ -31,7 +31,7 @@ a dictionary with these (optional) keys:
 	`ext_tabline`		Externalize the tabline. |ui-tabline|
 	`ext_cmdline`		Externalize the cmdline. |ui-cmdline|
 	`ext_wildmenu`		Externalize the wildmenu. |ui-wildmenu|
-	`ext_newgrid`		Use new revision of the grid events. |ui-newgrid|
+	`ext_linegrid`		Use new revision of the grid events. |ui-linegrid|
 	`ext_hlstate`		Use detailed highlight state. |ui-hlstate|
 
 Specifying a non-existent option is an error. UIs can check the |api-metadata|
@@ -55,12 +55,12 @@ intermediate state after processing only part of the array).
 
 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-newgrid|, enabled by
+grid part of the protocol. The newer revision |ui-linegrid|, enabled by
-`ext_newgrid` option, has some improvements, such as a more efficient
+`ext_linegrid` option, has a more effecient representation of text (especially
-representation of highlighted text, simplified events and room for futher
+highlighted text), and room for futher enhancements that will use
-enhancements that will use multiple grids. The older revision is available and
+multiple grids. The older revision is available and used by default only for
-used by default only for backwards compatibility reasons. New UIs are strongly
+backwards compatibility reasons. New UIs are strongly recommended to use
-recommended to use |ui-newgrid|, as further protocol extensions will require it.
+|ui-linegrid|, as further protocol extensions will require it.
 
 Nvim optionally sends screen elements "semantically" as structured events
 instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present
@@ -75,10 +75,10 @@ UI startup							   *ui-startup*
 
 Nvim defines a standard procedure for how an embedding UI should interact with
 the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag
-but not the |--headless| flag. Nvim will now pause before loading startup
+but not the |--headless| flag. The started Nvim process will pause before loading
-files and reading buffers, and give the UI a chance to invoke requests to do
+startup files and reading buffers, and give the UI a chance to invoke requests
-early initialization. As soon as the UI invokes |nvim_ui_attach()|, the startup
+to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the
-will continue.
+startup will continue.
 
 A simple UI only need to do a single |nvim_ui_attach()| request and then
 be prepared to handle any UI event. A more featureful UI, which might do
@@ -106,6 +106,9 @@ procedure:
 ==============================================================================
 Global Events							    *ui-global*
 
+The following events will always be available, and describe global state of
+the editor.
+
 ["set_title", title]
 ["set_icon", icon]
 	Set the window title, and icon (minimized) window title, respectively.
@@ -197,15 +200,18 @@ Global Events							    *ui-global*
 	Notify the user with an audible or visual bell, respectively.
 
 ==============================================================================
-Grid Events (new revision)					  *ui-newgrid*
+Grid Events (line-based)					  *ui-linegrid*
 
-These events are used if `ext_newgrid` option is set (recommended for all new
+These events are used if `ext_linegrid` option is set (recommended for all new
-UIs).
+UIs). The biggest change compared to previous revision is to use a single
+event `grid_line` to update the contents of a screen line (where the old
+protocol used a combination of cursor, highlight and text events)
 
 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_newgrid`
+than that will be defined by future extensions. Just activating the
-option by itself will never cause any additional grids to be created.
+`ext_linegrid` option by itself will never cause any additional grids to be
+created.
 
 Highlight attribute groups are predefined. UIs should maintain a table to map
 numerical highlight `id`:s to the actual attributes.
@@ -334,10 +340,10 @@ numerical highlight `id`:s to the actual attributes.
 	from `set_scroll_region` which was end-inclusive.
 
 ==============================================================================
-Grid Events (first revision)					   *ui-grid-old*
+Legacy Grid Events (cell based)					   *ui-grid-old*
 
-This is an older representation of the screen grid, used if `ext_newgrid`
+This is an older representation of the screen grid, used if `ext_linegrid`
-option is not set.
+option is not set. New UIs should use |ui-linegrid|.
 
 ["resize", width, height]
 	The grid is resized to `width` and `height` cells.
@@ -424,9 +430,8 @@ option is not set.
 ==============================================================================
 Detailed highlight state Extension 				  *ui-hlstate*
 
-
 Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies
-`ext_newgrid`.
+`ext_linegrid`.
 
 By default, nvim will only describe grid cells using the final calculated
 higlight attributes, as described by the dict keys in |ui-event-highlight_set|.

src/nvim/api/ui.c

@@ -127,7 +127,7 @@ void nvim_ui_attach(uint64_t channel_id, Integer width, Integer height,
   }
 
   if (ui->ui_ext[kUIHlState]) {
-    ui->ui_ext[kUINewgrid] = true;
+    ui->ui_ext[kUILinegrid] = true;
   }
 
   UIData *data = xmalloc(sizeof(UIData));
@@ -227,11 +227,11 @@ static void ui_set_option(UI *ui, bool init, String name, Object value,
         return;
       }
       bool boolval = value.data.boolean;
-      if (!init && i == kUINewgrid && boolval != ui->ui_ext[i]) {
+      if (!init && i == kUILinegrid && boolval != ui->ui_ext[i]) {
         // There shouldn't be a reason for an UI to do this ever
         // so explicitly don't support this.
         api_set_error(error, kErrorTypeValidation,
-                      "ext_newgrid option cannot be changed");
+                      "ext_linegrid option cannot be changed");
       }
       ui->ui_ext[i] = boolval;
       if (!init) {
@@ -271,10 +271,10 @@ static void push_call(UI *ui, const char *name, Array args)
 static void remote_ui_grid_clear(UI *ui, Integer grid)
 {
   Array args = ARRAY_DICT_INIT;
-  if (ui->ui_ext[kUINewgrid]) {
+  if (ui->ui_ext[kUILinegrid]) {
     ADD(args, INTEGER_OBJ(grid));
   }
-  const char *name = ui->ui_ext[kUINewgrid] ? "grid_clear" : "clear";
+  const char *name = ui->ui_ext[kUILinegrid] ? "grid_clear" : "clear";
   push_call(ui, name, args);
 }
 
@@ -282,12 +282,12 @@ static void remote_ui_grid_resize(UI *ui, Integer grid,
                                   Integer width, Integer height)
 {
   Array args = ARRAY_DICT_INIT;
-  if (ui->ui_ext[kUINewgrid]) {
+  if (ui->ui_ext[kUILinegrid]) {
     ADD(args, INTEGER_OBJ(grid));
   }
   ADD(args, INTEGER_OBJ(width));
   ADD(args, INTEGER_OBJ(height));
-  const char *name = ui->ui_ext[kUINewgrid] ? "grid_resize" : "resize";
+  const char *name = ui->ui_ext[kUILinegrid] ? "grid_resize" : "resize";
   push_call(ui, name, args);
 }
 
@@ -295,7 +295,7 @@ static void remote_ui_grid_scroll(UI *ui, Integer grid, Integer top,
                                   Integer bot, Integer left, Integer right,
                                   Integer rows, Integer cols)
 {
-  if (ui->ui_ext[kUINewgrid]) {
+  if (ui->ui_ext[kUILinegrid]) {
     Array args = ARRAY_DICT_INIT;
     ADD(args, INTEGER_OBJ(grid));
     ADD(args, INTEGER_OBJ(top));
@@ -341,7 +341,7 @@ static void remote_ui_default_colors_set(UI *ui, Integer rgb_fg,
   push_call(ui, "default_colors_set", args);
 
   // Deprecated
-  if (!ui->ui_ext[kUINewgrid]) {
+  if (!ui->ui_ext[kUILinegrid]) {
     args = (Array)ARRAY_DICT_INIT;
     ADD(args, INTEGER_OBJ(ui->rgb ? rgb_fg : cterm_fg - 1));
     push_call(ui, "update_fg", args);
@@ -359,7 +359,7 @@ static void remote_ui_default_colors_set(UI *ui, Integer rgb_fg,
 static void remote_ui_hl_attr_define(UI *ui, Integer id, HlAttrs rgb_attrs,
                                      HlAttrs cterm_attrs, Array info)
 {
-  if (!ui->ui_ext[kUINewgrid]) {
+  if (!ui->ui_ext[kUILinegrid]) {
     return;
   }
   Array args = ARRAY_DICT_INIT;
@@ -397,7 +397,7 @@ static void remote_ui_highlight_set(UI *ui, int id)
 static void remote_ui_grid_cursor_goto(UI *ui, Integer grid, Integer row,
                                        Integer col)
 {
-  if (ui->ui_ext[kUINewgrid]) {
+  if (ui->ui_ext[kUILinegrid]) {
     Array args = ARRAY_DICT_INIT;
     ADD(args, INTEGER_OBJ(grid));
     ADD(args, INTEGER_OBJ(row));
@@ -442,7 +442,7 @@ static void remote_ui_raw_line(UI *ui, Integer grid, Integer row,
                                const sattr_T *attrs)
 {
   UIData *data = ui->data;
-  if (ui->ui_ext[kUINewgrid]) {
+  if (ui->ui_ext[kUILinegrid]) {
     Array args = ARRAY_DICT_INIT;
     ADD(args, INTEGER_OBJ(grid));
     ADD(args, INTEGER_OBJ(row));
@@ -508,7 +508,7 @@ static void remote_ui_flush(UI *ui)
 {
   UIData *data = ui->data;
   if (data->buffer.size > 0) {
-    if (!ui->ui_ext[kUINewgrid]) {
+    if (!ui->ui_ext[kUILinegrid]) {
       remote_ui_cursor_goto(ui, data->cursor_row, data->cursor_col);
     }
     rpc_send_event(data->channel_id, "redraw", data->buffer);
@@ -549,7 +549,7 @@ static Array translate_firstarg(UI *ui, Array args)
 
 static void remote_ui_event(UI *ui, char *name, Array args, bool *args_consumed)
 {
-  if (!ui->ui_ext[kUINewgrid]) {
+  if (!ui->ui_ext[kUILinegrid]) {
     // the representation of highlights in cmdline changed, translate back
     // never consumes args
     if (strequal(name, "cmdline_show")) {

src/nvim/api/ui_events.in.h

@@ -63,7 +63,7 @@ void set_scroll_region(Integer top, Integer bot, Integer left, Integer right)
 void scroll(Integer count)
   FUNC_API_SINCE(3) FUNC_API_REMOTE_ONLY;
 
-// Second revison of the grid protocol, used with ext_newgrid ui option
+// Second revison of the grid protocol, used with ext_linegrid ui option
 void default_colors_set(Integer rgb_fg, Integer rgb_bg, Integer rgb_sp,
                         Integer cterm_fg, Integer cterm_bg)
   FUNC_API_SINCE(5) FUNC_API_REMOTE_IMPL;

src/nvim/syntax.c

@@ -6884,7 +6884,7 @@ void do_highlight(const char *line, const bool forceit, const bool init)
       // "fg", which have been changed now.
       highlight_attr_set_all();
 
-      if (!ui_is_external(kUINewgrid) && starting == 0) {
+      if (!ui_is_external(kUILinegrid) && starting == 0) {
         // Older UIs assume that we clear the screen after normal group is
         // changed
         ui_refresh();

src/nvim/tui/tui.c

@@ -156,7 +156,7 @@ UI *tui_start(void)
   ui->raw_line = tui_raw_line;
 
   memset(ui->ui_ext, 0, sizeof(ui->ui_ext));
-  ui->ui_ext[kUINewgrid] = true;
+  ui->ui_ext[kUILinegrid] = true;
 
   return ui_bridge_attach(ui, tui_main, tui_scheduler);
 }

src/nvim/ui.h

@@ -15,7 +15,7 @@ typedef enum {
   kUITabline,
   kUIWildmenu,
 #define kUIGlobalCount (kUIWildmenu+1)
-  kUINewgrid,
+  kUILinegrid,
   kUIHlState,
   kUIExtCount,
 } UIExtension;
@@ -25,7 +25,7 @@ EXTERN const char *ui_ext_names[] INIT(= {
   "ext_popupmenu",
   "ext_tabline",
   "ext_wildmenu",
-  "ext_newgrid",
+  "ext_linegrid",
   "ext_hlstate",
 });
 

test/functional/api/version_spec.lua

@@ -156,6 +156,6 @@ describe("ui_options in metadata", function()
     local api = helpers.call('api_info')
     local options = api.ui_options
     eq({'rgb', 'ext_cmdline', 'ext_popupmenu',
-        'ext_tabline', 'ext_wildmenu', 'ext_newgrid', 'ext_hlstate'}, options)
+        'ext_tabline', 'ext_wildmenu', 'ext_linegrid', 'ext_hlstate'}, options)
   end)
 end)

test/functional/api/vim_spec.lua

@@ -1254,7 +1254,7 @@ describe('API', function()
           ext_popupmenu = false,
           ext_tabline = false,
           ext_wildmenu = false,
-          ext_newgrid = screen._options.ext_newgrid or false,
+          ext_linegrid = screen._options.ext_linegrid or false,
           ext_hlstate=false,
           height = 4,
           rgb = true,

test/functional/terminal/tui_spec.lua

@@ -258,10 +258,10 @@ describe('tui', function()
     feed_data(':echo map(nvim_list_uis(), {k,v -> sort(items(v))})\013')
     screen:expect([=[
       [[['ext_cmdline', v:false], ['ext_hlstate', v:fals|
-      e], ['ext_newgrid', v:true], ['ext_popupmenu', v:f|
+      e], ['ext_linegrid', v:true], ['ext_popupmenu', v:|
-      alse], ['ext_tabline', v:false], ['ext_wildmenu', |
+      false], ['ext_tabline', v:false], ['ext_wildmenu',|
-      v:false], ['height', 6], ['rgb', v:false], ['width|
+       v:false], ['height', 6], ['rgb', v:false], ['widt|
-      ', 50]]]                                          |
+      h', 50]]]                                         |
       {10:Press ENTER or type command to continue}{1: }          |
       {3:-- TERMINAL --}                                    |
     ]=])

test/functional/ui/cmdline_spec.lua

@@ -4,13 +4,13 @@ local clear, feed = helpers.clear, helpers.feed
 local source = helpers.source
 local command = helpers.command
 
-local function test_cmdline(newgrid)
+local function test_cmdline(linegrid)
   local screen
 
   before_each(function()
     clear()
     screen = Screen.new(25, 5)
-    screen:attach({rgb=true, ext_cmdline=true, ext_newgrid=newgrid})
+    screen:attach({rgb=true, ext_cmdline=true, ext_linegrid=linegrid})
     screen:set_default_attr_ids({
       [1] = {bold = true, foreground = Screen.colors.Blue1},
       [2] = {reverse = true},
@@ -608,7 +608,7 @@ local function test_cmdline(newgrid)
   end)
 end
 
--- the representation of cmdline and cmdline_block contents changed with ext_newgrid
+-- the representation of cmdline and cmdline_block contents changed with ext_linegrid
 -- (which uses indexed highlights) so make sure to test both
 describe('ui/ext_cmdline', function() test_cmdline(true) end)
 describe('ui/ext_cmdline (legacy highlights)', function() test_cmdline(false) end)

test/functional/ui/embed_spec.lua

@@ -5,14 +5,14 @@ local feed = helpers.feed
 local eq = helpers.eq
 local clear = helpers.clear
 
-local function test_embed(ext_newgrid)
+local function test_embed(ext_linegrid)
   local screen
   local function startup(...)
     clear{headless=false, args={...}}
 
     -- attach immediately after startup, for early UI
     screen = Screen.new(60, 8)
-    screen:attach{ext_newgrid=ext_newgrid}
+    screen:attach{ext_linegrid=ext_linegrid}
     screen:set_default_attr_ids({
       [1] = {foreground = Screen.colors.Grey100, background = Screen.colors.Red},
       [2] = {bold = true, foreground = Screen.colors.SeaGreen4},
@@ -77,5 +77,5 @@ local function test_embed(ext_newgrid)
   end)
 end
 
-describe('--embed UI on startup (ext_newgrid=true)', function() test_embed(true) end)
+describe('--embed UI on startup (ext_linegrid=true)', function() test_embed(true) end)
-describe('--embed UI on startup (ext_newgrid=false)', function() test_embed(false) end)
+describe('--embed UI on startup (ext_linegrid=false)', function() test_embed(false) end)

test/functional/ui/options_spec.lua

@@ -30,15 +30,15 @@ describe('ui receives option updates', function()
     ext_popupmenu=false,
     ext_tabline=false,
     ext_wildmenu=false,
-    ext_newgrid=false,
+    ext_linegrid=false,
     ext_hlstate=false,
   }
 
   it("for defaults", function()
     screen:attach()
-    -- NB: UI test suite can be run in both "newgrid" and legacy grid mode.
+    -- NB: UI test suite can be run in both "linegrid" and legacy grid mode.
     -- In both cases check that the received value is the one requested.
-    defaults.ext_newgrid = screen._options.ext_newgrid or false
+    defaults.ext_linegrid = screen._options.ext_linegrid or false
     screen:expect(function()
       eq(defaults, screen.options)
     end)
@@ -46,7 +46,7 @@ describe('ui receives option updates', function()
 
   it("when setting options", function()
     screen:attach()
-    defaults.ext_newgrid = screen._options.ext_newgrid or false
+    defaults.ext_linegrid = screen._options.ext_linegrid or false
     local changed = {}
     for k,v in pairs(defaults) do
       changed[k] = v
@@ -95,7 +95,7 @@ describe('ui receives option updates', function()
     end
 
     screen:attach({ext_cmdline=true, ext_wildmenu=true})
-    defaults.ext_newgrid = screen._options.ext_newgrid or false
+    defaults.ext_linegrid = screen._options.ext_linegrid or false
     changed.ext_cmdline = true
     changed.ext_wildmenu = true
     screen:expect(function()

test/functional/ui/screen.lua

@@ -185,11 +185,11 @@ function Screen:attach(options)
   if options == nil then
     options = {}
   end
-  if options.ext_newgrid == nil then
+  if options.ext_linegrid == nil then
-    options.ext_newgrid = true
+    options.ext_linegrid = true
   end
   self._options = options
-  self._clear_attrs = (options.ext_newgrid and {{},{}}) or {}
+  self._clear_attrs = (options.ext_linegrid and {{},{}}) or {}
   uimeths.attach(self._width, self._height, options)
   if self._options.rgb == nil then
     -- nvim defaults to rgb=true internally,
@@ -609,6 +609,7 @@ function Screen:_handle_highlight_set(attrs)
 end
 
 function Screen:_handle_put(str)
+  assert(not self._options.ext_linegrid)
   local cell = self._rows[self._cursor.row][self._cursor.col]
   cell.text = str
   cell.attrs = self._attrs
@@ -617,6 +618,7 @@ function Screen:_handle_put(str)
 end
 
 function Screen:_handle_grid_line(grid, row, col, items)
+  assert(self._options.ext_linegrid)
   assert(grid == 1)
   local line = self._rows[row+1]
   local colpos = col+1
@@ -764,7 +766,7 @@ function Screen:_row_repr(row, attr_state)
   local current_attr_id
   for i = 1, self._width do
     local attrs = row[i].attrs
-    if self._options.ext_newgrid then
+    if self._options.ext_linegrid then
       attrs = attrs[(self._options.rgb and 1) or 2]
     end
     local attr_id = self:_get_attr_id(attr_state, attrs, row[i].hl_id)
@@ -820,7 +822,7 @@ function Screen:_chunks_repr(chunks, attr_state)
   for i, chunk in ipairs(chunks) do
     local hl, text = unpack(chunk)
     local attrs
-    if self._options.ext_newgrid then
+    if self._options.ext_linegrid then
       attrs = self._attr_table[hl][1]
     else
       attrs = hl

test/functional/ui/screen_basic_spec.lua

@@ -48,13 +48,13 @@ describe('screen', function()
   end)
 end)
 
-local function screen_tests(newgrid)
+local function screen_tests(linegrid)
   local screen
 
   before_each(function()
     clear()
     screen = Screen.new()
-    screen:attach({rgb=true,ext_newgrid=newgrid})
+    screen:attach({rgb=true,ext_linegrid=linegrid})
     screen:set_default_attr_ids( {
       [0] = {bold=true, foreground=255},
       [1] = {bold=true, reverse=true},