Merge pull request #5316 from myk002/myk_overlay_toggle_fns

[overlay] add enable/disable hooks for widgets

docs/changelog.txt

@@ -87,6 +87,7 @@ Template for new versions:
 - ``gui.dwarfmode``: adventure mode cursor now supported in ``getCursorPos``, ``setCursorPos``, and ``clearCursorPos`` funcitons
 - ``dfhack.buildings.checkFreeTiles``: now replaces the extents parameter for a building pointer
 - ``overlay.isOverlayEnabled``: new API for querying whether a given overlay is enabled
+- ``overlay``: widgets can now declare ``overlay_onenable`` and ``overlay_ondisable`` functions to hook enable/disable
 
 ## Removed
 

docs/dev/overlay-dev-guide.rst

@@ -86,6 +86,11 @@ beyond your everyday `widgets.Widget <widget>`:
         end
 
     This allows for dynamic updates to UI overlays directly from the CLI.
+- If an ``overlay_onenable()`` function is defined, it is called when the
+    overlay is enabled (including when the persisted state is reloaded at DF
+    startup).
+- If an ``overlay_ondisable()`` function is defined, it is called when the
+    overlay is disabled.
 
 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

plugins/lua/overlay.lua

@@ -171,6 +171,9 @@ local function do_enable(args, quiet, skip_save)
             vs_name = normalize_viewscreen_name(vs_name)
             ensure_key(active_viewscreen_widgets, vs_name)[name] = db_entry
         end
+        if db_entry.widget.overlay_onenable then
+            db_entry.widget.overlay_onenable()
+        end
         if not quiet then
             print(('enabled widget %s'):format(name))
         end
@@ -202,6 +205,9 @@ local function do_disable(args, quiet)
                 active_viewscreen_widgets[vs_name] = nil
             end
         end
+        if db_entry.widget.overlay_ondisable then
+            db_entry.widget.overlay_ondisable()
+        end
         if not quiet then
             print(('disabled widget %s'):format(name))
         end