Custom

Contents

• Overview
• Custom Control
• Custom Page
• Custom Page Counts
• Search Entries
• Lifecycle

Overview

Custom hosting lets a host addon render specialized UI inside LibSettingsDesigner while the library still owns navigation, search, sizing, density, theme refresh, and page lifecycle.

Use this for editors that are not simple settings rows, such as rule builders, record tables, previews, or import tools. Keep host-addon logic in the host addon; the library only provides the parent frame and lifecycle.

Custom Control

app:RegisterControl("tools.editor", {
  id = "ruleBuilder",
  type = "custom",
  label = "Rule Builder",
  description = "Create and edit rule-based filters.",
  rowHeight = 420,
  render = function(parent, app, control, state, focusID)
    return MyAddon.RuleBuilder:Render(parent, state, focusID)
  end,
  refresh = function(handle, app, control, state)
    if handle and handle.Refresh then handle:Refresh() end
  end,
  release = function(handle, app, control, state)
    if handle and handle.Release then handle:Release() end
  end,
})

getHeight(app, control, state) may be used instead of fixed rowHeight when the control height is dynamic.

Custom Page

app:RegisterPage({
  id = "tools.rule-builder",
  category = "tools",
  title = "Rule Builder",
  layout = "custom",
  getHeight = function(app, page, state)
    return 560
  end,
  render = function(parent, app, page, state, focusID)
    return MyAddon.RuleBuilder:Render(parent, state, focusID)
  end,
  release = function(handle, app, page, state)
    if handle and handle.Release then handle:Release() end
  end,
})

Custom pages still get the standard page header, side panel, scroll frame, and window controls.

Custom Page Counts

Custom pages do not automatically expose the host-rendered checkboxes, table cells, or nested controls to LibSettingsDesigner. If the page card should show a meaningful count instead of 0 settings, provide count fields or callbacks:

app:RegisterPage({
  id = "auras.ignore-matrix",
  category = "auras",
  title = "Aura Ignore Matrix",
  layout = "custom",
  getSettingCount = function(app, page)
    return MyAddon.AuraMatrix:GetCellCount()
  end,
  getCustomizedCount = function(app, page)
    return MyAddon.AuraMatrix:GetChangedCellCount()
  end,
  render = function(parent, app, page, state)
    return MyAddon.AuraMatrix:Render(parent, state)
  end,
})

Static values are also supported:

settingCount = 25,
customizedCount = 3,

Aliases are accepted for host wrappers: settingsCount, controlCount, getSettingsCount, getControlCount, changedCount, and getChangedCount.

Search Entries

Custom pages can provide searchable child entries:

app:RegisterPage({
  id = "tools.rule-builder",
  category = "tools",
  title = "Rule Builder",
  layout = "custom",
  searchEntries = {
    { id = "rule.create", label = "Create Rule", keywords = { "filter", "new" }, focusID = "create" },
  },
  render = function(parent, app, page, state, focusID)
    return MyAddon.RuleBuilder:Render(parent, state, focusID)
  end,
})

Selecting a search entry opens the page and passes focusID to render.

Lifecycle

The custom render callback receives:

render(parent, app, owner, state, focusID)

The returned handle is stored until the content is re-rendered or the settings window is hidden. Cleanup order:

1. owner.release(handle, app, owner, state) when supplied.
2. handle:Release(app, owner, state) when the handle provides it.

Use state:RequestLayout() after host content changes height or needs a full layout recalculation.