Display Components

Relevant source files

• BasaltLS.lua
• config.lua
• release/basalt.lua

Display components are UI elements designed for presenting information to users without direct interaction. These components focus on visual output and data presentation. The primary display components in Basalt are Label for text display and ProgressBar for progress visualization.

For interactive components like buttons and input fields, see page 5.5 (Interactive Components) and page 5.2 (Input Components). For navigation components, see page 5.4 (Navigation Components).

Component Hierarchy

Display components inherit from VisualElement and provide specialized rendering for information presentation.

Diagram: Display Component Class Hierarchy

Sources: src/elements/VisualElement.lua1-50 src/elements/Label.lua8-10 src/elements/ProgressBar.lua9-11

Label Component

The Label class provides text display with automatic sizing and text wrapping capabilities. It is the simplest display component, designed for showing static or dynamic text content.

Properties

Property	Type	Default	Description
text	string	"Label"	Text content to display. Can be a string or a function returning a string
autoSize	boolean	true	Automatically resize width to fit text content

Key Methods

Method	Parameters	Returns	Description
setText(text)	text: string	Label	Sets the text content and updates width if autoSize is enabled
getText()	-	string	Returns the current text content
getWrappedText()	-	table	Returns text wrapped to fit within the current width
setAutoSize(enabled)	enabled: boolean	Label	Enables or disables automatic width sizing

Initialization

Labels are created with a default width of 5 and height of 1. When autoSize is enabled, the width automatically adjusts to match the text length.

Sources: src/elements/Label.lua8-31 src/elements/Label.lua37-59

Text Rendering

The Label.render() method handles text wrapping and positioning:

Diagram: Label Rendering Flow

Sources: src/elements/Label.lua60-83

ProgressBar Component

The ProgressBar class visualizes progress with configurable fill direction and optional percentage display. It renders a filled bar that represents completion from 0% to 100%.

Properties

Property	Type	Default	Description
progress	number	0	Current progress value (0-100)
direction	string	"right"	Fill direction: "up", "down", "left", or "right"
progressColor	color	colors.black	Color used for the filled portion of the bar
showPercentage	boolean	false	Whether to display percentage text in center

Key Methods

Method	Parameters	Returns	Description
setProgress(value)	value: number	ProgressBar	Sets progress (clamped to 0-100)
setDirection(dir)	dir: string	ProgressBar	Sets fill direction
setProgressColor(color)	color: color	ProgressBar	Sets the filled portion color
setShowPercentage(show)	show: boolean	ProgressBar	Enables/disables percentage display

Initialization

Progress bars are created with default dimensions of 25x3 pixels, oriented to fill from left to right.

Sources: src/elements/ProgressBar.lua9-32 src/elements/ProgressBar.lua39-42

Progress Rendering

The rendering algorithm calculates fill dimensions based on direction and progress value:

Diagram: ProgressBar Rendering Logic

Sources: src/elements/ProgressBar.lua46-72

Rendering Pipeline

Display components follow the standard Basalt rendering pipeline, which propagates from Container to children and ultimately to the terminal buffer.

Diagram: Display Component Rendering Flow

Sources: src/elements/Label.lua60-83 src/elements/ProgressBar.lua46-72 src/elements/VisualElement.lua1-50

Property System Integration

Display components use the PropertySystem for reactive property management with automatic validation and render triggering.

Diagram: Property System Integration

Label Properties

The text property uses a custom setter to handle automatic width calculation:

Sources: src/elements/Label.lua13-31

ProgressBar Properties

All ProgressBar properties that affect visualization use canTriggerRender = true:

Property	canTriggerRender	Effect
progress	true	Updates fill dimensions
showPercentage	false	Only affects text overlay
progressColor	true	Changes fill color
direction	true	Changes fill orientation

Sources: src/elements/ProgressBar.lua13-20 src/propertySystem.lua1-100

Dynamic Content Updates

Label Dynamic Text

Labels support dynamic content through function-based text properties:

Diagram: Dynamic Label Updates

Example usage:

Sources: src/elements/Label.lua60-83

ProgressBar Dynamic Updates

Progress bars are typically updated through scheduled functions or event-driven updates:

Diagram: Progress Update Flow

Common patterns:

• Timer-based updates for loading indicators
• Event-driven updates for task completion
• Property observation for reactive updates

Sources: src/elements/ProgressBar.lua39-72 src/propertySystem.lua1-100

Element Creation and Usage

Display elements are created through the container's add* methods, which use the ElementManager system:

Common creation patterns:

Sources: src/elements/Label.lua37-59 src/elements/Image.lua32-51 src/elements/ProgressBar.lua26-42