UI Components

Relevant source files

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

This page provides a comprehensive overview of Basalt2's built-in UI components, their organization, inheritance hierarchy, and instantiation patterns. UI components are visual and interactive elements that make up the user interface of a Basalt application.

For detailed information about specific component categories, see:

• Layout Components - Frame, TabControl, SideNav, ScrollFrame, Accordion, FlexBox
• Input Components - Input, TextBox
• Display Components - Label, Image, Display, BigFont
• Data Components - List, Menu, Table, Tree, Collection
• Interactive Components - Button, CheckBox, Switch, Slider, ProgressBar
• Program Component - Program element for embedding external Lua programs
• Specialized Components - DropDown, ComboBox, Dialog, Toast, Breadcrumb, ContextMenu

For information about the base element classes and rendering system, see Element Hierarchy.

---

Component Hierarchy

All UI components in Basalt2 inherit from a base class hierarchy that provides progressively more specialized functionality. This inheritance structure enables code reuse and maintains separation of concerns.

Class Inheritance Structure

Sources: config.lua105-444 BasaltLS.lua1-2500 Diagram 2 from high-level architecture

Base Class Responsibilities

Class	Primary Responsibility	Key Features
BaseElement	Property system and events	Property definitions, observers, event registration, state management
VisualElement	Rendering and positioning	x, y, z, width, height, background, foreground, constraints, render buffer interaction
Container	Child management	children array, event propagation, z-index sorting, focus management, offset management
BaseFrame	Terminal integration	Terminal binding, peripheral support, event dispatch root, top-level rendering

Sources: elements/BaseElement.lua1-500 elements/VisualElement.lua1-1000 elements/Container.lua1-800 elements/BaseFrame.lua1-300

---

Component Categories

Components are organized into functional categories based on their primary purpose. Each category is defined in the component registry and can be loaded on demand.

Category Organization

Sources: config.lua105-444

Component Registry

All components are registered in config.lua with metadata including dependencies, file paths, and default loading status.

Property	Description
path	Relative path to component file within elements/ directory
requires	Array of parent class names that must be loaded first
description	Human-readable description of component functionality
default	Boolean indicating if component is included in default release build
size	File size in bytes

Example registry entry:

Sources: config.lua276-284

---

Component Instantiation

Components are instantiated through the elementManager which handles dependency resolution, caching, and class creation.

Instantiation Flow

Sources: elementManager.lua1-500 elements/Button.lua227-229

Container Add Methods

The Container class provides convenience methods for creating child elements. Each method corresponds to a registered component type.

Method naming pattern: add<ComponentName>(props)

Example methods:

• container:addButton(props) → Creates Button instance
• container:addLabel(props) → Creates Label instance
• container:addFrame(props) → Creates Frame instance

These methods are automatically generated by the system and handle:

1. Component class retrieval via elementManager.getElement()
2. Instance creation via Component.new()
3. Initialization with props and basalt context
4. Parent-child relationship establishment via addChild()

Sources: elements/Container.lua1-900

Manual Instantiation

Components can also be instantiated manually without a parent container:

Sources: elementManager.lua200-300

---

Common Patterns

All UI components share common patterns inherited from their base classes.

Property System

Components use the property system defined in BaseElement for reactive state management.

Property definition:

This automatically generates:

• get<PropertyName>() method
• set<PropertyName>(value) method
• State-specific variants for UI states (hover, pressed, disabled)

Sources: propertySystem.lua1-500 elements/BaseElement.lua1-400

Event System

Components define events using defineEvent() which creates:

• Event registration via on<EventName>(callback)
• Event firing via fireEvent(eventName, ...args)
• Event observation via observe(eventName, callback)

Common events:

• mouse_click - Mouse button pressed
• mouse_up - Mouse button released
• mouse_drag - Mouse moved while button held
• mouse_scroll - Mouse wheel scrolled
• mouse_move - Mouse position changed
• key - Keyboard key pressed
• key_up - Keyboard key released
• char - Character typed

Sources: elements/BaseElement.lua200-400 elements/VisualElement.lua500-1000

Rendering Pattern

All visual components implement the render() method which writes to the parent's render buffer:

Rendering methods:

• blit(x, y, text, fg, bg) - Write text with colors
• textFg(x, y, text, color) - Write text with foreground color
• textBg(x, y, text, color) - Write text with background color
• multiBlit(x, y, width, height, text, fg, bg) - Write repeated pattern

Sources: elements/VisualElement.lua800-1200 render.lua1-200

State Management

Components support multiple visual states that can be set and unset dynamically:

State	Description
focused	Element has keyboard focus
hovered	Mouse is over element
pressed	Mouse button is held down on element
disabled	Element is non-interactive

State methods:

• setState(stateName) - Add state
• unsetState(stateName) - Remove state
• hasState(stateName) - Check if state is active
• getResolved(propertyName) - Get property value for current state

Sources: elements/BaseElement.lua300-500

---

Component Loading and Dependencies

The elementManager handles component loading with automatic dependency resolution.

Dependency Resolution

Sources: elementManager.lua1-500 config.lua105-444

Dependency Chain Examples

Component	Direct Dependency	Transitive Dependencies
Button	VisualElement	BaseElement
Frame	Container	VisualElement, BaseElement
Dialog	Frame	Container, VisualElement, BaseElement
ComboBox	DropDown	List, Collection, VisualElement, BaseElement
Table	Collection	VisualElement, BaseElement

Sources: config.lua276-444

Auto-loading from Remote Sources

The elementManager supports loading components from remote URLs or disk mounts when they are not available locally.

Configuration:

• elementManager.setDiskMount(path) - Set path for disk-based loading
• Components are loaded on-demand when accessed
• Loaded components are cached in memory

Sources: elementManager.lua300-500

---

Component Default Status

Components in the registry have a default flag indicating whether they are included in the standard release build.

Default Components

Always included:

• BaseElement, VisualElement, Container, BaseFrame, Timer
• Button, Label, Input, CheckBox, Switch, Slider, ProgressBar
• Frame, TabControl, SideNav, ScrollFrame, Accordion, FlexBox
• List, Menu, Table, Tree, Collection
• ContextMenu, Dialog, Toast, Breadcrumb, ScrollBar

Optional Components

Excluded by default (must be explicitly loaded):

• TextBox - Large file with syntax highlighting and autocomplete
• ComboBox - Combines dropdown with editable input
• DropDown - Dropdown selection menu
• Display - CC Window API wrapper
• Image - BIMG format image display
• BigFont - Large text rendering
• LineChart, BarChart - Charting components
• Graph - Point-based graph visualization

Sources: config.lua105-444

---

Component Property Overview

The following table summarizes common properties available across all visual components:

Property Category	Properties	Inherited From
Positioning	x, y, z	VisualElement
Sizing	width, height	VisualElement
Styling	background, foreground	VisualElement
Visibility	visible, transparent	VisualElement
Interactivity	enabled, focusable	VisualElement
Container	children, offsetX, offsetY	Container
State	State-specific variants of style properties	BaseElement

State-specific properties:

• hoverBackground, hoverForeground
• pressedBackground, pressedForeground
• disabledBackground, disabledForeground
• focusedBackground, focusedForeground

Sources: elements/VisualElement.lua1-500 elements/Container.lua1-300

---

Summary

Basalt2 provides a comprehensive component library organized into a clean inheritance hierarchy. Components are:

1. Registered in config.lua with metadata and dependencies
2. Loaded on-demand by elementManager with automatic dependency resolution
3. Instantiated via container add<Component>() methods or manually
4. Configured through the property system with reactive updates
5. Rendered through a buffered rendering pipeline
6. Interacted with through the event system

For detailed information about specific components, refer to the category-specific pages listed at the top of this document.

Sources: config.lua1-510 elementManager.lua1-500 elements/BaseElement.lua1-500 elements/VisualElement.lua1-1000 elements/Container.lua1-900