add dfhack.screen.hideGuard

docs/Lua API.rst

@@ -1992,6 +1992,12 @@ Functions:
   Returns: *tile, tile_grayscale*, or *nil* if not found.
   The values can then be used for the *tile* field of *pen* structures.
 
+* ``dfhack.screen.hideGuard(screen,callback[,args...])``
+
+  Removes screen from the viewscreen stack, calls the callback (with optional
+  supplied arguments), and then restores the screen on the top of the viewscreen
+  stack.
+
 * ``dfhack.screen.clear()``
 
   Fills the screen with blank background.

library/LuaApi.cpp

@@ -2370,6 +2370,21 @@ static int screen_findGraphicsTile(lua_State *L)
     }
 }
 
+static int screen_hideGuard(lua_State *L) {
+    df::viewscreen *screen = dfhack_lua_viewscreen::get_pointer(L, 1, false);
+    luaL_checktype(L, 2, LUA_TFUNCTION);
+
+    // remove screen from the stack so it doesn't get returned as an output
+    lua_remove(L, 1);
+
+    Screen::Hide hideGuard(screen, Screen::Hide::RESTORE_AT_TOP);
+
+    int nargs = lua_gettop(L) - 1;
+    lua_call(L, nargs, LUA_MULTRET);
+
+    return lua_gettop(L);
+}
+
 namespace {
 
 int screen_show(lua_State *L)
@@ -2472,6 +2487,7 @@ static const luaL_Reg dfhack_screen_funcs[] = {
     { "paintString", screen_paintString },
     { "fillRect", screen_fillRect },
     { "findGraphicsTile", screen_findGraphicsTile },
+    CWRAP(hideGuard, screen_hideGuard),
     CWRAP(show, screen_show),
     CWRAP(dismiss, screen_dismiss),
     CWRAP(isDismissed, screen_isDismissed),