Merge pull request #2367 from myk002/myk_overlay_v2
[overlay] implement overlay v2 frameworkdevelop
Myk
GitHub
commit
63410d63c7
@ -0,0 +1,302 @@
|
||||
.. _overlay-dev-guide:
|
||||
|
||||
DFHack overlay dev guide
|
||||
=========================
|
||||
|
||||
.. highlight:: lua
|
||||
|
||||
This guide walks you through how to build overlay widgets and register them with
|
||||
the `overlay` framework for injection into Dwarf Fortress viewscreens.
|
||||
|
||||
Why would I want to create an overlay widget?
|
||||
---------------------------------------------
|
||||
|
||||
There are both C++ and Lua APIs for creating viewscreens and drawing to the
|
||||
screen. If you need very specific low-level control, those APIs might be the
|
||||
right choice for you. However, here are some reasons you might want to implement
|
||||
an overlay widget instead:
|
||||
|
||||
1. You can draw directly to an existing viewscreen instead of creating an
|
||||
entirely new screen on the viewscreen stack. This allows the original
|
||||
viewscreen to continue processing uninterrupted and keybindings bound to
|
||||
that viewscreen will continue to function. This was previously only
|
||||
achievable by C++ plugins.
|
||||
|
||||
1. You'll get a free UI for enabling/disabling your widget and repositioning it
|
||||
on the screen. Widget state is saved for you and is automatically restored
|
||||
when the game is restarted.
|
||||
|
||||
1. You don't have to manage the C++ interposing logic yourself and can focus on
|
||||
the business logic, writing purely in Lua if desired.
|
||||
|
||||
In general, if you are writing a plugin or script and have anything you'd like
|
||||
to add to an existing screen (including live updates of map tiles while the game
|
||||
is unpaused), an overlay widget is probably your easiest path to get it done. If
|
||||
your plugin or script doesn't otherwise need to be enabled to function, using
|
||||
the overlay allows you to avoid writing any of the enable management code that
|
||||
would normally be required for you to show info in the UI.
|
||||
|
||||
Overlay widget API
|
||||
------------------
|
||||
|
||||
Overlay widgets are Lua classes that inherit from ``overlay.OverlayWidget``
|
||||
(which itself inherits from `widgets.Widget <widget>`). The regular
|
||||
``onInput(keys)``, ``onRenderFrame(dc, frame_rect)``, and ``onRenderBody(dc)``
|
||||
functions work as normal, and they are called when the viewscreen that the
|
||||
widget is associated with does its usual input and render processing. The widget
|
||||
gets first dibs on input processing. If a widget returns ``true`` from its
|
||||
``onInput()`` function, the viewscreen will not receive the input.
|
||||
|
||||
Overlay widgets can contain other Widgets and be as simple or complex as you
|
||||
need them to be, just like you're building a regular UI element.
|
||||
|
||||
There are a few extra capabilities that overlay widgets have that take them
|
||||
beyond your everyday ``Widget``:
|
||||
|
||||
- If an ``overlay_onupdate(viewscreen)`` function is defined, it will be called
|
||||
just after the associated viewscreen's ``logic()`` function is called (i.e.
|
||||
a "tick" or a (non-graphical) "frame"). For hotspot widgets, this function
|
||||
will also get called after the top viewscreen's ``logic()`` function is
|
||||
called, regardless of whether the widget is associated with that viewscreen.
|
||||
If this function returns ``true``, then the widget's ``overlay_trigger()``
|
||||
function is immediately called. Note that the ``viewscreen`` parameter will
|
||||
be ``nil`` for hotspot widgets that are not also associated with the current
|
||||
viewscreen.
|
||||
- If an ``overlay_trigger()`` function is defined, will be called when the
|
||||
widget's ``overlay_onupdate`` callback returns true or when the player uses
|
||||
the CLI (or a keybinding calling the CLI) to trigger the widget. The
|
||||
function must return either ``nil`` or the ``gui.Screen`` object that the
|
||||
widget code has allocated, shown, and now owns. Hotspot widgets will receive
|
||||
no callbacks from unassociated viewscreens until the returned screen is
|
||||
dismissed. Unbound hotspot widgets **must** allocate a Screen with this
|
||||
function if they want to react to the ``onInput()`` feed or be rendered. The
|
||||
widgets owned by the overlay framework must not be attached to that new
|
||||
screen, but the returned screen can instantiate and configure any new views
|
||||
that it wants to.
|
||||
|
||||
If the widget can take up a variable amount of space on the screen, and you want
|
||||
the widget to adjust its position according to the size of its contents, you can
|
||||
modify ``self.frame.w`` and ``self.frame.h`` at any time -- in ``init()`` or in
|
||||
any of the callbacks -- to indicate a new size. The overlay framework will
|
||||
detect the size change and adjust the widget position and layout.
|
||||
|
||||
If you don't need to dynamically resize, just set ``self.frame.w`` and
|
||||
``self.frame.h`` once in ``init()``.
|
||||
|
||||
Widget attributes
|
||||
*****************
|
||||
|
||||
The ``overlay.OverlayWidget`` superclass defines the following class attributes:
|
||||
|
||||
- ``name``
|
||||
This will be filled in with the display name of your widget, in case you
|
||||
have multiple widgets with the same implementation but different
|
||||
configurations.
|
||||
- ``default_pos`` (default: ``{x=-2, y=-2}``)
|
||||
Override this attribute with your desired default widget position. See
|
||||
the `overlay` docs for information on what positive and negative numbers
|
||||
mean for the position. Players can change the widget position at any time
|
||||
via the `overlay position <overlay>` command, so don't assume that your
|
||||
widget will always be at the default position.
|
||||
- ``viewscreens`` (default: ``{}``)
|
||||
The list of viewscreens that this widget should be associated with. When
|
||||
one of these viewscreens is on top of the viewscreen stack, your widget's
|
||||
callback functions for update, input, and render will be interposed into the
|
||||
viewscreen's call path. The name of the viewscreen is the name of the DFHack
|
||||
class that represents the viewscreen, minus the ``viewscreen_`` prefix and
|
||||
``st`` suffix. For example, the fort mode main map viewscreen would be
|
||||
``dwarfmode`` and the adventure mode map viewscreen would be
|
||||
``dungeonmode``. If there is only one viewscreen that this widget is
|
||||
associated with, it can be specified as a string instead of a list of
|
||||
strings with a single element.
|
||||
- ``hotspot`` (default: ``false``)
|
||||
If set to ``true``, your widget's ``overlay_onupdate`` function will be
|
||||
called whenever the `overlay` plugin's ``plugin_onupdate()`` function is
|
||||
called (which corresponds to one call per call to the current top
|
||||
viewscreen's ``logic()`` function). This call to ``overlay_onupdate`` is in
|
||||
addition to any calls initiated from associated interposed viewscreens and
|
||||
will come after calls from associated viewscreens.
|
||||
- ``overlay_onupdate_max_freq_seconds`` (default: ``5``)
|
||||
This throttles how often a widget's ``overlay_onupdate`` function can be
|
||||
called (from any source). Set this to the largest amount of time (in
|
||||
seconds) that your widget can take to react to changes in information and
|
||||
not annoy the player. Set to 0 to be called at the maximum rate. Be aware
|
||||
that running more often than you really need to will impact game FPS,
|
||||
especially if your widget can run while the game is unpaused.
|
||||
|
||||
Registering a widget with the overlay framework
|
||||
***********************************************
|
||||
|
||||
Anywhere in your code after the widget classes are declared, define a table
|
||||
named ``OVERLAY_WIDGETS``. The keys are the display names for your widgets and
|
||||
the values are the widget classes. For example, the `dwarfmonitor` widgets are
|
||||
declared like this::
|
||||
|
||||
OVERLAY_WIDGETS = {
|
||||
cursor=CursorWidget,
|
||||
date=DateWidget,
|
||||
misery=MiseryWidget,
|
||||
weather=WeatherWidget,
|
||||
}
|
||||
|
||||
When the `overlay` plugin is enabled, it scans all plugins and scripts for
|
||||
this table and registers the widgets on your behalf. The widget is enabled if it
|
||||
was enabled the last time the `overlay` plugin was loaded and the widget's
|
||||
position is restored according to the state saved in the
|
||||
:file:`dfhack-config/overlay.json` file.
|
||||
|
||||
The overlay framework will instantiate widgets from the named classes and own
|
||||
the resulting objects. The instantiated widgets must not be added as subviews to
|
||||
any other View, including the Screen views that can be returned from the
|
||||
``overlay_trigger()`` function.
|
||||
|
||||
Widget example 1: adding text to a DF screen
|
||||
--------------------------------------------
|
||||
|
||||
This is a simple widget that displays a message at its position. The message
|
||||
text is retrieved from the host script or plugin every ~20 seconds or when
|
||||
the :kbd:`Alt`:kbd:`Z` hotkey is hit::
|
||||
|
||||
local overlay = require('plugins.overlay')
|
||||
local widgets = require('gui.widgets')
|
||||
|
||||
MessageWidget = defclass(MessageWidget, overlay.OverlayWidget)
|
||||
MessageWidget.ATTRS{
|
||||
default_pos={x=5,y=-2},
|
||||
viewscreens={'dwarfmode', 'dungeonmode'},
|
||||
overlay_onupdate_max_freq_seconds=20,
|
||||
}
|
||||
|
||||
function MessageWidget:init()
|
||||
self.label = widgets.Label{text=''}
|
||||
self:addviews{self.label}
|
||||
end
|
||||
|
||||
function MessageWidget:overlay_onupdate()
|
||||
local text = getImportantMessage() -- defined in the host script/plugin
|
||||
self.label:setText(text)
|
||||
self.frame.w = #text
|
||||
end
|
||||
|
||||
function MessageWidget:onInput(keys)
|
||||
if keys.CUSTOM_ALT_Z then
|
||||
self:overlay_onupdate()
|
||||
return true
|
||||
end
|
||||
end
|
||||
|
||||
OVERLAY_WIDGETS = {message=MessageWidget}
|
||||
|
||||
Widget example 2: highlighting artifacts on the live game map
|
||||
-------------------------------------------------------------
|
||||
|
||||
This widget is not rendered at its "position" at all, but instead monitors the
|
||||
map and overlays information about where artifacts are located. Scanning for
|
||||
which artifacts are visible on the map can slow, so that is only done every 10
|
||||
seconds to avoid slowing down the entire game on every frame.
|
||||
|
||||
::
|
||||
|
||||
local overlay = require('plugins.overlay')
|
||||
local widgets = require('gui.widgets')
|
||||
|
||||
ArtifactRadarWidget = defclass(ArtifactRadarWidget, overlay.OverlayWidget)
|
||||
ArtifactRadarWidget.ATTRS{
|
||||
viewscreens={'dwarfmode', 'dungeonmode'},
|
||||
overlay_onupdate_max_freq_seconds=10,
|
||||
}
|
||||
|
||||
function ArtifactRadarWidget:overlay_onupdate()
|
||||
self.visible_artifacts_coords = getVisibleArtifactCoords()
|
||||
end
|
||||
|
||||
function ArtifactRadarWidget:onRenderFrame()
|
||||
for _,pos in ipairs(self.visible_artifacts_coords) do
|
||||
-- highlight tile at given coordinates
|
||||
end
|
||||
end
|
||||
|
||||
OVERLAY_WIDGETS = {radar=ArtifactRadarWidget}
|
||||
|
||||
Widget example 3: corner hotspot
|
||||
--------------------------------
|
||||
|
||||
This hotspot reacts to mouseover events and launches a screen that can react to
|
||||
input events. The hotspot area is a 2x2 block near the lower right corner of the
|
||||
screen (by default, but the player can move it wherever).
|
||||
|
||||
::
|
||||
|
||||
local overlay = require('plugins.overlay')
|
||||
local widgets = require('gui.widgets')
|
||||
|
||||
HotspotMenuWidget = defclass(HotspotMenuWidget, overlay.OverlayWidget)
|
||||
HotspotMenuWidget.ATTRS{
|
||||
default_pos={x=-3,y=-3},
|
||||
frame={w=2, h=2},
|
||||
hotspot=true,
|
||||
viewscreens='dwarfmode',
|
||||
overlay_onupdate_max_freq_seconds=0, -- check for mouseover every tick
|
||||
}
|
||||
|
||||
function HotspotMenuWidget:init()
|
||||
-- note this label only gets rendered on the associated viewscreen
|
||||
-- (dwarfmode), but the hotspot is active on all screens
|
||||
self:addviews{widgets.Label{text={'!!', NEWLINE, '!!'}}}
|
||||
self.mouseover = false
|
||||
end
|
||||
|
||||
function HotspotMenuWidget:overlay_onupdate()
|
||||
local hasMouse = self:getMousePos()
|
||||
if hasMouse and not self.mouseover then -- only trigger on mouse entry
|
||||
self.mouseover = true
|
||||
return true
|
||||
end
|
||||
self.mouseover = hasMouse
|
||||
end
|
||||
|
||||
function HotspotMenuWidget:overlay_trigger()
|
||||
return MenuScreen{hotspot_frame=self.frame}:show()
|
||||
end
|
||||
|
||||
OVERLAY_WIDGETS = {menu=HotspotMenuWidget}
|
||||
|
||||
MenuScreen = defclass(MenuScreen, gui.Screen)
|
||||
MenuScreen.ATTRS{
|
||||
focus_path='hotspot/menu',
|
||||
hotspot_frame=DEFAULT_NIL,
|
||||
}
|
||||
|
||||
function MenuScreen:init()
|
||||
self.mouseover = false
|
||||
|
||||
-- derrive the menu frame from the hotspot frame so it
|
||||
-- can appear in a nearby location
|
||||
local frame = copyall(self.hotspot_frame)
|
||||
-- ...
|
||||
|
||||
self:addviews{
|
||||
widgets.ResizingPanel{
|
||||
autoarrange_subviews=true,
|
||||
frame=frame,
|
||||
frame_style=gui.GREY_LINE_FRAME,
|
||||
frame_background=gui.CLEAR_PEN,
|
||||
subviews={
|
||||
-- ...
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
end
|
||||
|
||||
function MenuScreen:onInput(keys)
|
||||
if keys.LEAVESCREEN then
|
||||
self:dismiss()
|
||||
return true
|
||||
end
|
||||
return self:inputToSubviews(keys)
|
||||
end
|
||||
|
||||
function MenuScreen:onRenderFrame(dc, rect)
|
||||
self:renderParent()
|
||||
end
|
||||
@ -0,0 +1,485 @@
|
||||
local _ENV = mkmodule('plugins.overlay')
|
||||
|
||||
local gui = require('gui')
|
||||
local json = require('json')
|
||||
local utils = require('utils')
|
||||
local widgets = require('gui.widgets')
|
||||
|
||||
local OVERLAY_CONFIG_FILE = 'dfhack-config/overlay.json'
|
||||
local OVERLAY_WIDGETS_VAR = 'OVERLAY_WIDGETS'
|
||||
|
||||
local DEFAULT_X_POS, DEFAULT_Y_POS = -2, -2
|
||||
|
||||
-- ---------------- --
|
||||
-- state and config --
|
||||
-- ---------------- --
|
||||
|
||||
local active_triggered_widget = nil
|
||||
local active_triggered_screen = nil -- if non-nil, hotspots will not get updates
|
||||
local widget_db = {} -- map of widget name to ephermeral state
|
||||
local widget_index = {} -- ordered list of widget names
|
||||
local overlay_config = {} -- map of widget name to persisted state
|
||||
local active_hotspot_widgets = {} -- map of widget names to the db entry
|
||||
local active_viewscreen_widgets = {} -- map of vs_name to map of w.names -> db
|
||||
|
||||
local function reset()
|
||||
if active_triggered_screen then
|
||||
active_triggered_screen:dismiss()
|
||||
end
|
||||
active_triggered_widget = nil
|
||||
active_triggered_screen = nil
|
||||
|
||||
widget_db = {}
|
||||
widget_index = {}
|
||||
|
||||
local ok, config = pcall(json.decode_file, OVERLAY_CONFIG_FILE)
|
||||
overlay_config = ok and config or {}
|
||||
|
||||
active_hotspot_widgets = {}
|
||||
active_viewscreen_widgets = {}
|
||||
end
|
||||
|
||||
local function save_config()
|
||||
if not safecall(json.encode_file, overlay_config, OVERLAY_CONFIG_FILE) then
|
||||
dfhack.printerr(('failed to save overlay config file: "%s"')
|
||||
:format(path))
|
||||
end
|
||||
end
|
||||
|
||||
local function triggered_screen_has_lock()
|
||||
if not active_triggered_screen then return false end
|
||||
if active_triggered_screen:isActive() then return true end
|
||||
active_triggered_widget = nil
|
||||
active_triggered_screen = nil
|
||||
return false
|
||||
end
|
||||
|
||||
-- ----------- --
|
||||
-- utility fns --
|
||||
-- ----------- --
|
||||
|
||||
local function normalize_list(element_or_list)
|
||||
if type(element_or_list) == 'table' then return element_or_list end
|
||||
return {element_or_list}
|
||||
end
|
||||
|
||||
-- normalize "short form" viewscreen names to "long form"
|
||||
local function normalize_viewscreen_name(vs_name)
|
||||
if vs_name:match('viewscreen_.*st') then return vs_name end
|
||||
return 'viewscreen_' .. vs_name .. 'st'
|
||||
end
|
||||
|
||||
-- reduce "long form" viewscreen names to "short form"
|
||||
local function simplify_viewscreen_name(vs_name)
|
||||
_,_,short_name = vs_name:find('^viewscreen_(.*)st$')
|
||||
if short_name then return short_name end
|
||||
return vs_name
|
||||
end
|
||||
|
||||
local function is_empty(tbl)
|
||||
for _ in pairs(tbl) do
|
||||
return false
|
||||
end
|
||||
return true
|
||||
end
|
||||
|
||||
local function sanitize_pos(pos)
|
||||
local x = math.floor(tonumber(pos.x) or DEFAULT_X_POS)
|
||||
local y = math.floor(tonumber(pos.y) or DEFAULT_Y_POS)
|
||||
-- if someone accidentally uses 0-based instead of 1-based indexing, fix it
|
||||
if x == 0 then x = 1 end
|
||||
if y == 0 then y = 1 end
|
||||
return {x=x, y=y}
|
||||
end
|
||||
|
||||
local function make_frame(pos, old_frame)
|
||||
old_frame = old_frame or {}
|
||||
local frame = {w=old_frame.w, h=old_frame.h}
|
||||
if pos.x < 0 then frame.r = math.abs(pos.x) - 1 else frame.l = pos.x - 1 end
|
||||
if pos.y < 0 then frame.b = math.abs(pos.y) - 1 else frame.t = pos.y - 1 end
|
||||
return frame
|
||||
end
|
||||
|
||||
local function get_screen_rect()
|
||||
local w, h = dfhack.screen.getWindowSize()
|
||||
return gui.ViewRect{rect=gui.mkdims_wh(0, 0, w, h)}
|
||||
end
|
||||
|
||||
-- ------------- --
|
||||
-- CLI functions --
|
||||
-- ------------- --
|
||||
|
||||
local function get_name(name_or_number)
|
||||
local num = tonumber(name_or_number)
|
||||
if num and widget_index[num] then
|
||||
return widget_index[num]
|
||||
end
|
||||
return tostring(name_or_number)
|
||||
end
|
||||
|
||||
local function do_by_names_or_numbers(args, fn)
|
||||
local arglist = normalize_list(args)
|
||||
if #arglist == 0 then
|
||||
dfhack.printerr('please specify a widget name or list number')
|
||||
return
|
||||
end
|
||||
for _,name_or_number in ipairs(arglist) do
|
||||
local name = get_name(name_or_number)
|
||||
local db_entry = widget_db[name]
|
||||
if not db_entry then
|
||||
dfhack.printerr(('widget not found: "%s"'):format(name))
|
||||
else
|
||||
fn(name, db_entry)
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
local function do_enable(args, quiet, skip_save)
|
||||
local enable_fn = function(name, db_entry)
|
||||
overlay_config[name].enabled = true
|
||||
if db_entry.widget.hotspot then
|
||||
active_hotspot_widgets[name] = db_entry
|
||||
end
|
||||
for _,vs_name in ipairs(normalize_list(db_entry.widget.viewscreens)) do
|
||||
vs_name = normalize_viewscreen_name(vs_name)
|
||||
ensure_key(active_viewscreen_widgets, vs_name)[name] = db_entry
|
||||
end
|
||||
if not quiet then
|
||||
print(('enabled widget %s'):format(name))
|
||||
end
|
||||
end
|
||||
if args[1] == 'all' then
|
||||
for name,db_entry in pairs(widget_db) do
|
||||
if not overlay_config[name].enabled then
|
||||
enable_fn(name, db_entry)
|
||||
end
|
||||
end
|
||||
else
|
||||
do_by_names_or_numbers(args, enable_fn)
|
||||
end
|
||||
if not skip_save then
|
||||
save_config()
|
||||
end
|
||||
end
|
||||
|
||||
local function do_disable(args)
|
||||
local disable_fn = function(name, db_entry)
|
||||
overlay_config[name].enabled = false
|
||||
if db_entry.widget.hotspot then
|
||||
active_hotspot_widgets[name] = nil
|
||||
end
|
||||
for _,vs_name in ipairs(normalize_list(db_entry.widget.viewscreens)) do
|
||||
vs_name = normalize_viewscreen_name(vs_name)
|
||||
ensure_key(active_viewscreen_widgets, vs_name)[name] = nil
|
||||
if is_empty(active_viewscreen_widgets[vs_name]) then
|
||||
active_viewscreen_widgets[vs_name] = nil
|
||||
end
|
||||
end
|
||||
print(('disabled widget %s'):format(name))
|
||||
end
|
||||
if args[1] == 'all' then
|
||||
for name,db_entry in pairs(widget_db) do
|
||||
if overlay_config[name].enabled then
|
||||
disable_fn(name, db_entry)
|
||||
end
|
||||
end
|
||||
else
|
||||
do_by_names_or_numbers(args, disable_fn)
|
||||
end
|
||||
save_config()
|
||||
end
|
||||
|
||||
local function do_list(args)
|
||||
local filter = args and #args > 0
|
||||
local num_filtered = 0
|
||||
for i,name in ipairs(widget_index) do
|
||||
if filter then
|
||||
local passes = false
|
||||
for _,str in ipairs(args) do
|
||||
if name:find(str) then
|
||||
passes = true
|
||||
break
|
||||
end
|
||||
end
|
||||
if not passes then
|
||||
num_filtered = num_filtered + 1
|
||||
goto continue
|
||||
end
|
||||
end
|
||||
local db_entry = widget_db[name]
|
||||
local enabled = overlay_config[name].enabled
|
||||
dfhack.color(enabled and COLOR_LIGHTGREEN or COLOR_YELLOW)
|
||||
dfhack.print(enabled and '[enabled] ' or '[disabled]')
|
||||
dfhack.color()
|
||||
print((' %d) %s'):format(i, name))
|
||||
::continue::
|
||||
end
|
||||
if num_filtered > 0 then
|
||||
print(('(%d widgets filtered out)'):format(num_filtered))
|
||||
end
|
||||
end
|
||||
|
||||
local function load_widget(name, widget_class)
|
||||
local widget = widget_class{name=name}
|
||||
widget_db[name] = {
|
||||
widget=widget,
|
||||
next_update_ms=widget.overlay_onupdate and 0 or math.huge,
|
||||
}
|
||||
if not overlay_config[name] then overlay_config[name] = {} end
|
||||
local config = overlay_config[name]
|
||||
config.pos = sanitize_pos(config.pos or widget.default_pos)
|
||||
widget.frame = make_frame(config.pos, widget.frame)
|
||||
if config.enabled then
|
||||
do_enable(name, true, true)
|
||||
else
|
||||
config.enabled = false
|
||||
end
|
||||
end
|
||||
|
||||
local function load_widgets(env_prefix, provider, env_fn)
|
||||
local env_name = env_prefix .. provider
|
||||
local ok, provider_env = pcall(env_fn, env_name)
|
||||
if not ok or not provider_env[OVERLAY_WIDGETS_VAR] then return end
|
||||
local overlay_widgets = provider_env[OVERLAY_WIDGETS_VAR]
|
||||
if type(overlay_widgets) ~= 'table' then
|
||||
dfhack.printerr(
|
||||
('error loading overlay widgets from "%s": %s map is malformed')
|
||||
:format(env_name, OVERLAY_WIDGETS_VAR))
|
||||
return
|
||||
end
|
||||
for widget_name,widget_class in pairs(overlay_widgets) do
|
||||
local name = provider .. '.' .. widget_name
|
||||
if not safecall(load_widget, name, widget_class) then
|
||||
dfhack.printerr(('error loading overlay widget "%s"'):format(name))
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
-- called directly from cpp on plugin enable
|
||||
function reload()
|
||||
reset()
|
||||
|
||||
for _,plugin in ipairs(dfhack.internal.listPlugins()) do
|
||||
load_widgets('plugins.', plugin, require)
|
||||
end
|
||||
for _,script_path in ipairs(dfhack.internal.getScriptPaths()) do
|
||||
local files = dfhack.filesystem.listdir_recursive(
|
||||
script_path, nil, false)
|
||||
if not files then goto skip_path end
|
||||
for _,f in ipairs(files) do
|
||||
if not f.isdir and
|
||||
f.path:endswith('.lua') and
|
||||
not f.path:startswith('test/') and
|
||||
not f.path:startswith('internal/') then
|
||||
local script_name = f.path:sub(1, #f.path - 4) -- remove '.lua'
|
||||
load_widgets('', script_name, reqscript)
|
||||
end
|
||||
end
|
||||
::skip_path::
|
||||
end
|
||||
|
||||
for name in pairs(widget_db) do
|
||||
table.insert(widget_index, name)
|
||||
end
|
||||
table.sort(widget_index)
|
||||
|
||||
reposition_widgets()
|
||||
end
|
||||
|
||||
local function dump_widget_config(name, widget)
|
||||
local pos = overlay_config[name].pos
|
||||
print(('widget %s is positioned at x=%d, y=%d'):format(name, pos.x, pos.y))
|
||||
local viewscreens = normalize_list(widget.viewscreens)
|
||||
if #viewscreens > 0 then
|
||||
print(' it will be attached to the following viewscreens:')
|
||||
for _,vs in ipairs(viewscreens) do
|
||||
print((' %s'):format(simplify_viewscreen_name(vs)))
|
||||
end
|
||||
end
|
||||
if widget.hotspot then
|
||||
print(' it will act as a hotspot on all screens')
|
||||
end
|
||||
end
|
||||
|
||||
local function do_position(args)
|
||||
local name_or_number, x, y = table.unpack(args)
|
||||
local name = get_name(name_or_number)
|
||||
if not widget_db[name] then
|
||||
if not name_or_number then
|
||||
dfhack.printerr('please specify a widget name or list number')
|
||||
else
|
||||
dfhack.printerr(('widget not found: "%s"'):format(name))
|
||||
end
|
||||
return
|
||||
end
|
||||
local widget = widget_db[name].widget
|
||||
local pos
|
||||
if x == 'default' then
|
||||
pos = sanitize_pos(widget.default_pos)
|
||||
else
|
||||
x, y = tonumber(x), tonumber(y)
|
||||
if not x or not y then
|
||||
dump_widget_config(name, widget)
|
||||
return
|
||||
end
|
||||
pos = sanitize_pos{x=x, y=y}
|
||||
end
|
||||
overlay_config[name].pos = pos
|
||||
widget.frame = make_frame(pos, widget.frame)
|
||||
widget:updateLayout(get_screen_rect())
|
||||
save_config()
|
||||
print(('repositioned widget %s to x=%d, y=%d'):format(name, pos.x, pos.y))
|
||||
end
|
||||
|
||||
-- note that the widget does not have to be enabled to be triggered
|
||||
local function do_trigger(args)
|
||||
if triggered_screen_has_lock() then
|
||||
dfhack.printerr(('cannot trigger widget; widget "%s" is already active')
|
||||
:format(active_triggered_widget))
|
||||
return
|
||||
end
|
||||
do_by_names_or_numbers(args[1], function(name, db_entry)
|
||||
local widget = db_entry.widget
|
||||
if widget.overlay_trigger then
|
||||
active_triggered_screen = widget:overlay_trigger()
|
||||
if active_triggered_screen then
|
||||
active_triggered_widget = name
|
||||
end
|
||||
print(('triggered widget %s'):format(name))
|
||||
end
|
||||
end)
|
||||
end
|
||||
|
||||
local command_fns = {
|
||||
enable=do_enable,
|
||||
disable=do_disable,
|
||||
list=do_list,
|
||||
position=do_position,
|
||||
trigger=do_trigger,
|
||||
}
|
||||
|
||||
local HELP_ARGS = utils.invert{'help', '--help', '-h'}
|
||||
|
||||
function overlay_command(args)
|
||||
local command = table.remove(args, 1) or 'help'
|
||||
if HELP_ARGS[command] or not command_fns[command] then return false end
|
||||
command_fns[command](args)
|
||||
return true
|
||||
end
|
||||
|
||||
-- ---------------- --
|
||||
-- event management --
|
||||
-- ---------------- --
|
||||
|
||||
local function detect_frame_change(widget, fn)
|
||||
local frame = widget.frame
|
||||
local w, h = frame.w, frame.h
|
||||
local ret = fn()
|
||||
if w ~= frame.w or h ~= frame.h then
|
||||
widget:updateLayout()
|
||||
end
|
||||
return ret
|
||||
end
|
||||
|
||||
local function get_next_onupdate_timestamp(now_ms, widget)
|
||||
local freq_s = widget.overlay_onupdate_max_freq_seconds
|
||||
if freq_s == 0 then
|
||||
return now_ms
|
||||
end
|
||||
local freq_ms = math.floor(freq_s * 1000)
|
||||
local jitter = math.random(0, freq_ms // 8) -- up to ~12% jitter
|
||||
return now_ms + freq_ms - jitter
|
||||
end
|
||||
|
||||
-- reduces the next call by a small random amount to introduce jitter into the
|
||||
-- widget processing timings
|
||||
local function do_update(name, db_entry, now_ms, vs)
|
||||
if db_entry.next_update_ms > now_ms then return end
|
||||
local w = db_entry.widget
|
||||
db_entry.next_update_ms = get_next_onupdate_timestamp(now_ms, w)
|
||||
if detect_frame_change(w, function() return w:overlay_onupdate(vs) end) then
|
||||
active_triggered_screen = w:overlay_trigger()
|
||||
if active_triggered_screen then
|
||||
active_triggered_widget = name
|
||||
return true
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
function update_hotspot_widgets()
|
||||
if triggered_screen_has_lock() then return end
|
||||
local now_ms = dfhack.getTickCount()
|
||||
for name,db_entry in pairs(active_hotspot_widgets) do
|
||||
if do_update(name, db_entry, now_ms) then return end
|
||||
end
|
||||
end
|
||||
|
||||
-- not subject to trigger lock since these widgets are already filtered by
|
||||
-- viewscreen
|
||||
function update_viewscreen_widgets(vs_name, vs)
|
||||
local vs_widgets = active_viewscreen_widgets[vs_name]
|
||||
if not vs_widgets then return end
|
||||
local now_ms = dfhack.getTickCount()
|
||||
for name,db_entry in pairs(vs_widgets) do
|
||||
if do_update(name, db_entry, now_ms, vs) then return end
|
||||
end
|
||||
end
|
||||
|
||||
function feed_viewscreen_widgets(vs_name, keys)
|
||||
local vs_widgets = active_viewscreen_widgets[vs_name]
|
||||
if not vs_widgets then return false end
|
||||
for _,db_entry in pairs(vs_widgets) do
|
||||
local w = db_entry.widget
|
||||
if detect_frame_change(w, function() return w:onInput(keys) end) then
|
||||
return true
|
||||
end
|
||||
end
|
||||
return false
|
||||
end
|
||||
|
||||
function render_viewscreen_widgets(vs_name)
|
||||
local vs_widgets = active_viewscreen_widgets[vs_name]
|
||||
if not vs_widgets then return false end
|
||||
local dc = gui.Painter.new()
|
||||
for _,db_entry in pairs(vs_widgets) do
|
||||
local w = db_entry.widget
|
||||
detect_frame_change(w, function() w:render(dc) end)
|
||||
end
|
||||
end
|
||||
|
||||
-- called when the DF window is resized
|
||||
function reposition_widgets()
|
||||
local sr = get_screen_rect()
|
||||
for _,db_entry in pairs(widget_db) do
|
||||
db_entry.widget:updateLayout(sr)
|
||||
end
|
||||
end
|
||||
|
||||
-- ------------------------------------------------- --
|
||||
-- OverlayWidget (base class of all overlay widgets) --
|
||||
-- ------------------------------------------------- --
|
||||
|
||||
OverlayWidget = defclass(OverlayWidget, widgets.Widget)
|
||||
OverlayWidget.ATTRS{
|
||||
name=DEFAULT_NIL, -- this is set by the framework to the widget name
|
||||
default_pos={x=DEFAULT_X_POS, y=DEFAULT_Y_POS}, -- 1-based widget screen pos
|
||||
hotspot=false, -- whether to call overlay_onupdate on all screens
|
||||
viewscreens={}, -- override with associated viewscreen or list of viewscrens
|
||||
overlay_onupdate_max_freq_seconds=5, -- throttle calls to overlay_onupdate
|
||||
}
|
||||
|
||||
function OverlayWidget:init()
|
||||
if self.overlay_onupdate_max_freq_seconds < 0 then
|
||||
error(('overlay_onupdate_max_freq_seconds must be >= 0: %s')
|
||||
:format(tostring(self.overlay_onupdate_max_freq_seconds)))
|
||||
end
|
||||
|
||||
-- set defaults for frame. the widget is expected to keep these up to date
|
||||
-- when display contents change so the widget position can shift if the
|
||||
-- frame is relative to the right or bottom edges.
|
||||
self.frame = self.frame or {}
|
||||
self.frame.w = self.frame.w or 5
|
||||
self.frame.h = self.frame.h or 1
|
||||
end
|
||||
|
||||
return _ENV
|
||||
Loading…
Reference in New Issue