Implement getViewscreenByType() in lua

docs/Lua API.rst

@@ -856,6 +856,12 @@ Gui module
 
   Returns the focus string of the current viewscreen.
 
+* ``dfhack.gui.getViewscreenByType(type [, depth])``
+
+  Returns the topmost viewscreen out of the top ``depth`` viewscreens with
+  the specified type (e.g. ``df.viewscreen_titlest``), or ``nil`` if none match.
+  If ``limit`` is not specified or is less than 1, all viewscreens are checked.
+
 * ``dfhack.gui.getSelectedWorkshopJob([silent])``
 
   When a job is selected in *'q'* mode, returns the job, else

library/lua/dfhack.lua

@@ -285,6 +285,27 @@ function dfhack.buildings.getSize(bld)
     return bld.x2+1-x, bld.y2+1-y, bld.centerx-x, bld.centery-y
 end
 
+function dfhack.gui.getViewscreenByType(scr_type, n)
+    -- translated from modules/Gui.cpp
+    if n == nil then
+        n = 1
+    end
+    local limit = (n > 0)
+    local scr = dfhack.gui.getCurViewscreen()
+    while scr do
+        if limit then
+            n = n - 1
+            if n < 0 then
+                return nil
+            end
+        end
+        if scr_type:is_instance(scr) then
+            return scr
+        end
+        scr = scr.parent
+    end
+end
+
 -- Interactive
 
 local print_banner = true