Merge pull request #4922 from wiktor-obrebski/feat/overlay-trigger-args

Pass CLI arguments  to `overlay_trigger` function

Author: myk002

docs/dev/overlay-dev-guide.rst

@@ -72,6 +72,21 @@ beyond your everyday `widgets.Widget <widget>`:
     screen, but the returned screen can instantiate and configure any new views
     that it wants to. See the `hotkeys` DFHack logo widget for an example.
 
+    The ``overlay_trigger()`` function enables the activation of overlay widgets
+    via the command line interface (CLI) or keybindings.
+    For example, executing ``overlay trigger notes.map_notes add Kitchen``::
+
+        function MyOverlayWidget:overlay_trigger(arg1, arg2)
+            if arg1 == 'add' then
+                -- Add a new note to the map
+                self:addSomething(arg2)
+            elseif arg1 == 'delete' then
+                self:deleteSomething(arg2)
+            end
+        end
+
+    This allows for dynamic updates to UI overlays directly from the CLI.
+
 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

docs/plugins/overlay.rst

@@ -49,6 +49,9 @@ Examples
 ``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`.
+``overlay trigger notes.map_notes add Kitchen``
+    Trigger the `notes` overlay widget so that it shows its new note popup
+    with given title.
 
 Widget position
 ---------------

plugins/lua/overlay.lua

@@ -383,7 +383,11 @@ local function do_trigger(args, quiet)
     do_by_names_or_numbers(args[1], function(name, db_entry)
         local widget = db_entry.widget
         if widget.overlay_trigger then
-            register_trigger_lock_screen(widget:overlay_trigger(), name)
+            register_trigger_lock_screen(
+                widget:overlay_trigger(table.unpack(args, 2)),
+                name
+            )
+
             if not quiet then
                 print(('triggered widget %s'):format(name))
             end