Blizzard UI Systems Deep Dive¶

-- Basic cooldown display
local cooldown = CreateFrame("Cooldown", nil, parentFrame, "CooldownFrameTemplate")
cooldown:SetAllPoints(parentFrame)

-- Pre-12.0 way (still works outside restricted contexts)
cooldown:SetCooldown(startTime, duration)

-- Read back cooldown times
local start, duration = cooldown:GetCooldownTimes()

-- Create a reusable Duration Object
local duration = C_DurationUtil.CreateDuration()

-- Three ways to populate it:
duration:SetTimeSpan(startTime, endTime)
duration:SetTimeFromStart(startTime, durationSecs)
duration:SetTimeFromEnd(endTime, durationSecs)

-- Pass it straight to the cooldown widget — no math needed
cooldownFrame:SetCooldownFromDurationObject(duration)

-- 11.0+ standard API (returns SpellCooldownInfo table)
local info = C_Spell.GetSpellCooldown(spellID)
-- info.startTime, info.duration, info.isEnabled, info.modRate

-- GCD check: use spell ID 61304
local gcdInfo = C_Spell.GetSpellCooldown(61304)

local addonName, ns = ...

-- Reusable Duration Object (avoid creating per-frame)
local durationObj = C_DurationUtil.CreateDuration()

local function UpdateCooldownDisplay(cooldownFrame, spellID)
    -- Try the Duration API first (Secret Values-safe)
    local duration = C_Spell.GetSpellCooldownDuration(spellID)
    if duration then
        cooldownFrame:SetCooldownFromDurationObject(duration)
        return
    end

    -- Fallback for non-restricted contexts
    local info = C_Spell.GetSpellCooldown(spellID)
    if info and info.duration > 0 then
        cooldownFrame:SetCooldown(info.startTime, info.duration, info.modRate)
    else
        cooldownFrame:Clear()
    end
end

-- React when Edit Mode opens/closes
EventRegistry:RegisterCallback("EditMode.Enter", function()
    -- Player entered Edit Mode — show configuration UI, unlock frames, etc.
    MyAddon:EnterEditMode()
end)

EventRegistry:RegisterCallback("EditMode.Exit", function()
    -- Player left Edit Mode — lock frames, save positions
    MyAddon:ExitEditMode()
end)

-- Vertical layout: auto-stacking controls (recommended for most addons)
local category = Settings.RegisterVerticalLayoutCategory("My AddOn")

-- Subcategory under a parent
local sub = Settings.RegisterVerticalLayoutSubcategory(category, "Advanced")

-- Canvas layout: fully custom frame
local frame = CreateFrame("Frame")
local category = Settings.RegisterCanvasLayoutCategory(frame, "My AddOn")

-- Register in the AddOns tab
Settings.RegisterAddOnCategory(category)

-- ## SavedVariables: MyAddOn_DB
MyAddOn_DB = {}  -- populated by WoW from SavedVariables

local category = Settings.RegisterVerticalLayoutCategory("My AddOn")

-- Checkbox
do
    local setting = Settings.RegisterAddOnSetting(category,
        "MyAddOn_Toggle",  -- unique variable name
        "toggle",          -- key in SavedVariables table
        MyAddOn_DB,        -- the SavedVariables table
        type(false),       -- variableType ("boolean")
        "Enable Feature",  -- display name
        false              -- default value
    )
    Settings.CreateCheckbox(category, setting, "Enables the main feature.")
end

-- Slider
do
    local setting = Settings.RegisterAddOnSetting(category,
        "MyAddOn_Scale", "scale", MyAddOn_DB,
        type(1), "UI Scale", 100
    )
    local options = Settings.CreateSliderOptions(50, 200, 5)
    options:SetLabelFormatter(MinimalSliderWithSteppersMixin.Label.Right)
    Settings.CreateSlider(category, setting, options, "Adjust scale percentage.")
end

-- Dropdown
do
    local function GetOptions()
        local container = Settings.CreateControlTextContainer()
        container:Add(1, "Small")
        container:Add(2, "Medium")
        container:Add(3, "Large")
        return container:GetData()
    end
    local setting = Settings.RegisterAddOnSetting(category,
        "MyAddOn_Size", "size", MyAddOn_DB,
        type(1), "Frame Size", 2
    )
    Settings.CreateDropdown(category, setting, GetOptions, "Select frame size.")
end

Settings.RegisterAddOnCategory(category)

-- Read
local value = Settings.GetValue("MyAddOn_Toggle")

-- Write
Settings.SetValue("MyAddOn_Toggle", true)

-- Get the setting object for callbacks
local setting = Settings.GetSetting("MyAddOn_Toggle")
setting:SetValueChangedCallback(function(setting, value)
    print("Toggle changed to:", value)
end)

-- Open the settings panel to your category
Settings.OpenToCategory(category:GetID())

local frame = CreateFrame("Frame")
frame:SetSize(600, 400)

-- These three functions are REQUIRED for Canvas layouts
function frame.OnCommit()
    -- Called when the player clicks "Okay" or "Apply"
    -- Save your settings here
end

function frame.OnDefault()
    -- Called when the player clicks "Defaults"
    -- Reset your settings here
end

function frame.OnRefresh()
    -- Called when the panel is shown
    -- Update your controls to match current settings
end

local category = Settings.RegisterCanvasLayoutCategory(frame, "My AddOn")
Settings.RegisterAddOnCategory(category)

-- Click handler (TOC-registered)
function MyAddon_OnCompartmentClick(addonName, buttonName)
    if buttonName == "LeftButton" then
        Settings.OpenToCategory(MyAddon.categoryID)
    elseif buttonName == "RightButton" then
        MyAddon:ToggleMainWindow()
    end
end

-- Tooltip on hover
function MyAddon_OnCompartmentEnter(addonName, menuButtonFrame)
    GameTooltip:SetOwner(menuButtonFrame, "ANCHOR_LEFT")
    GameTooltip:SetText("My Addon")
    GameTooltip:AddLine("Left-click: Settings", 1, 1, 1)
    GameTooltip:AddLine("Right-click: Toggle window", 1, 1, 1)
    GameTooltip:Show()
end

function MyAddon_OnCompartmentLeave(addonName, menuButtonFrame)
    GameTooltip:Hide()
end

AddonCompartmentFrame:RegisterAddon({
    text = "My Addon",
    icon = "Interface\\Icons\\INV_Misc_QuestionMark",
    func = function(button, menuInputData, menu)
        local mouseButton = menuInputData.buttonName
        -- Handle click
    end,
    funcOnEnter = function(button, menuInputData, menu)
        GameTooltip:SetOwner(button, "ANCHOR_LEFT")
        GameTooltip:SetText("My Addon")
        GameTooltip:Show()
    end,
    funcOnLeave = function(button, menuInputData, menu)
        GameTooltip:Hide()
    end,
    notCheckable = true,
})

-- 1. Create the visual components
local scrollBox = CreateFrame("Frame", nil, parentFrame, "WowScrollBoxList")
scrollBox:SetPoint("TOPLEFT", 4, -4)
scrollBox:SetPoint("BOTTOMRIGHT", -24, 4)

local scrollBar = CreateFrame("EventFrame", nil, parentFrame, "MinimalScrollBar")
scrollBar:SetPoint("TOPLEFT", scrollBox, "TOPRIGHT", 4, 0)
scrollBar:SetPoint("BOTTOMLEFT", scrollBox, "BOTTOMRIGHT", 4, 0)

-- 2. Configure the ScrollView with fixed row height
local scrollView = CreateScrollBoxListLinearView()
scrollView:SetElementExtent(24)

-- 3. Define how each row renders
scrollView:SetElementInitializer("UIPanelButtonTemplate", function(button, data)
    button:SetText(data.name)
    button:SetScript("OnClick", function()
        print("Clicked:", data.name)
    end)
end)

-- 4. Wire everything together
ScrollUtil.InitScrollBoxListWithScrollBar(scrollBox, scrollBar, scrollView)

-- 5. Populate with data
local dataProvider = CreateDataProvider()
for i = 1, 100 do
    dataProvider:Insert({ name = "Item " .. i })
end
scrollBox:SetDataProvider(dataProvider)

scrollView:SetElementInitializer("MyItemTemplate", function(frame, data)
    frame.Name:SetText(data.name)
    frame.Icon:SetTexture(data.icon)
    frame:SetScript("OnEnter", function(self)
        GameTooltip:SetOwner(self, "ANCHOR_RIGHT")
        GameTooltip:SetText(data.tooltip)
        GameTooltip:Show()
    end)
    frame:SetScript("OnLeave", GameTooltip_Hide)
end)

scrollView:SetElementResetter(function(frame, data)
    frame:SetScript("OnEnter", nil)
    frame:SetScript("OnLeave", nil)
end)

scrollView:SetElementExtentCalculator(function(dataIndex, data)
    if data.isHeader then return 32 end
    return 20
end)

scrollView:SetElementFactory(function(factory, node)
    local data = node:GetData()
    factory(data.Template, function(frame, node)
        frame:Init(node)
    end)
end)

dataProvider:Insert({ name = "New Item" })
dataProvider:InsertTable({ {name = "A"}, {name = "B"} })
dataProvider:RemoveIndex(3)
dataProvider:RemoveByPredicate(function(d) return d.name == "B" end)
dataProvider:Flush()  -- clear all data
dataProvider:SetSortComparator(function(a, b) return a.name < b.name end)
dataProvider:Sort()
dataProvider:GetSize()
dataProvider:ForEach(function(data) print(data.name) end)
dataProvider:FindByPredicate(function(d) return d.name == "A" end)

-- Keeps the scroll position when replacing data
scrollBox:SetDataProvider(dataProvider, ScrollBoxConstants.RetainScrollPosition)

local selectionBehavior = ScrollUtil.AddSelectionBehavior(scrollBox)

selectionBehavior:RegisterCallback(
    SelectionBehaviorMixin.Event.OnSelectionChanged,
    function(self, elementData, selected)
        local button = scrollBox:FindFrame(elementData)
        if button then
            if selected then
                button:SetText("[" .. elementData.name .. "]")
            else
                button:SetText(elementData.name)
            end
        end
    end
)

local AllData = {}
for i = 1, 100 do
    tinsert(AllData, { name = "Item " .. i })
end

local dataProvider = CreateDataProvider(AllData)
scrollBox:SetDataProvider(dataProvider)

searchBox:HookScript("OnTextChanged", function(editBox)
    local query = editBox:GetText():lower()
    local filtered = {}
    for _, entry in ipairs(AllData) do
        if entry.name:lower():find(query, 1, true) then
            tinsert(filtered, entry)
        end
    end
    scrollBox:SetDataProvider(CreateDataProvider(filtered))
end)

local treeView = CreateScrollBoxListTreeListView()
local treeDataProvider = CreateTreeDataProvider()

treeView:SetElementInitializer("UIPanelButtonTemplate", function(button, node)
    local data = node:GetData()
    local depth = node:GetDepth()
    button:SetText(string.rep("  ", depth) .. data.name)
    button:SetScript("OnClick", function() node:ToggleCollapsed() end)
end)

ScrollUtil.InitScrollBoxListWithScrollBar(scrollBox, scrollBar, treeView)
scrollBox:SetDataProvider(treeDataProvider)

local parent = treeDataProvider:Insert({ name = "Category A" })
parent:Insert({ name = "Sub-item 1" })
parent:Insert({ name = "Sub-item 2" })

-- React when Blizzard populates a ScrollBox
hooksecurefunc(someBlizzardScrollBox, "SetDataProvider", function(self, dp)
    -- Hook the DataProvider to track insertions
    hooksecurefunc(dp, "Insert", function(dataProvider, data)
        -- React to new data entries
    end)
end)

-- Old (pre-12.0): one cooldown frame
local cd = actionButton.cooldown

-- New (12.0): three cooldown frames
local cd     = actionButton.cooldown
local charge = actionButton.chargeCooldown
local loc    = actionButton.lossOfControlCooldown

-- Check if a specific value is secret
if issecretvalue(someValue) then
    -- Can't read this right now — pass it to a widget or bail
    return
end

-- Check if restrictions are currently active
if C_Secrets.HasSecretRestrictions() then
    -- We're in restricted content
end

-- Specific restriction checks
C_Secrets.ShouldSpellCooldownBeSecret()    -- cooldown restriction
C_Secrets.ShouldAurasBeSecret()            -- aura restriction
C_Secrets.ShouldUnitAuraInstanceBeSecret() -- unit aura restriction

-- Check if a widget contains secret values
frame:HasSecretValues()
frame:HasSecretAspect()

-- Prevent a widget from accepting secret values (will error instead)
frame:SetPreventSecretValues()

-- WRONG: trying to read and branch on secret values
local info = C_Spell.GetSpellCooldown(spellID)
if info.duration > 0 then  -- ERROR: can't compare secret value
    cooldown:SetCooldown(info.startTime, info.duration)
end

-- RIGHT: use Duration Objects that pass through to widgets
local duration = C_Spell.GetSpellCooldownDuration(spellID)
if duration then
    cooldown:SetCooldownFromDurationObject(duration)
end

-- Instead of: if someSecretBool then region:SetAlpha(1) else region:SetAlpha(0) end
region:SetAlphaFromBoolean(someSecretBool)

-- Instead of: if someSecretBool then region:SetVertexColor(1,0,0) else ... end
region:SetVertexColorFromBoolean(someSecretColor)