Petitions Overlay

petitioners.lua

@@ -0,0 +1,232 @@
+--@ module = true
+-- This script defines a DFHack overlay widget that augments the Petitioners screen
+-- by showing additional information about the units involved in a selected petition.
+
+local gui = require('gui')              -- GUI helpers (pens, frames, layout)
+local overlay = require('plugins.overlay') -- Overlay framework (OverlayWidget base)
+local widgets = require('gui.widgets')  -- Standard DFHack UI widgets (List, Panel, Label, etc.)
+local utils = require('utils')          -- Misc DFHack utilities
+
+-- -------------------
+-- Utility functions
+-- -------------------
+
+-- Determines which petition row is currently selected in the vanilla UI
+-- by comparing screen texture positions. This is a heuristic that tracks
+-- which row's screen texpos matches the initially captured value.
+function getActivePetitionRow(self)
+    local starty = 6                     -- Y offset where the first petition row starts
+    local steps = 3                      -- Vertical spacing between petition rows
+    local listlength = #df.global.plotinfo.petitions -- Number of petitions currently listed
+    local gps = df.global.gps            -- Global screen state (texture positions, dimensions)
+    if not gps then 
+        return nil                       -- If GPS is unavailable, we cannot determine selection
+    end
+
+    -- Capture the initially selected texpos once. This serves as the reference
+    -- value that identifies the currently highlighted row.
+    if self.tocheck == nil or self.tocheck == 0 then
+        self.tocheck = gps.screentexpos_lower[6 * gps.dimy + starty] or 0
+        --print("tocheck " .. self.tocheck)
+    end
+
+    -- Iterate over all visible petition rows and compare their texpos
+    -- against the captured reference. The matching row index is returned.
+    for i = 0, listlength - 1 do
+        local y = starty + i * steps
+        local idx = (6 * gps.dimy) + y
+        local tex = gps.screentexpos_lower[idx] or 0
+
+        if tex == self.tocheck then
+            return i                     -- Found the active petition row
+        end
+    end
+    return nil
+end
+
+-- Helper that returns a localized caste/profession name for a unit
+local function get_caste_name(race, caste, profession)
+    return dfhack.units.getCasteProfessionName(race, caste, profession)
+end
+
+-- -------------------
+-- PetitionersOverlay
+-- -------------------
+
+-- Define a new overlay widget that attaches to the Petitioners screen
+PetitionersOverlay = defclass(PetitionersOverlay, overlay.OverlayWidget)
+PetitionersOverlay.ATTRS{
+    desc="Add information about the petitioners to the Petition screen", -- Short description
+    default_enabled=true,          -- Overlay is enabled by default
+    version=3,                     -- Config version for migration/reset
+    viewscreens={'dwarfmode/Petitions'}, -- Only active on the Petitions screen
+    frame_background=gui.CLEAR_PEN, -- Transparent background
+}
+
+-- Initialization runs once when the widget is created
+function PetitionersOverlay:init()
+    self.firstrender = true         -- Flag to perform one-time setup on first render
+    self.tocheck = nil              -- Stored texpos reference for row detection
+    self.last_petitions_size = #df.global.plotinfo.petitions -- Track petition count
+    self.last_selected_petition = 0 -- Track currently selected petition index
+    self.frame = { l=0, t=0, r=0, b=0 } -- Base frame; child widgets define actual layout
+
+    -- Define child views for this overlay
+    self:addviews{
+        -- List showing petitioners and summary info
+        widgets.List{
+            frame={l=60, r=28, t=30, b=14}, -- Position relative to screen edges
+            frame_style=gui.FRAME_INTERIOR,
+            view_id='list',               -- Identifier for lookup via self.subviews
+            on_select=self:callback('onZoom'), -- Called when selection changes
+        },
+        -- Footer panel containing extended description text
+        widgets.Panel{
+            view_id='footer',
+            frame={l=6, r=28, b=3, h=10},
+            frame_style=gui.FRAME_INTERIOR,
+            subviews={
+                -- Wrapped label that shows detailed skill info for the selected unit
+                widgets.WrappedLabel{
+                    frame={l=0, h=7},
+                    view_id='desc',
+                    auto_height=false,
+                    -- Text is computed dynamically based on the current list selection
+                    text_to_wrap=function()
+                        local _, choice = self.subviews.list:getSelected()
+                        return choice and choice.text_long or ''
+                    end,
+                },
+            },
+        },
+    }
+end
+
+-- Builds or refreshes the list contents based on the currently selected petition
+function PetitionersOverlay:initListChoices()
+    local choices = {}               -- Accumulates entries for the List widget
+
+    local agmt_id = df.global.plotinfo.petitions[self.last_selected_petition]
+    if not agmt_id then
+        --print("no id for selected petition or selected petition invalid")              -- No petition selected
+        return
+    end
+    local agmt = df.global.world.agreements.all[agmt_id]
+    if not agmt then 
+        --print("error no petition found")
+        return
+    end
+
+    local party0 = agmt.parties[0]   -- First party involved in the agreement
+
+    -- Collect all historical figure IDs associated with this petition
+    local histfig_ids = {}
+    if #party0.histfig_ids > 0 then
+        -- Direct histfig references
+        for _, hf_id in ipairs(party0.histfig_ids) do histfig_ids[hf_id] = true end
+    elseif #party0.entity_ids > 0 then
+        -- Indirect references via an entity
+        local ent = df.global.world.entities.all[party0.entity_ids[0]]
+        if ent then
+            for _, hf in ipairs(ent.hist_figures) do histfig_ids[hf.id] = true end
+        end
+    end
+
+    -- Iterate over collected historical figures and resolve them to active units
+    for hf_id, _ in pairs(histfig_ids) do
+        local u = nil
+        for _, unit in ipairs(df.global.world.units.active) do
+            if unit.hist_figure_id == hf_id then
+                u = unit                -- Found the active unit for this histfig
+                break
+            end
+        end
+
+        if u then
+            -- Resolve and localize unit names
+            local u_name = dfhack.translation.translateName(u.name)
+            local trans_name = dfhack.translation.translateName(u.name, true, true)
+            local u_caste = get_caste_name(u.race, u.caste, u.profession)
+            local u_race = dfhack.units.getRaceName(u) == "DWARF" and " (DWARF)" or ""
+
+            local info_text = ""        -- Long description text (skills)
+
+            -- Collect skills with rating > 0
+            if u.status.current_soul.skills then
+                local skills_copy = {}
+                for _, skill in ipairs(u.status.current_soul.skills) do
+                    if skill.rating > 0 then
+                        table.insert(skills_copy, skill)
+                    end
+                end
+
+                -- Sort skills by rating, highest first
+                table.sort(skills_copy, function(a, b)
+                    return a.rating > b.rating
+                end)
+
+                -- Append skill names and ratings into a single string
+                for _, skill in ipairs(skills_copy) do
+                    info_text = info_text .. df.job_skill[skill.id] .. ": " .. skill.rating .. "  "
+                end
+            end
+
+            if info_text == "" then info_text = "None" end
+
+            -- Short text shown in the list, long text shown in the footer
+            local text = u_name .. " (" .. trans_name .. ") - " .. u_caste .. u_race
+            local text_long = info_text
+
+            table.insert(choices, {text=text, text_long=text_long, data={unit=u}})
+        end
+    end
+
+    -- Apply the built choices to the List widget
+    self.subviews.list:setChoices(choices)
+end
+
+-- Checks whether the petition list size or selected petition has changed
+-- and refreshes the list contents if necessary
+function PetitionersOverlay:ListChangeCheck()
+    local current_size = #df.global.plotinfo.petitions
+    if current_size < 1 then 
+        self.subviews.list:setChoices({})
+        return 
+    end
+    local current_selected = getActivePetitionRow(self)
+    if current_selected == nil then return end
+    if current_size ~= self.last_petitions_size or current_selected ~= self.last_selected_petition then
+        self.last_petitions_size = current_size
+        self.last_selected_petition = current_selected
+        --print("Petitions list or selection changed: " .. current_size)
+        self:initListChoices()
+    end
+end
+
+-- Called every render frame while the overlay is visible
+function PetitionersOverlay:onRenderFrame(dc, rect)
+    -- Perform one-time initialization on the first render
+    if self.firstrender == nil or self.firstrender then
+        --print("first render" )
+        self:initListChoices()
+        self.firstrender = false
+    end
+
+    -- Continuously monitor for petition list or selection changes
+    self:ListChangeCheck()
+end
+
+-- Called when the user selects an entry in the list
+-- Zooms the camera to the selected unit and updates layout if needed
+function PetitionersOverlay:onZoom()
+    local _, choice = self.subviews.list:getSelected()
+    if not choice then return end
+    local unit = choice.data.unit
+    local target = xyz2pos(dfhack.units.getPosition(unit))
+    dfhack.gui.revealInDwarfmodeMap(target, true, true)
+    local desc = self.subviews.desc
+    if desc.frame_body then desc:updateLayout() end
+end
+
+-- Register this overlay widget so DFHack can discover and load it
+OVERLAY_WIDGETS = {PetitionersOverlay=PetitionersOverlay}