From cae2bca0a7487195d0381c9bf4013d0fcaf0773f Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Sat, 10 Sep 2022 09:49:22 -0700
Subject: [PATCH] add dfhack.screen.hideGuard

---
 docs/Lua API.rst   |  6 ++++++
 library/LuaApi.cpp | 16 ++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/docs/Lua API.rst b/docs/Lua API.rst
index 942ccfa8f..71094414f 100644
--- a/docs/Lua API.rst	
+++ b/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.
diff --git a/library/LuaApi.cpp b/library/LuaApi.cpp
index d04da21ec..70cb01dfc 100644
--- a/library/LuaApi.cpp
+++ b/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),