Merge pull request #2900 from myk002/myk_zscreen

refine ZScreen behavior around pausing, update docs
develop
Myk 2023-02-13 13:14:17 -08:00 committed by GitHub
commit f22856bdda
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 46 additions and 32 deletions

@ -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!

@ -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

@ -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()

@ -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