Container

extends Element

Container: an element that owns and renders child elements.

Types

ContainerScrollbarMode

ContainerScrollbarMode = "auto"|"always"|"hidden"

ContainerScrollbarGeometry

Field	Type	Description
showX	boolean	Whether the horizontal scrollbar is visible
showY	boolean	Whether the vertical scrollbar is visible
horizontalLength	number	Horizontal scrollbar track length
verticalLength	number	Vertical scrollbar track length
horizontalThumbSize	number	Horizontal thumb size
horizontalThumbPos	number	Horizontal thumb offset
verticalThumbSize	number	Vertical thumb size
verticalThumbPos	number	Vertical thumb offset
maxX	number	Maximum horizontal scroll offset
maxY	number	Maximum vertical scroll offset

ContainerScrollInfo

extends ContainerScrollbarGeometry

Field	Type	Description
x	number	Current horizontal scroll offset
y	number	Current vertical scroll offset
contentWidth	number	Laid-out content width
contentHeight	number	Laid-out content height

Properties

Property	Type	Default	Description
scrollable	boolean	false	Enables content scrolling for this container
scrollbar	ContainerScrollbarMode	"auto"	"auto", "always" or "hidden"
scrollXEnabled	boolean	true	Allow horizontal scrolling
scrollYEnabled	boolean	true	Allow vertical scrolling
scrollStep	number	3	Cells scrolled per mouse wheel tick
scrollbarColor	number	colors.gray	Scrollbar track color
scrollbarThumbColor	number	colors.lightGray	Scrollbar thumb color

Events

Event	Registrar	Description
scrollChange	:onScrollChange(fn)	Fired when the scroll offset changes, with (x, y)

Methods

Container:setup()

Initializes per-instance state and input handlers.

Container:getScroll()

Returns the current horizontal and vertical scroll offsets.

• returns x (number)
• returns y (number)

Container:getContentSize()

Returns cached content bounds after the latest layout pass.

• returns width (number)
• returns height (number)

Container:getScrollInfo()

Returns scrollbar visibility, ranges, offsets and content size.

• returns info (ContainerScrollInfo)

Container:scrollTo(x, y)

Scrolls to absolute content offsets.

• x (number, optional) Horizontal offset, default 0

• y (number, optional) Vertical offset, default 0

• returns (self)

Container:scrollBy(dx, dy)

Scrolls relative to the current offsets.

• dx (number, optional) Horizontal delta, default 0

• dy (number, optional) Vertical delta, default 0

• returns (self)

Container:scrollToElement(el)

Aligns a descendant's top-left corner with the viewport.

• el (Element) Descendant element

• returns (self)

Container:ensureVisible(el)

Applies the smallest scroll needed to reveal a descendant.

• el (Element) Descendant element

• returns (self)

Container:addChild(child)

Attaches an existing element as the final child.

• child (T) Element to attach

• returns child (T)

Container:removeChild(child)

Detaches a direct child and releases its interaction state.

• child (Element) Child to remove

• returns removed (boolean)

Container:destroy()

Recursively destroys every descendant before detaching this container. This is important for stateful children such as Program: merely removing their parent frame would otherwise leave their scheduled coroutines alive.

• returns (self)

Container:getChildren()

Returns the live direct-child array.

• returns children (Element[])

Container:find(childName)

Finds a descendant element by its name property (depth-first).

• childName (string) Element name

• returns element (Element|nil)

Container:render(buf)

Renders the element into the buffer.

• buf (Render) The render buffer (local coordinates, pre-clipped)

Container:handleMouse(event, btn, x, y)

Routes a mouse event to children (topmost first), falling back to self.

• event (string) Mouse event name

• btn (number) Mouse button or scroll direction

• x (number) Local x coordinate

• y (number) Local y coordinate

• returns consumer (Element|nil) The consuming element, or nil

Container:findAt(x, y)

Returns the deepest visible element at a point, regardless of handlers.

• x (number) Local x coordinate

• y (number) Local y coordinate

• returns element (Element)

Container.register(elementName, elementClass)

Registers an element class: creates Container:add<Name>(props).

• elementName (string) Public element name
• elementClass ({ new: fun(props?: table): T }) Element class