Class ui.panel.Text

TextPanel class for displaying and navigating scrollable text content.

The TextPanel provides a powerful interface for displaying text content that doesn't fit on a single screen with efficient scrolling, navigation, and content management capabilities. It's designed for applications that need to display logs, documentation, or any scrollable text content.

Key Features

  • Inherits from Panel class, so it supports all the features of the Panel class.

Navigation & Scrolling:

  • Line-by-line scrolling with configurable step size
  • Page-based navigation (scroll by viewport height)
  • Direct positioning to any line or "go to bottom"
  • Highlighting a line for selection

Content Management:

  • Dynamic line addition and removal
  • Automatic line rotation with max_lines option
  • Text truncation/wrapping/word-wrapping and padding with UTF-8 support
  • Automatic re-rendering with auto_render option

Usage Examples

Basic text display:

local panel = TextPanel {
  lines = {"Line 1", "Line 2", "Line 3"},
  scroll_step = 1,
  auto_render = true,
  line_formatter = TextPanel.format_line_wordwrap,
}

Log viewer with line limits:

local log_panel = TextPanel {
  max_lines = 200,  -- Keep only last 200 lines
  text_attr = { fg = "green" },
  auto_render = true
}
log_panel:add_line("New log entry")

Functions

TextPanel:add_line (line) Add a line to the text content.
TextPanel:clear_lines () Clear all text content.
TextPanel:format_line_truncate (line, max_width) Format a line by truncating/padding it to fit the available width.
TextPanel:format_line_wordwrap (line, max_width) Format a line by word-wrapping it to fit the available width.
TextPanel:format_line_wrap (line, max_width) Format a line by wrapping it to fit the available width.
TextPanel:get_highlight () Get the highlighted source line index.
TextPanel:get_line_count () Get the total number of lines.
TextPanel:get_position () Get the current scroll position.
TextPanel:get_source_line_index (display_line_index) Get the source-line index from the display-line index.
TextPanel:init (opts) Create a new TextPanel instance.
TextPanel:page_down () Scroll down by one page (inner_height lines).
TextPanel:page_up () Scroll up by one page (inner_height lines).
TextPanel:scroll_down () Scroll down by scroll_step lines.
TextPanel:scroll_up () Scroll up by scroll_step lines.
TextPanel:set_highlight (source_line_idx[, jump=false]) Set the highlight for a specific source line.
TextPanel:set_line_formatter (formatter_func) Set the line formatter function.
TextPanel:set_lines (lines) Set new text lines.
TextPanel:set_position (position) Set the viewport position to a specific line.


Functions

TextPanel:add_line (line)
Add a line to the text content.

Parameters:

  • line string The line to add.

Returns:

    nothing
TextPanel:clear_lines ()
Clear all text content.

Returns:

    nothing
TextPanel:format_line_truncate (line, max_width)
Format a line by truncating/padding it to fit the available width. Returned lines must be padded with spaces to prevent having to clear lines.

Parameters:

  • line string The line text to format.
  • max_width number Maximum width in display columns.

Returns:

    table Array of formatted lines
TextPanel:format_line_wordwrap (line, max_width)
Format a line by word-wrapping it to fit the available width.

Parameters:

  • line string The line text to format.
  • max_width number Maximum width in display columns.

Returns:

    table Array of formatted lines
TextPanel:format_line_wrap (line, max_width)
Format a line by wrapping it to fit the available width.

Parameters:

  • line string The line text to format.
  • max_width number Maximum width in display columns.

Returns:

    table Array of formatted lines
TextPanel:get_highlight ()
Get the highlighted source line index.

Returns:

    number or nil The highlighted source line index, or nil if no highlight is set.
TextPanel:get_line_count ()
Get the total number of lines.

Returns:

    number The total number of lines.
TextPanel:get_position ()
Get the current scroll position.

Returns:

    number The current line position (1-based).
TextPanel:get_source_line_index (display_line_index)
Get the source-line index from the display-line index.

Parameters:

  • display_line_index number The display-line index to get the source-line index for.

Returns:

    number The source-line index, or nil if the display-line index is out of bounds.
TextPanel:init (opts)
Create a new TextPanel instance. Do not call this method directly, call on the class instead.

Parameters:

  • opts Configuration options (see Panel:init for inherited properties)
    • lines table Array of text lines to display. (optional)
    • scroll_step number Number of lines to scroll at a time. (default 1)
    • initial_position number Initial scroll position (1-based line number). (default 1)
    • text_attr table Text attributes to apply to all displayed text. (optional)
    • auto_render boolean Whether to automatically re-render when content changes. (default false)
    • max_lines number Maximum number of lines to keep (older lines are removed when exceeded upon a call to add_line). (optional)
    • line_formatter function Line formatter function to use (defaults to formatlinetruncate). see set_line_formatter for more details. (optional)
    • highlight number Source line index to highlight (1-based). (optional)
    • highlight_attr table Text attributes for highlighted lines (defaults to { reverse = true }). (optional)

Returns:

    TextPanel A new TextPanel instance.

Usage:

    local TextPanel = require("terminal.ui.panel.text")
local panel = TextPanel {
  lines = {"Line 1", "Line 2", "Line 3"},
  scroll_step = 2,
  initial_position = 1,
  text_attr = { fg = "green", brightness = "bright" },
  highlight = 2,
  highlight_attr = { fg = "red", bg = "yellow" },
}
panel:set_position(5)  -- Go to line 5
panel:scroll_down()  -- Scroll down by scroll_step
TextPanel:page_down ()
Scroll down by one page (inner_height lines).

Returns:

    nothing
TextPanel:page_up ()
Scroll up by one page (inner_height lines).

Returns:

    nothing
TextPanel:scroll_down ()
Scroll down by scroll_step lines.

Returns:

    nothing
TextPanel:scroll_up ()
Scroll up by scroll_step lines.

Returns:

    nothing
TextPanel:set_highlight (source_line_idx[, jump=false])
Set the highlight for a specific source line.

Parameters:

  • source_line_idx number or nil The source line index to highlight, or nil to remove highlight.
  • jump boolean Whether to adjust viewport to show the highlighted line. (default false)

Returns:

    nothing
TextPanel:set_line_formatter (formatter_func)

Set the line formatter function. Must conform to the line_formatter function signature; array_formatted_lines = function(text_panel_instance, line, max_width). The formatted lines must be full width, padded with spaces where necessary, to ensure that any previous content is overwritten.

This class comes with 3 formatters:

  • TextPanel.format_line_truncate - truncates long lines (default)
  • TextPanel.format_line_wrap - wraps lines to fit the available width
  • TextPanel.format_line_wordwrap - word-wraps lines to fit the available width

Parameters:

  • formatter_func function The formatter function to use.

Returns:

    nothing
TextPanel:set_lines (lines)
Set new text lines. This will reset position to 1, and clear highlighting.

Parameters:

  • lines table Array of text lines.

Returns:

    nothing
TextPanel:set_position (position)
Set the viewport position to a specific line. If the position is out of bounds, it will be corrected to be within bounds.

Parameters:

  • position number The line position to go to (1-based).

Returns:

    nothing
generated by LDoc 1.5.0