Merge pull request #2377 from myk002/myk_gui_convenience

Make View:getMousePos() and Screen:show() a bit more flexible

docs/Lua API.rst

@@ -3707,10 +3707,11 @@ The class has the following methods:
 
   Returns the dimensions of the ``frame_body`` rectangle.
 
-* ``view:getMousePos()``
+* ``view:getMousePos([view_rect])``
 
-  Returns the mouse *x,y* in coordinates local to the ``frame_body``
+  Returns the mouse *x,y* in coordinates local to the given ViewRect (or
-  rectangle if it is within its clip area, or nothing otherwise.
+  ``frame_body`` if no ViewRect is passed) if it is within its clip area,
+  or nothing otherwise.
 
 * ``view:updateLayout([parent_rect])``
 
@@ -3829,7 +3830,9 @@ It adds the following methods:
   ``dfhack.screen.show``, calls ``self:onAboutToShow(parent)``. Note that
   ``onAboutToShow()`` can dismiss active screens, and therefore change the
   potential parent. If parent is not specified, this function will re-detect the
-  current topmost window after ``self:onAboutToShow(parent)`` returns.
+  current topmost window after ``self:onAboutToShow(parent)`` returns. This
+  function returns ``self`` as a convenience so you can write such code as
+  ``local view = MyScreen{params=val}:show()``.
 
 * ``screen:onAboutToShow(parent)`` *(for overriding)*
 

docs/changelog.txt

@@ -80,6 +80,8 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - ``dfhack.constructions.findAtTile()``: exposed preexisting function to Lua.
 - ``dfhack.constructions.insert()``: exposed new function to Lua.
 - ``widgets.EditField`` now allows other widgets to process characters that the ``on_char`` callback rejects.
+- ``gui.Screen.show()`` now returns ``self`` as a convenience
+- ``gui.View.getMousePos()`` now takes an optional ``ViewRect`` parameter in case the caller wants to get the mouse pos relative to a rect that is not the frame_body (such as the frame_rect)
 
 # 0.47.05-r7
 

library/lua/gui.lua

@@ -473,8 +473,8 @@ function View:getWindowSize()
     return rect.width, rect.height
 end
 
-function View:getMousePos()
+function View:getMousePos(view_rect)
-    local rect = self.frame_body
+    local rect = view_rect or self.frame_body
     local x,y = dscreen.getMousePos()
     if rect and rect:inClipGlobalXY(x,y) then
         return rect:localXY(x,y)
@@ -641,6 +641,7 @@ function Screen:show(parent)
     if not dscreen.show(self, parent.child) then
         error('Could not show screen')
     end
+    return self
 end
 
 function Screen:onAboutToShow(parent)