add CycleHotkeyLabel:setOption()

docs/changelog.txt

@@ -55,11 +55,12 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - ``widgets.Panel``: new attributes to control window dragging and resizing with mouse or keyboard
 - ``widgets.Window``: Panel subclass with attributes preset for top-level windows
 - ``widgets.CycleHotkeyLabel``: now supports rendering option labels in the color of your choice
+- ``widgets.CycleHotkeyLabel``: new functions ``setOption()`` and ``getOptionPen()``
 - ``widgets.ToggleHotkeyLabel``: now renders the ``On`` option in green text
 - `overlay`: ``OverlayWidget`` now inherits from ``Panel`` instead of ``Widget`` to get all the frame and mouse integration goodies
 - ``dfhack.gui.getDFViewscreen()``: returns the topmost underlying DF viewscreen
 - ``gui.ZScreen``: Screen subclass that implements window raising, multi-viewscreen input handling, and viewscreen event pass-through so the underlying map can be interacted with and dragged around while DFHack screens are visible
-- ``gui.View``: new function: ``view:getMouseFramePos()`` for detecting whether the mouse is within (or over) the exterior frame of a view
+- ``gui.View``: new function ``view:getMouseFramePos()`` for detecting whether the mouse is within (or over) the exterior frame of a view
 
 ## Internals
 

docs/dev/Lua API.rst

@@ -4734,6 +4734,12 @@ The CycleHotkeyLabel widget implements the following methods:
 
     Cycles the selected option and triggers the ``on_change`` callback.
 
+* ``cyclehotkeylabel:setOption(value_or_index, call_on_change)``
+
+    Sets the current option to the option with the specified value or
+    index. If ``call_on_change`` is set to ``true``, then the ``on_change``
+    callback is triggered.
+
 * ``cyclehotkeylabel:getOptionLabel([option_idx])``
 
     Retrieves the option label at the given index, or the label of the
@@ -4744,6 +4750,12 @@ The CycleHotkeyLabel widget implements the following methods:
     Retrieves the option value at the given index, or the value of the
     currently selected option if no index is given.
 
+* ``cyclehotkeylabel:getOptionPen([option_idx])``
+
+    Retrieves the option pen at the given index, or the pen of the currently
+    selected option if no index is given. If an option was defined as just a
+    string, then this function will return ``nil`` for that option.
+
 ToggleHotkeyLabel
 -----------------
 

library/lua/gui/widgets.lua

@@ -1415,22 +1415,7 @@ CycleHotkeyLabel.ATTRS{
 }
 
 function CycleHotkeyLabel:init()
-    -- initialize option_idx
+    self:setOption(self.initial_option)
-    for i in ipairs(self.options) do
-        if self.initial_option == self:getOptionValue(i) then
-            self.option_idx = i
-            break
-        end
-    end
-    if not self.option_idx then
-        if self.options[self.initial_option] then
-            self.option_idx = self.initial_option
-        end
-    end
-    if not self.option_idx then
-        error(('cannot find option with value or index: "%s"')
-              :format(self.initial_option))
-    end
 
     self:setText{
         {key=self.key, key_sep=': ', text=self.label, width=self.label_width,
@@ -1454,6 +1439,31 @@ function CycleHotkeyLabel:cycle()
     end
 end
 
+function CycleHotkeyLabel:setOption(value_or_index, call_on_change)
+    local option_idx = nil
+    for i in ipairs(self.options) do
+        if value_or_index == self:getOptionValue(i) then
+            option_idx = i
+            break
+        end
+    end
+    if not option_idx then
+        if self.options[value_or_index] then
+            option_idx = value_or_index
+        end
+    end
+    if not option_idx then
+        error(('cannot find option with value or index: "%s"')
+              :format(value_or_index))
+    end
+    local old_option_idx = self.option_idx
+    self.option_idx = option_idx
+    if call_on_change and self.on_change then
+        self.on_change(self:getOptionValue(),
+                       self:getOptionValue(old_option_idx))
+    end
+end
+
 local function cyclehotkeylabel_getOptionElem(self, option_idx, key)
     option_idx = option_idx or self.option_idx
     local option = self.options[option_idx]