Merge pull request #2900 from myk002/myk_zscreen

refine ZScreen behavior around pausing, update docs

docs/Quickstart.rst

@@ -79,7 +79,7 @@ hover list.
 The second place to check is the DFHack control panel: `gui/control-panel`. It
 will give you an overview of which tools are currently enabled, and will allow
 you to toggle them on or off, see help text for them, or launch their dedicated
-configuration UIs. You can launch the control panel from anywhere with the
+configuration UIs. You can open the control panel from anywhere with the
 Ctrl-Shift-E hotkey or by selecting it from the logo hover list.
 
 In the control panel, you can also select which tools you'd like to be
@@ -105,7 +105,7 @@ The bottom panel will show the full help text for the command you are running,
 allowing you to refer to the usage documentation and examples when you are typing
 your command. After you run a command, the bottom panel switches to command output
 mode, but you can get back to the help text by hitting Ctrl-T or clicking on the
-``Showing`` selector.
+``Help`` tab.
 
 How do DFHack in-game windows work?
 -----------------------------------
@@ -134,12 +134,12 @@ game is unpaused, it can continue to run while a DFHack window is open. If confi
 to do so in `gui/control-panel`, tools will initially pause the game to let you
 focus on the task at hand, but you can unpause like normal if you want. You can
 also interact with the map, scrolling it with the keyboard or mouse and selecting
-units, buildings, and items. Some tools will capture all keyboard input, such as
-tools with editable text fields, and some will force-pause the game if it makes
-sense to, like `gui/quickfort`, since you cannot interact with the map normally
-while trying to apply a blueprint. Windows for tools that force-pause the game
-will have a pause icon in their upper right corner to indicate which tool is
-preventing you from unpausing.
+units, buildings, and items. Some tools will intercept all mouse clicks to allow
+you to select regions on the map. When these tools have focus, you will not be able
+to use the mouse to interact with map elements or pause/unpause the game. Therefore,
+these tools will pause the game when they open, regardless of your settings in
+`gui/control-panel`. You can still unpause with the keyboard (spacebar by default),
+though.
 
 Where do I go next?
 -------------------
@@ -156,7 +156,7 @@ You can get to the launcher and its integrated autocomplete, history search,
 and help text by hitting backtick (\`) or Ctrl-Shift-D, or, of course, by
 running it from the logo hover list.
 
-With those three tools, you have the complete DFHack tool suite at your
+With those three interfaces, you have the complete DFHack tool suite at your
 fingertips. So what to run first? Here are a few commands to get you started.
 You can run them all from the launcher.
 
@@ -168,13 +168,13 @@ using the DFHack `overlay` widget at the bottom of the manager orders panel.
 
 Next, try setting up `autochop` to automatically designate trees for chopping when
 you get low on usable logs. Run `gui/control-panel` and select ``autochop`` in the
-list. Click on the button to the left of the name or hit Enter to enable it. You
-can then click on the ``[configure]`` button to launch `gui/autochop` if you'd
-like to customize its settings. If you have the extra screen space, you can go
-ahead and set the `gui/autochop` window to minimal mode (click on the hint near
-the upper right corner of the window or hit Alt-M) and click on the map so the
-window loses keyboard focus. As you play the game, you can glance at the live
-status panel to check on your stocks of wood.
+``Fort`` list. Click on the button to the left of the name or hit Enter to enable
+it. You can then click on the configure button (the gear icon) to launch
+`gui/autochop` if you'd like to customize its settings. If you have the extra
+screen space, you can go ahead and set the `gui/autochop` window to minimal mode
+(click on the hint near the upper right corner of the window or hit Alt-M) and
+click on the map so the window loses keyboard focus. As you play the game, you can
+glance at the live status panel to check on your stocks of wood.
 
 Finally, let's do some fort design copy-pasting. Go to some bedrooms that you have
 set up in your fort. Run `gui/blueprint`, set a name for your blueprint by
@@ -197,6 +197,9 @@ had designated the tiles yourself.
 
 Once the area is dug out, run `gui/quickfort` again and select the "/build" blueprint
 this time. Apply the blueprint in the dug-out area, and your furniture will be
-designated. It's just that easy!
+designated. It's just that easy! Note that `quickfort` uses `buildingplan` to place
+buildings, so you don't even need to have the relevant furniture or building
+materials in stock. The planned furniture/buildings will get built whenever you are
+able to produce the building materials.
 
 There are many, many more tools to explore. Have fun!

docs/changelog.txt

@@ -43,6 +43,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 -@ `autochop`: generate default names for burrows with no assigned names
 
 ## Misc Improvements
+- DFHack tool windows that capture mouse clicks (and therefore prevent you from clicking on the "pause" button) now unconditionally pause the game when they open (but you can still unpause with the keyboard if you want to). Examples of this behavior: `gui/quickfort`, `gui/blueprint`, `gui/liquids`
 - `showmood`: now shows the number of items needed for cloth and bars in addition to the technically correct but always confusing "total dimension" (150 per bar or 10,000 per cloth)
 
 ## Documentation

docs/dev/Lua API.rst

@@ -4149,7 +4149,7 @@ underlying map, or even other DFHack ZScreen windows! That is, even when the
 DFHack tool window is visible, players will be able to use vanilla designation
 tools, select units, and scan/drag the map around.
 
-At most one ZScreen can have keyboard focus at a time. That ZScreen's widgets
+At most one ZScreen can have input focus at a time. That ZScreen's widgets
 will have a chance to handle the input before anything else. If unhandled, the
 input skips all unfocused ZScreens under that ZScreen and is passed directly to
 the first non-ZScreen viewscreen. There are class attributes that can be set to
@@ -4168,8 +4168,8 @@ is dismissed.
 
 All this behavior is implemented in ``ZScreen:onInput()``, which subclasses
 **must not override**. Instead, ZScreen subclasses should delegate all input
-processing to subviews. Consider using a `Window class`_ widget as your top
-level input processor.
+processing to subviews. Consider using a `Window class`_ widget subview as your
+top level input processor.
 
 When rendering, the parent viewscreen is automatically rendered first, so
 subclasses do not have to call ``self:renderParent()``. Calls to ``logic()``
@@ -4179,8 +4179,8 @@ that passing ``logic()`` calls through to the underlying map is required for
 allowing the player to drag the map with the mouse. ZScreen subclasses can set
 attributes that control whether the game is paused when the ZScreen is shown and
 whether the game is forced to continue being paused while the ZScreen is shown.
-If pausing is forced, child ``Window`` widgets will show a force-pause icon to
-indicate which tool is forcing the pausing.
+If pausing is forced, child ``Window`` widgets will show a force-pause indicator
+to show which tool is forcing the pausing.
 
 ZScreen provides the following functions:
 
@@ -4195,8 +4195,9 @@ ZScreen provides the following functions:
 * ``zscreen:isMouseOver()``
 
   The default implementation iterates over the direct subviews of the ZScreen
-  subclass and sees if ``getMouseFramePos()`` returns a position for any of
-  them. Subclasses can override this function if that logic is not appropriate.
+  subclass (which usually only includes a single Window subview) and sees if
+  ``getMouseFramePos()`` returns a position for any of them. Subclasses can
+  override this function if that logic is not appropriate.
 
 * ``zscreen:hasFocus()``
 
@@ -4212,16 +4213,23 @@ ZScreen subclasses can set the following attributes:
   of the screen other than the tool window. If the player clicks on a different
   ZScreen window, focus still transfers to that other ZScreen.
 
-* ``initial_pause`` (default: ``DEFAULT_INITIAL_PAUSE``)
+* ``initial_pause`` (default: ``DEFAULT_INITIAL_PAUSE or not pass_mouse_clicks``)
 
-  Whether to pause the game when the ZScreen is shown. ``DEFAULT_INITIAL_PAUSE``
-  defaults to ``true`` but can be set via running a command like::
+  Whether to pause the game when the ZScreen is shown. If not explicitly set,
+  this attribute will be true if the system-wide ``DEFAULT_INITIAL_PAUSE`` is
+  ``true`` (which is its default value) or if the ``pass_mouse_clicks`` attribute
+  is ``false`` (see below). It depends on ``pass_mouse_clicks`` because if the
+  player normally pauses/unpauses the game with the mouse, they will not be able
+  to pause the game like they usually do while the ZScreen has focus.
+  ``DEFAULT_INITIAL_PAUSE`` can be customized permanently via `gui/control-panel`
+  or set for the session by running a command like::
 
     :lua require('gui.widgets').DEFAULT_INITIAL_PAUSE = false
 
 * ``force_pause`` (default: ``false``)
 
-  Whether to ensure the game *stays* paused while the ZScreen is shown.
+  Whether to ensure the game *stays* paused while the ZScreen is shown,
+  regardless of whether it has input focus.
 
 * ``pass_pause`` (default: ``true``)
 
@@ -4230,7 +4238,7 @@ ZScreen subclasses can set the following attributes:
 
 * ``pass_movement_keys`` (default: ``false``)
 
-  Whether to pass the map movement keys to the lower viewscreens if they ar not
+  Whether to pass the map movement keys to the lower viewscreens if they are not
   handled by this ZScreen.
 
 * ``pass_mouse_clicks`` (default: ``true``)
@@ -4238,7 +4246,7 @@ ZScreen subclasses can set the following attributes:
   Whether to pass mouse clicks to the lower viewscreens if they are not handled
   by this ZScreen.
 
-Here is an example skeleton for a ZScreen tool dialog::
+Here is an example skeleton for a ZScreen tool window::
 
     local gui = require('gui')
     local widgets = require('gui.widgets')
@@ -4265,6 +4273,7 @@ Here is an example skeleton for a ZScreen tool dialog::
     MyScreen.ATTRS {
         focus_path='myscreen',
         -- set pause and passthrough attributes as appropriate
+        -- (but most tools can use the defaults)
     }
 
     function MyScreen:init()

library/lua/gui.lua

@@ -708,8 +708,9 @@ ZScreen.ATTRS{
 }
 
 function ZScreen:preinit(args)
-    if args.initial_pause == nil then
-        args.initial_pause = DEFAULT_INITIAL_PAUSE
+    if self.ATTRS.initial_pause == nil then
+        args.initial_pause = DEFAULT_INITIAL_PAUSE or
+                (self.ATTRS.pass_mouse_clicks == false)
     end
 end