Deprecate some functions and add form:update

README.md

@@ -88,6 +88,45 @@ my_gui:show_hud(player)
 my_gui:close_hud(player)
 ```
 
+### Updating forms
+
+If some data displayed inside a form changes (for example a timer or progress
+indicator), you can use `form:update` to update the form without resetting
+`ctx` or showing the form again if the player has closed it.
+
+Due to formspec limitations, players may lose text typed into fields that
+hasn't been sent to the server when `form:update` is called.
+
+```
+-- Re-shows the form for one player if they have the form open
+my_gui:update(player)
+
+-- Re-shows the form for all players that have the form open and where
+-- ctx.test == 123
+my_gui:update_where(function(player, ctx)
+    return ctx.test == 123
+end)
+
+-- Re-shows the form for all players with the "server" privilege
+my_gui:update_where(function(player, ctx)
+    return minetest.check_player_privs(player, "server")
+end)
+
+-- Re-shows the form for all players with the form open
+my_gui:update_where(function() return true end)
+```
+
+Inside an `on_event` handler, you can use `return true` instead.
+
+```
+gui.Button{
+    label = "Update form",
+    on_event = function(player, ctx)
+        return true
+    end,
+}
+```
+
 ## Other formspec libraries/utilities
 
 These utilities likely aren't compatible with flow.
@@ -105,8 +144,8 @@ You should do `local gui = flow.widgets` in your code.
 
 ### Layouting elements
 
-These elements are used to lay out elements in the formspec. They don't have a
-direct equivalent in Minetest formspecs.
+These elements are used to lay out elements in the form. They don't have a
+direct equivalent in formspecs.
 
 #### `gui.VBox`
 

init.lua

@@ -199,6 +199,7 @@ function size_getters.hbox(hbox)
 end
 
 function size_getters.padding(node)
+    minetest.log("warning", "[flow] The gui.Padding element is deprecated")
     assert(#node == 1, "Padding can only have one element inside.")
     local n = node[1]
     local x, y = apply_padding(n, 0, 0)
@@ -599,6 +600,7 @@ local gui_mt = {
 }
 local gui = setmetatable({
     embed = function(fs, w, h)
+        minetest.log("warning", "[flow] gui.embed() is deprecated")
         if type(fs) ~= "table" then
             fs = formspec_ast.parse(fs)
         end
@@ -676,11 +678,13 @@ end
 local open_formspecs = {}
 function Form:show(player, ctx)
     if type(player) == "string" then
+        minetest.log("warning",
+            "[flow] Calling form:show() with a player name is deprecated")
         player = minetest.get_player_by_name(player)
         if not player then return end
     end
 
-    local t = minetest.get_us_time()
+    local t = DEBUG_MODE and minetest.get_us_time()
     ctx = ctx or {}
 
     -- The numbering of automatically named elements is continued from previous
@@ -697,9 +701,9 @@ function Form:show(player, ctx)
     local tree, form_info = self:_render(player, ctx,
         info and info.formspec_version, auto_name_id)
 
-    local t2 = minetest.get_us_time()
+    local t2 = DEBUG_MODE and minetest.get_us_time()
     local fs = assert(formspec_ast.unparse(tree))
-    local t3 = minetest.get_us_time()
+    local t3 = DEBUG_MODE and minetest.get_us_time()
 
     open_formspecs[name] = form_info
     if DEBUG_MODE then
@@ -721,6 +725,24 @@ function Form:close_hud(player)
     hud_fs.close_hud(player, self._formname)
 end
 
+function Form:update(player)
+    local form_info = open_formspecs[player:get_player_name()]
+    if form_info and form_info.self == self then
+        self:show(player, form_info.ctx)
+    end
+end
+
+function Form:update_where(func)
+    for name, form_info in pairs(open_formspecs) do
+        if form_info.self == self then
+            local player = minetest.get_player_by_name(name)
+            if player and func(player, form_info.ctx) then
+                self:show(player, form_info.ctx)
+            end
+        end
+    end
+end
+
 local used_ids = {}
 setmetatable(used_ids, {__mode = "v"})