Class ui.panel.Set

Panel set for managing multiple named panels with single selection.

This class is a Panel that holds a set of content panels (by unique name) of which at most one is visible/active at a time. It can be used in combination with a ui.panel.TabStrip.

Example usage:

local PanelSet = require("terminal.ui.panel.set")
local Panel = require("terminal.ui.panel")

-- Create panels for different views
local view1 = Panel { name = "view1", content = function(self) end }
local view2 = Panel { name = "view2", content = function(self) end }
local view3 = Panel { name = "view3", content = function(self) end }

-- Create a set and add panels
local set = PanelSet { children = { view1, view2, view3 } }

-- Switch between panels (e.g., from tab control)
set:select("view2")  -- Shows view2, hides others
set:select("view1")  -- Shows view1, hides others

-- Iterate over all panels
for panel in set:panel_set() do
  print("Panel:", panel.name)
end

Methods

ui.panel.set:add (panel[, jump=false]) Add a panel to the set.
ui.panel.set:get_selected () Get the currently selected panel name.
ui.panel.set:init (opts) Create a new Set instance.
ui.panel.set:panel_set () Iterator for traversing panels in the tree.
ui.panel.set:remove (name) Remove a panel from the set by name.
ui.panel.set:select (name) Select an existing panel by name (makes it visible).


Methods

ui.panel.set:add (panel[, jump=false])
Add a panel to the set. Accepts the panel; its name is derived from panel.name. When jump is truthy, the newly added panel is selected; otherwise the current selection is preserved. If there was no selection yet, the newly added panel becomes selected regardless of jump.

Parameters:

  • panel table The panel instance to add
  • jump boolean Select the newly added panel when truthy (default false)

Returns:

    nothing

Usage:

    local PanelSet = require("terminal.ui.panel.set")
local Panel = require("terminal.ui.panel")

local set = PanelSet {}
local panel1 = Panel { name = "panel1", content = function() end }
local panel2 = Panel { name = "panel2", content = function() end }

set:add(panel1)           -- panel1 is selected automatically
set:add(panel2, true)      -- panel2 is now selected
ui.panel.set:get_selected ()
Get the currently selected panel name.

Returns:

    string Name of the selected panel

Or

  1. nil If none selected
  2. string Error message

Usage:

    local PanelSet = require("terminal.ui.panel.set")
local Panel = require("terminal.ui.panel")

local set = PanelSet {}
set:add(Panel { name = "tab1", content = function() end })
set:add(Panel { name = "tab2", content = function() end })
set:select("tab2")

local selected = set:get_selected()  -- Returns "tab2"
ui.panel.set:init (opts)
Create a new Set instance. Do not call this method directly, call on the class instead.

Parameters:

  • opts Options (any Panel options that make sense for a divided parent)
    • children table Optional initial array of child panels (0..n) (optional)
    • selected string Optional name to select initially (optional)

Returns:

    Set A new Set instance

Usage:

    local PanelSet = require("terminal.ui.panel.set")
local Panel = require("terminal.ui.panel")

-- Empty set
local set = PanelSet {}

-- Set with initial panels
local set = PanelSet {
  children = {
    Panel { name = "tab1", content = function() end },
    Panel { name = "tab2", content = function() end },
  },
  selected = "tab2"  -- tab2 will be selected initially
}
ui.panel.set:panel_set ()
Iterator for traversing panels in the tree.

Returns:

    iterator function that yields panel instances

Usage:

    local PanelSet = require("terminal.ui.panel.set")
local Panel = require("terminal.ui.panel")

local set = PanelSet {}
set:add(Panel { name = "a", content = function() end })
set:add(Panel { name = "b", content = function() end })
set:add(Panel { name = "c", content = function() end })

-- Iterate over all panels
for panel in set:panel_set() do
  print("Found panel:", panel.name)
end
ui.panel.set:remove (name)
Remove a panel from the set by name. If the removed panel is currently selected, another available panel will be selected automatically (any available panel) or the set becomes empty.

Parameters:

  • name string The panel name to remove

Returns:

    Panel The removed panel

Or

  1. nil If the panel was not found
  2. string Error message

Usage:

    local PanelSet = require("terminal.ui.panel.set")
local Panel = require("terminal.ui.panel")

local set = PanelSet {}
set:add(Panel { name = "a", content = function() end })
set:add(Panel { name = "b", content = function() end })
set:select("b")

local removed = set:remove("b")  -- Returns the removed panel
-- "a" is now automatically selected since "b" was removed
assert.are.equal("a", set:get_selected())
ui.panel.set:select (name)
Select an existing panel by name (makes it visible). All other panels are hidden.

Parameters:

  • name string Panel name to select

Returns:

    true If the panel was found and selected

Or

  1. nil If the panel was not found
  2. string Error message

Usage:

    local PanelSet = require("terminal.ui.panel.set")
local Panel = require("terminal.ui.panel")

local set = PanelSet {}
set:add(Panel { name = "tab1", content = function() end })
set:add(Panel { name = "tab2", content = function() end })

local ok = set:select("tab2")  -- Returns true, tab2 is now visible
generated by LDoc 1.5.0