return self from raise, update docs

docs/dev/Lua API.rst

@@ -4117,9 +4117,10 @@ ZScreen provides the following functions:
 
 * ``zscreen:raise()``
 
-  Raises the ZScreen to the top of the viewscreen stack. Note that this is
-  handled automatically for common cases (e.g. player clicks on a Window
-  belonging to a ZScreen that is not the top viewscreen).
+  Raises the ZScreen to the top of the viewscreen stack and returns a reference
+  to ``self``. A common pattern is to check if a tool dialog is already active
+  when the tool command is run and raise the existing dialog if it exists or
+  show a new dialog if it doesn't. See the sample code below for an example.
 
 * ``zscreen:isMouseOver()``
 
@@ -4130,6 +4131,43 @@ ZScreen provides the following functions:
   there are multiple independent windows being shown and this function should
   return true if the mouse is over any of them.
 
+Here is an example skeleton for a ZScreen tool dialog::
+
+    local gui = require('gui')
+    local widgets = require('gui.widgets')
+
+    MyWindow = defclass(MyWindow, widgets.Window)
+    MyWindow.ATTRS {
+        frame_title='My Window',
+        frame={w=50, h=45},
+        resizable=true, -- if resizing makes sense for your dialog
+    }
+
+    function MyWindow:init()
+        self:addviews{
+          -- add subviews here
+        }
+    end
+
+    function MyWindow:onInput(keys)
+        -- if required
+    end
+
+    MyScreen = defclass(MyScreen, gui.ZScreen)
+    MyScreen.ATTRS {
+        focus_path='myscreen',
+    }
+
+    function MyScreen:init()
+        self:addviews{MyWindow{view_id='main'}}
+    end
+
+    function MyScreen:onDismiss()
+        view = nil
+    end
+
+    view = view and view:raise() or MyScreen{}:show()
+
 FramedScreen class
 ------------------
 

library/lua/gui.lua

@@ -702,12 +702,12 @@ function ZScreen:render(dc)
     ZScreen.super.render(self, dc)
 end
 
-local function zscreen_is_top(self)
+function ZScreen:isOnTop()
     return dfhack.gui.getCurViewscreen(true) == self._native
 end
 
 function ZScreen:onInput(keys)
-    if not zscreen_is_top(self) then
+    if not self:isOnTop() then
         if keys._MOUSE_L_DOWN and self:isMouseOver() then
             self:raise()
         else
@@ -734,10 +734,11 @@ end
 
 -- move this viewscreen to the top of the stack (if it's not there already)
 function ZScreen:raise()
-    if self:isDismissed() or zscreen_is_top(self) then
-        return
+    if self:isDismissed() or self:isOnTop() then
+        return self
     end
     dscreen.raise(self)
+    return self
 end
 
 -- subclasses should either annotate their viewable panel with view_id='main'