add Gui::getDFViewscreen and Lua binding

docs/changelog.txt

@@ -48,12 +48,14 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 
 ## API
 - ``Gui::getDwarfmodeDims``: now only returns map viewport dimensions; menu dimensions are obsolete
+- ``Gui::getDFViewscreen``: returns the topmost underlying DF viewscreen
 
 ## Lua
 - ``gui.View``: ``visible`` and ``active`` can now be functions that return a boolean
 - ``widgets.Panel``: new attributes to control window dragging and resizing with mouse or keyboard
 - ``widgets.Window``: Panel subclass with attributes preset for top-level windows
 - `overlay`: ``OverlayWidget`` now inherits from ``Panel`` instead of ``Widget`` to get all the frame and mouse integration goodies
+- ``dfhack.gui.getDFViewscreen()``: returns the topmost underlying DF viewscreen
 
 ## Internals
 

docs/dev/Lua API.rst

@@ -965,6 +965,11 @@ Screens
   the specified type (e.g. ``df.viewscreen_titlest``), or ``nil`` if none match.
   If ``depth`` is not specified or is less than 1, all viewscreens are checked.
 
+* ``dfhack.gui.getDFViewscreen([skip_dismissed])``
+
+  Returns the topmost viewscreen not owned by DFHack. If ``skip_dismissed`` is
+  ``true``, ignores screens already marked to be removed.
+
 General-purpose selections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

library/LuaApi.cpp

@@ -1454,6 +1454,7 @@ static int gui_getMousePos(lua_State *L)
 
 static const LuaWrapper::FunctionReg dfhack_gui_module[] = {
     WRAPM(Gui, getCurViewscreen),
+    WRAPM(Gui, getDFViewscreen),
     WRAPM(Gui, getFocusString),
     WRAPM(Gui, getCurFocus),
     WRAPM(Gui, getSelectedWorkshopJob),

library/include/modules/Gui.h

@@ -181,6 +181,9 @@ namespace DFHack
 
         DFHACK_EXPORT df::viewscreen *getViewscreenByIdentity(virtual_identity &id, int n = 1);
 
+        /// Get the top-most underlying DF viewscreen (not owned by DFHack)
+        DFHACK_EXPORT df::viewscreen *getDFViewscreen(bool skip_dismissed = false);
+
         /// Get the top-most viewscreen of the given type from the top `n` viewscreens (or all viewscreens if n < 1)
         /// returns NULL if none match
         template <typename T>

library/modules/Gui.cpp

@@ -1873,6 +1873,12 @@ bool Gui::autoDFAnnouncement(df::announcement_type type, df::coord pos, std::str
     return autoDFAnnouncement(r, message);
 }
 
+static df::viewscreen * do_skip_dismissed(df::viewscreen * ws) {
+    while (ws && Screen::isDismissed(ws) && ws->parent)
+        ws = ws->parent;
+    return ws;
+}
+
 df::viewscreen *Gui::getCurViewscreen(bool skip_dismissed)
 {
     if (!gview)
@@ -1883,10 +1889,7 @@ df::viewscreen *Gui::getCurViewscreen(bool skip_dismissed)
         ws = ws->child;
 
     if (skip_dismissed)
-    {
-        while (ws && Screen::isDismissed(ws) && ws->parent)
-            ws = ws->parent;
-    }
+        ws = do_skip_dismissed(ws);
 
     return ws;
 }
@@ -1906,6 +1909,16 @@ df::viewscreen *Gui::getViewscreenByIdentity (virtual_identity &id, int n)
     return NULL;
 }
 
+df::viewscreen *Gui::getDFViewscreen(bool skip_dismissed) {
+    df::viewscreen *screen = Gui::getCurViewscreen(skip_dismissed);
+    while (screen && dfhack_viewscreen::is_instance(screen)) {
+        screen = screen->parent;
+        if (skip_dismissed)
+            screen = do_skip_dismissed(screen);
+    }
+    return screen;
+}
+
 df::coord Gui::getViewportPos()
 {
     if (!df::global::window_x || !df::global::window_y || !df::global::window_z)