Class ui.Panel

Panel system for terminal UI layouts.

This module provides a flexible panel system for creating terminal UI layouts. Each panel can contain content or be divided into two child panels (horizontally or vertically). Panels automatically recalculate their size and position based on parent constraints.

Features:

  • Automatic layout calculation with size constraints
  • Horizontal and vertical panel division
  • Content callback system for rendering
  • Minimum and maximum size constraints
  • Dynamic resizing based on orientation

The typical usage starts with a ui.panel.Screen instance as the root panel.

Usage:

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

-- Create a root panel with content
local root = Panel {
  content = function(row, col, height, width)
    -- render content here
  end
}

-- Create a divided panel
local divided = Panel {
  orientation = Panel.orientations.horizontal, -- or Panel.orientations.vertical
  children = {
    Panel { content = function(self, r, c, h, w) -- left/top panel
      -- render left/top content
    end },
    Panel { content = function(self, r, c, h, w) -- right/bottom panel
      -- render right/bottom content
    end }
  }
}

-- Calculate layout
root:calculate_layout(1, 1, 24, 80) -- row, col, height, width
root:render()

Fields

self.panels Panels lookup table.
ui.panel.orientations Panel orientation constants table.

Methods

ui.panel:calculate_layout (parent_row, parent_col, parent_height, parent_width) Calculate the layout for this panel and all its children.
ui.panel:clear () Clears the panel content (inner area).
ui.panel:draw_border () Draw the border around panel content.
ui.panel:get_children () Get the children of this panel.
ui.panel:get_max_height () Get the maximum height constraint of this panel.
ui.panel:get_max_width () Get the maximum width constraint of this panel.
ui.panel:get_min_height () Get the minimum height constraint of this panel.
ui.panel:get_min_width () Get the minimum width constraint of this panel.
ui.panel:get_panel (name) Find a panel by name in this panel tree.
ui.panel:get_size () Get the current size of this panel.
ui.panel:get_split_ratio () Get the split ratio of this panel.
ui.panel:get_type () Get the type of this panel.
ui.panel:init (opts) Create a new Panel instance.
ui.panel:render () Render this panel and all its children.
ui.panel:set_split_ratio (ratio) Set the split ratio for divided panels.


Fields

self.panels
Panels lookup table. Provides access to child panels by name with recursive search and caching.

Usage:

    local header = main_panel.panels.header -- Returns panel named "header"
local not_found = parent.panels.nonexistent -- Returns nil
ui.panel.orientations
Panel orientation constants table.

Methods

ui.panel:calculate_layout (parent_row, parent_col, parent_height, parent_width)
Calculate the layout for this panel and all its children.

Parameters:

  • parent_row number Parent panel's starting row.
  • parent_col number Parent panel's starting column.
  • parent_height number Parent panel's height.
  • parent_width number Parent panel's width.

Returns:

    nothing
ui.panel:clear ()
Clears the panel content (inner area).

Returns:

    nothing
ui.panel:draw_border ()
Draw the border around panel content.

Returns:

    nothing
ui.panel:get_children ()
Get the children of this panel.

Returns:

    table or nil Array of child panels or nil if not divided.
ui.panel:get_max_height ()
Get the maximum height constraint of this panel.

Returns:

    number The maximum height.
ui.panel:get_max_width ()
Get the maximum width constraint of this panel.

Returns:

    number The maximum width.
ui.panel:get_min_height ()
Get the minimum height constraint of this panel.

Returns:

    number The minimum height.
ui.panel:get_min_width ()
Get the minimum width constraint of this panel.

Returns:

    number The minimum width.
ui.panel:get_panel (name)
Find a panel by name in this panel tree. Searches in order: self, child 1, child 2.

Parameters:

  • name string The name to search for.

Returns:

    Panel or nil The first panel found with the given name, or nil if not found.
ui.panel:get_size ()
Get the current size of this panel.

Returns:

  1. number The current height in rows.
  2. number The current width in columns.
ui.panel:get_split_ratio ()
Get the split ratio of this panel.

Returns:

    number or nil The split ratio or nil if not divided.
ui.panel:get_type ()
Get the type of this panel.

Returns:

    Returns "content" for content panels, or the orientation (Panel.orientations.horizontal or Panel.orientations.vertical) for divided panels.
ui.panel:init (opts)
Create a new Panel instance. Do not call this method directly, call on the class instead. See example.

Parameters:

  • opts Options for the panel.
    • content function Content callback function that takes (self, row, col, height, width) parameters. (optional)
    • clear_content boolean Whether to clear the content area before rendering. (default true)
    • orientation table Panel orientation: Panel.orientations.horizontal or Panel.orientations.vertical (for divided panels). (optional)
    • children table Array of exactly 2 child panels (for divided panels). (optional)
    • name string Optional name for the panel. Defaults to tostring(self) if not provided. (optional)
    • min_height number Minimum height constraint (content panels only). (default 1)
    • min_width number Minimum width constraint (content panels only). (default 1)
    • max_height number Maximum height constraint (content panels only). (default math.huge)
    • max_width number Maximum width constraint (content panels only). (default math.huge)
    • split_ratio number Ratio for dividing child panels (0.0 to 1.0). (default 0.5)
    • border table Border configuration for content panels, with the following properties: (optional)
    • format table The box format table (see terminal.draw.box_fmt).
    • attr table Table of attributes for the border, eg. { fg = "red", bg = "blue" }. (optional)
    • title string Optional title to display in the border. (optional)
    • truncation_type string The type of title-truncation to apply, either "left", "right", or "drop". (default "right")
    • title_attr table Table of attributes for the title, eg. { fg = "red", bg = "blue" }. (optional)

Returns:

    Panel A new Panel instance.

Usage:

    local Panel = require("terminal.ui.panel")
local panel = Panel {
  content = function(self, row, col, height, width)
    -- render content here
  end,
  border = {
    format = terminal.draw.box_fmt.single,
    title = "My Panel"
  }
}
ui.panel:render ()
Render this panel and all its children.

Returns:

    nothing
ui.panel:set_split_ratio (ratio)
Set the split ratio for divided panels.

Parameters:

  • ratio number The split ratio (0.0 to 1.0).

Returns:

    nothing
generated by LDoc 1.5.0