76 lines
3.0 KiB
ReStructuredText
76 lines
3.0 KiB
ReStructuredText
overlay
|
|
=======
|
|
|
|
.. dfhack-tool::
|
|
:summary: Manage on-screen overlay widgets.
|
|
:tags: dfhack interface
|
|
|
|
The overlay framework manages the on-screen widgets that other tools (including
|
|
3rd party plugins and scripts) can register for display. For a graphical
|
|
configuration interface, please see `gui/control-panel`. If you are a developer
|
|
who wants to write an overlay widget, please see the `overlay-dev-guide`.
|
|
|
|
Usage
|
|
-----
|
|
|
|
``enable overlay``
|
|
Display enabled widgets.
|
|
``overlay enable|disable all|<name or list number> [<name or list number> ...]``
|
|
Enable/disable all or specified widgets. Widgets can be specified by either
|
|
their name or their number, as returned by ``overlay list``.
|
|
``overlay list [<filter>]``
|
|
Show a list of all the widgets that are registered with the overlay
|
|
framework, optionally filtered by the given filter string.
|
|
``overlay position <name or list number> [default|<x> <y>]``
|
|
Display configuration information for the given widget or change the
|
|
position where it is rendered. See the `Widget position`_ section below for
|
|
details.
|
|
``overlay trigger <name or list number>``
|
|
Intended to be used by keybindings for manually triggering a widget. For
|
|
example, you could use an ``overlay trigger`` keybinding to show a menu that
|
|
normally appears when you hover the mouse over a screen hotspot.
|
|
|
|
Examples
|
|
--------
|
|
|
|
``overlay enable all``
|
|
Enable all widgets. Note that they will only be displayed on the screens
|
|
that they are associated with. You can see which screens a widget will be
|
|
displayed on, along with whether the widget is a hotspot, by calling
|
|
``overlay position``.
|
|
``overlay position hotkeys.menu``
|
|
Show the current configuration of the `hotkeys` menu widget.
|
|
``overlay position dwarfmonitor.cursor -2 -3``
|
|
Display the `dwarfmonitor` cursor position reporting widget in the lower
|
|
right corner of the screen, 2 tiles from the left and 3 tiles from the
|
|
bottom.
|
|
``overlay position dwarfmonitor.cursor default``
|
|
Reset the `dwarfmonitor` cursor position to its default.
|
|
``overlay trigger hotkeys.menu``
|
|
Trigger the `hotkeys` menu widget so that it shows its popup menu. This is
|
|
what is run when you hit :kbd:`Ctrl`:kbd:`Shift`:kbd:`C`.
|
|
|
|
Widget position
|
|
---------------
|
|
|
|
Widgets can be positioned at any (``x``, ``y``) position on the screen, and can
|
|
be specified relative to any edge. Coordinates are 1-based, which means that
|
|
``1`` is the far left column (for ``x``) or the top row (for ``y``). Negative
|
|
numbers are measured from the right of the screen to the right edge of the
|
|
widget or from the bottom of the screen to the bottom of the widget,
|
|
respectively.
|
|
|
|
For easy reference, the corners can be found at the following coordinates:
|
|
|
|
:(1, 1): top left corner
|
|
:(-1, 1): top right corner
|
|
:(1, -1): lower left corner
|
|
:(-1, -1): lower right corner
|
|
|
|
Overlay
|
|
-------
|
|
|
|
The `overlay` plugin also provides a standard overlay itself:
|
|
``title_version``, which displays the DFHack version on the DF title screen,
|
|
along with quick links to `quickstart-guide` and `gui/control-panel`.
|