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 recalculate their size and position based on parent constraints.

Features:

  • 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(self)
    -- render content here
  end
}

-- Create a divided panel
local divided = Panel {
  orientation = Panel.orientations.horizontal, -- or Panel.orientations.vertical
  min_width = 50,    -- User-defined minimum width
  max_width = 100,   -- User-defined maximum width
  children = {
    Panel { content = function(self) -- left/top panel
      -- render left/top content
    end },
    Panel { content = function(self) -- 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.col Position: column, upper left corner
self.height Size: height
self.inner_col Position: column, inner upper left corner
self.inner_height Size: inner height
self.inner_row Position: row, inner upper left corner
self.inner_width Size: inner width
self.panels Panels lookup table.
self.row Position: row, upper left corner
self.width Size: width
ui.panel.orientations Panel orientation constants table.
ui.panel.types Panel type 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_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:hide ([hide=true]) Set the visibility 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.
ui.panel:visible () Get the visibility of this panel.


Fields

self.col
Position: column, upper left corner
  • col number Starting column, upper left corner.
self.height
Size: height
  • height number Height.
self.inner_col
Position: column, inner upper left corner
  • inner_col number Inner upper left corner.
self.inner_height
Size: inner height
  • inner_height number Inner height.
self.inner_row
Position: row, inner upper left corner
  • inner_row number Inner upper left corner.
self.inner_width
Size: inner width
  • inner_width number Inner width.
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
self.row
Position: row, upper left corner
  • row number Starting row, upper left corner.
self.width
Size: width
  • width number Width.
ui.panel.orientations
Panel orientation constants table.
ui.panel.types
Panel type constants table. See get_type.

Methods

ui.panel:calculate_layout (parent_row, parent_col, parent_height, parent_width)
Calculate the layout for this panel and all its children. This method must be called before render whenever there has been a change that impacts the layout. For example, terminal resize, (un)hiding a panel, changing the split ratio, etc.

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. This will automatically be called by the render method if a border is defined.

Returns:

    nothing
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 The first panel found with the given name.

Or

  1. nil In case the panel wasn't found.
  2. string Error message if panel 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 The split ratio (0.0 to 1.0) or nil if not divided. The value determines the size of the upper or left child panel. The remainder will go to the lower or right child panel.

Or

  1. nil In case the panel is a content panel.
  2. string Error message.

See also:

ui.panel:get_type ()
Get the type of this panel.

Returns:

    Returns Panel.types.content for content panels, or the orientation (Panel.orientations.horizontal or Panel.orientations.vertical) for divided panels.

Usage:

    local t = my_panel:get_type()
if t == Panel.types.content then
  -- my_panel is a content panel

elseif t == Panel.types.horizontal then
  -- my_panel is a horizontal divided panel

elseif t == Panel.types.vertical then
  -- my_panel is a vertical divided panel
end
ui.panel:hide ([hide=true])
Set the visibility of this panel.

Parameters:

  • hide boolean True to hide the panel, false to show it. (default true)

Returns:

    nothing

See also:

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 only self parameter. Access layout via self.innerrow, self.innercol, self.innerheight, self.innerwidth. (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. (default 1)
    • min_width number Minimum width constraint. (default 1)
    • max_height number Maximum height constraint. (default math.huge)
    • max_width number Maximum width constraint. (default math.huge)
    • split_ratio number Ratio for dividing child panels (0.0 to 1.0). (default 0.5)
    • visible boolean Whether the panel is visible (true) or hidden (false). (default true)
    • 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)
    -- render content here
  end,
  border = {
    format = terminal.draw.box_fmt.single,
    title = "My Panel"
  }
}
ui.panel:render ()
Render this panel and all its children. Note: if any changes have been made that impact the layout, then calculate_layout must be called before render. For example, terminal resize, (un)hiding a panel, changing the split ratio, etc.

Returns:

    nothing
ui.panel:set_split_ratio (ratio)
Set the split ratio for divided panels. After changing the ratio, calculate_layout must be called to update the layout.

Parameters:

  • ratio number The split ratio (0.0 to 1.0). The value set determines the size of the upper or left child panel. The remainder will go to the lower or right child panel.

Returns:

    nothing

See also:

ui.panel:visible ()
Get the visibility of this panel.

Returns:

    boolean True if visible, false if hidden.

See also:

generated by LDoc 1.5.0