allow getMousePos to return out of bounds coordinates

docs/changelog.txt

@@ -80,10 +80,12 @@ Template for new versions:
 - ``Maps::getWalkableGroup``: get the walkability group of a tile
 - ``Units::getReadableName``: now returns the *untranslated* name
 - ``Burrows::setAssignedUnit``: now properly handles inactive burrows
+- ``Gui::getMousePos``: now takes an optional ``allow_out_of_bounds`` parameter so coordinates can be returned for mouse positions outside of the game map (i.e. in the blank space around the map)
 
 ## Lua
 - ``dfhack.gui.revealInDwarfmodeMap``: gained ``highlight`` parameter to control setting the tile highlight on the zoom target
 - ``dfhack.maps.getWalkableGroup``: get the walkability group of a tile
+- ``dfhack.gui.getMousePos``: support new optional ``allow_out_of_bounds`` parameter
 - ``gui.FRAME_THIN``: a panel frame suitable for floating tooltips
 
 ## Removed

docs/dev/Lua API.rst

@@ -1140,10 +1140,12 @@ Announcements
 
   If you want a guaranteed announcement without parsing, use ``dfhack.gui.showAutoAnnouncement`` instead.
 
-* ``dfhack.gui.getMousePos()``
+* ``dfhack.gui.getMousePos([allow_out_of_bounds])``
 
   Returns the map coordinates of the map tile the mouse is over as a table of
-  ``{x, y, z}``. If the cursor is not over the map, returns ``nil``.
+  ``{x, y, z}``. If the cursor is not over a valid tile, returns ``nil``. To
+  allow the function to return coordinates outside of the map, set
+  ``allow_out_of_bounds`` to ``true``.
 
 Other
 ~~~~~

library/LuaApi.cpp

@@ -1505,8 +1505,9 @@ static int gui_getDwarfmodeViewDims(lua_State *state)
 
 static int gui_getMousePos(lua_State *L)
 {
-    auto pos = Gui::getMousePos();
-    if (pos.isValid())
+    bool allow_out_of_bounds = lua_toboolean(L, 1);
+    df::coord pos = Gui::getMousePos(allow_out_of_bounds);
+    if ((allow_out_of_bounds && pos.z >= 0) || pos.isValid())
         Lua::Push(L, pos);
     else
         lua_pushnil(L);

library/include/modules/Gui.h

@@ -150,7 +150,7 @@ namespace DFHack
          */
         DFHACK_EXPORT df::coord getViewportPos();
         DFHACK_EXPORT df::coord getCursorPos();
-        DFHACK_EXPORT df::coord getMousePos();
+        DFHACK_EXPORT df::coord getMousePos(bool allow_out_of_bounds = false);
 
         static const int AREA_MAP_WIDTH = 23;
         static const int MENU_WIDTH = 30;

library/modules/Gui.cpp

@@ -2257,7 +2257,7 @@ bool Gui::setDesignationCoords (const int32_t x, const int32_t y, const int32_t
 }
 
 // returns the map coordinates that the mouse cursor is over
-df::coord Gui::getMousePos()
+df::coord Gui::getMousePos(bool allow_out_of_bounds)
 {
     df::coord pos;
     if (gps && gps->precise_mouse_x > -1) {
@@ -2271,7 +2271,7 @@ df::coord Gui::getMousePos()
             pos.y += gps->mouse_y;
         }
     }
-    if (!Maps::isValidTilePos(pos.x, pos.y, pos.z))
+    if (!allow_out_of_bounds && !Maps::isValidTilePos(pos.x, pos.y, pos.z))
         return df::coord();
     return pos;
 }