Merge pull request #9064 from bfredl/uidoc

UI: rename ext_newgrid to ext_linegrid and add --embed UI startup recommendations

8 files changed, 45 insertions, 28 deletions

diff --git a/test/functional/api/version_spec.lua b/test/functional/api/version_spec.lua
index e0472977cc..c3b332c8e7 100644
--- a/test/functional/api/version_spec.lua
+++ b/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)
diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua
index 5261f57ca7..5ca133267d 100644
--- a/test/functional/api/vim_spec.lua
+++ b/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,
diff --git a/test/functional/terminal/tui_spec.lua b/test/functional/terminal/tui_spec.lua
index 351038e521..09f80ca849 100644
--- a/test/functional/terminal/tui_spec.lua
+++ b/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|
-      alse], ['ext_tabline', v:false], ['ext_wildmenu', |
-      v:false], ['height', 6], ['rgb', v:false], ['width|
-      ', 50]]]                                          |
+      e], ['ext_linegrid', v:true], ['ext_popupmenu', v:|
+      false], ['ext_tabline', v:false], ['ext_wildmenu',|
+       v:false], ['height', 6], ['rgb', v:false], ['widt|
+      h', 50]]]                                         |
       {10:Press ENTER or type command to continue}{1: }          |
       {3:-- TERMINAL --}                                    |
     ]=])
diff --git a/test/functional/ui/cmdline_spec.lua b/test/functional/ui/cmdline_spec.lua
index d39b24a00f..af26a6d88f 100644
--- a/test/functional/ui/cmdline_spec.lua
+++ b/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)
diff --git a/test/functional/ui/embed_spec.lua b/test/functional/ui/embed_spec.lua
index 6a5227803d..4fc93c3b63 100644
--- a/test/functional/ui/embed_spec.lua
+++ b/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_newgrid=false)', function() test_embed(false) end)
+describe('--embed UI on startup (ext_linegrid=true)', function() test_embed(true) end)
+describe('--embed UI on startup (ext_linegrid=false)', function() test_embed(false) end)
diff --git a/test/functional/ui/options_spec.lua b/test/functional/ui/options_spec.lua
index 322a94763f..99aae16183 100644
--- a/test/functional/ui/options_spec.lua
+++ b/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()
diff --git a/test/functional/ui/screen.lua b/test/functional/ui/screen.lua
index 3831968f5b..691bf9f64c 100644
--- a/test/functional/ui/screen.lua
+++ b/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
-    options.ext_newgrid = true
+  if options.ext_linegrid == nil then
+    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,
@@ -386,9 +386,13 @@ function Screen:wait(check, timeout)
   local err, checked = false
   local success_seen = false
   local failure_after_success = false
+  local did_flush = true
   local function notification_cb(method, args)
     assert(method == 'redraw')
-    self:_redraw(args)
+    did_flush = self:_redraw(args)
+    if not did_flush then
+      return
+    end
     err = check()
     checked = true
     if not err then
@@ -402,7 +406,9 @@ function Screen:wait(check, timeout)
     return true
   end
   run(nil, notification_cb, nil, timeout or self.timeout)
-  if not checked then
+  if not did_flush then
+    err = "no flush received"
+  elseif not checked then
     err = check()
   end
 
@@ -431,7 +437,8 @@ function Screen:sleep(ms)
 end
 
 function Screen:_redraw(updates)
-  for _, update in ipairs(updates) do
+  local did_flush = false
+  for k, update in ipairs(updates) do
     -- print('--')
     -- print(require('inspect')(update))
     local method = update[1]
@@ -446,7 +453,11 @@ function Screen:_redraw(updates)
         self._on_event(method, update[i])
       end
     end
+    if k == #updates and method == "flush" then
+      did_flush = true
+    end
   end
+  return did_flush
 end
 
 function Screen:set_on_event_handler(callback)
@@ -472,6 +483,10 @@ function Screen:_handle_resize(width, height)
   }
 end
 
+function Screen:_handle_flush()
+end
+
+
 function Screen:_handle_grid_resize(grid, width, height)
   assert(grid == 1)
   self:_handle_resize(width, height)
@@ -609,6 +624,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 +633,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 +781,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 +837,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
diff --git a/test/functional/ui/screen_basic_spec.lua b/test/functional/ui/screen_basic_spec.lua
index 957d8c0915..31825bdbf4 100644
--- a/test/functional/ui/screen_basic_spec.lua
+++ b/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},