Widget

#include <Widget.hpp>

Inherits: enable_shared_from_this< Widget > Subclassed by: Button, Container, Dropdown, DropdownPopup, Input, Label, Modal, Navigator, ScrollView, TextArea, TextView

The base class for all UI components.

Widget is the foundation of the UI system. All visual components (buttons, labels, containers, etc.) inherit from this class. Widgets form a tree hierarchy where each widget can have a parent and children.

Key responsibilities:

Measure: Calculate how much space is needed
Layout: Position and size the widget and its children
Render: Draw to the screen buffer
Events: Handle user input
Focus: Manage keyboard focus

Subclassing: To create a custom widget, override these virtual methods:

measure(): Return your size requirements
layout(): Position yourself and children (call parent class if needed)
drawContent(): Render your content (not render()!)
onEvent(): Handle input events
isFocusable(): Return true if your widget can receive focus

Public Attributes

Return	Name	Description
`bool`	`visible`	Whether this widget is visible and participates in layout. When false, the widget is not rendered, not focusable, and takes no space.
`std::weak_ptr< Widget >`	`parent`	Weak pointer to this widget’s parent. Use weak_ptr to avoid circular references.

visible

bool visible = true

Whether this widget is visible and participates in layout. When false, the widget is not rendered, not focusable, and takes no space.

parent

std::weak_ptr< Widget > parent

Weak pointer to this widget’s parent. Use weak_ptr to avoid circular references.

Public Methods

Return	Name	Description
`Size`	`measure` `virtual`	Measures how much space this widget needs.
`void`	`layout` `virtual`	Positions and sizes this widget and its children.
`void`	`render` `virtual`	Renders this widget to the buffer.
`bool`	`onEvent` `virtual` `inline`	Handles an input event.
`void`	`addEventListener` `inline`	Registers an event listener on this widget.
`bool`	`isFocusable` `virtual` `const` `inline`	Returns whether this widget can receive keyboard focus.
`void`	`onFocus` `virtual` `inline`	Called when this widget gains keyboard focus.
`void`	`onBlur` `virtual` `inline`	Called when this widget loses keyboard focus.
`bool`	`focused` `const`	Checks if this widget currently has keyboard focus.
`void`	`setStyle` `inline`	Sets the widget’s normal style.
`void`	`setFocusedStyle` `inline`	Sets the widget’s style when it has focus.
`const Style &`	`getStyle` `const` `inline`	Gets the widget’s normal style.
`const Style &`	`getFocusedStyle` `const` `inline`	Gets the widget’s focused style.
`const Rect &`	`getRect` `const` `inline`	Gets this widget’s bounding rectangle.
`std::vector< std::shared_ptr< Widget > >`	`getChildren` `virtual` `const` `inline`	Returns this widget’s children.
`std::vector< std::shared_ptr< Widget > >`	`getFocusChildren` `virtual` `const` `inline`	Returns this widget’s children for focus traversal.

measure

virtual

virtual Size measure(int availW, int availH)

Measures how much space this widget needs.

Called during the measurement pass to determine widget size requirements. Should return the preferred size based on available space.

Parameters

availW Maximum available width (may be ignored by widget)
availH Maximum available height (may be ignored by widget)

Returns

The Size this widget wants, or needs at minimum

layout

virtual

virtual void layout(int x, int y, int width, int height)

Positions and sizes this widget and its children.

Called after measurement to actually place the widget at a specific location. If your widget has children, you must call their layout() methods here.

Parameters

x The X coordinate for this widget
y The Y coordinate for this widget
width The width allocated to this widget
height The height allocated to this widget

render

virtual

virtual void render(backend::Buffer & buf)

Renders this widget to the buffer.

The default implementation handles drawing borders and background.

Parameters

buf The buffer to draw to

onEvent

virtual inline

virtual inline bool onEvent(const events::Event & event)

Handles an input event.

Called by the framework to deliver an event to this widget. The default implementation runs any listeners registered via addEventListener(), then returns false. Subclasses (Button, Input, etc.) override this to add built-in behavior, and should call Widget::onEvent(event) first to give user listeners a chance to handle the event before the widget’s own logic.

Return true if the event was handled, false to let it bubble to the parent widget.

Parameters

event The input event

Returns

True if this widget (or one of its listeners) handled the event

addEventListener

inline

inline void addEventListener(EventHandler handler)

Registers an event listener on this widget.

Listeners are called by onEvent() before the widget’s built-in behavior. If a listener returns true, the event is considered handled and will not propagate further. Multiple listeners can be registered and are called in registration order.

Example:

root->addEventListener([&](/api/const events::event& e) -> bool {
  if (auto* k = std::get_if<events::KeyEvent>(&e)) {
    if (k->modifiers.ctrl && k->key == 's') {
      save();
      return true;
    }
  }
  return false;
});

Parameters

handler The function to call when this widget receives an event

isFocusable

virtual const inline

virtual inline bool isFocusable() const

Returns whether this widget can receive keyboard focus.

Widgets like Button and Input return true; containers return false.

Returns

True if this widget can be focused, false otherwise

onFocus

virtual inline

virtual inline void onFocus()

Called when this widget gains keyboard focus.

onBlur

virtual inline

virtual inline void onBlur()

Called when this widget loses keyboard focus.

focused

const

bool focused() const

Checks if this widget currently has keyboard focus.

Returns

True if this widget is focused

setStyle

inline

inline void setStyle(const Style & s)

Sets the widget’s normal style.

Parameters

s The style to apply

setFocusedStyle

inline

inline void setFocusedStyle(const Style & s)

Sets the widget’s style when it has focus.

Parameters

s The focused style to apply

getStyle

const inline

inline const Style & getStyle() const

Gets the widget’s normal style.

Returns

The current style

getFocusedStyle

const inline

inline const Style & getFocusedStyle() const

Gets the widget’s focused style.

Returns

The focused style

getRect

const inline

inline const Rect & getRect() const

Gets this widget’s bounding rectangle.

Returns

The position and size of this widget

getChildren

virtual const inline

virtual inline std::vector< std::shared_ptr< Widget > > getChildren() const

Returns this widget’s children.

Returns

Vector of child widgets (empty if no children)

getFocusChildren

virtual const inline

virtual inline std::vector< std::shared_ptr< Widget > > getFocusChildren() const

Returns this widget’s children for focus traversal.

By default this matches getChildren(). Widgets with custom rendering behavior (like clipping/compositing) can override this without affecting paint traversal.

Protected Attributes

Return	Name	Description
`Style`	`style`	The normal (unfocused) style.
`Style`	`focusedStyle`	The style applied when this widget has focus.
`Rect`	`rect`	This widget’s bounding rectangle (set during layout)
`std::vector< EventHandler >`	`listeners`	Registered event listeners, called by onEvent() in order.

style

Style style

The normal (unfocused) style.

focusedStyle

Style focusedStyle

The style applied when this widget has focus.

rect

Rect rect

This widget’s bounding rectangle (set during layout)

listeners

std::vector< EventHandler > listeners

Registered event listeners, called by onEvent() in order.

Protected Methods

Return	Name	Description
`void`	`drawContent` `virtual` `inline`	Draws this widget’s content.
`const Style &`	`activeStyle` `const`	Gets the currently active style (normal or focused).
`Rect`	`innerRect` `const`	Gets the inner rectangle, accounting for border and padding.
`int`	`justifyX` `const`	Calculates the X position for content based on horizontal alignment.
`int`	`justifyY` `const`	Calculates the Y position for content based on vertical alignment.
`Rect`	`alignContentRect` `const`	Calculates the aligned content rectangle within the inner area.

drawContent

virtual inline

virtual inline void drawContent(backend::Buffer & buf, Rect inner)

Draws this widget’s content.

Called by render() after background and borders are drawn. This is where you should draw your widget’s actual content. The inner rectangle accounts for borders and padding.

Parameters

buf The buffer to draw to
inner The inner rectangle (excluding border/padding)

activeStyle

const

const Style & activeStyle() const

Gets the currently active style (normal or focused).

Returns

The normal style if not focused, focused style if focused

innerRect

const

Rect innerRect() const

Gets the inner rectangle, accounting for border and padding.

Returns

The inner rectangle (content area)

justifyX

const

int justifyX(int innerX, int innerW, int contentW, Align align) const

Calculates the X position for content based on horizontal alignment.

Parameters

innerX The inner rectangle’s X coordinate
innerW The inner rectangle’s width
contentW The content width
align The horizontal alignment

Returns

The X coordinate for the content’s top-left corner

justifyY

const

int justifyY(int innerY, int innerH, int contentH, Align align) const

Calculates the Y position for content based on vertical alignment.

Parameters

innerY The inner rectangle’s Y coordinate
innerH The inner rectangle’s height
contentH The content height
align The vertical alignment

Returns

The Y coordinate for the content’s top-left corner

alignContentRect

const

Rect alignContentRect(Rect inner, int contentW, int contentH, Align ax, Align ay) const

Calculates the aligned content rectangle within the inner area.

Combines justifyX and justifyY to produce a full Rect for placing content inside the inner rectangle with the given alignments.

Parameters

inner The inner rectangle to align within
contentW The content width
contentH The content height
ax Horizontal alignment
ay Vertical alignment

Returns

The rectangle where content should be drawn

Public Types

Name	Description
`EventHandler`	Function signature for event listeners.

EventHandler

std::function< bool(const events::Event &)> EventHandler()

Function signature for event listeners.

Takes the event and returns true if the listener handled it (stopping propagation) or false to let the event continue to the widget’s own onEvent() and then bubble to the parent.

Private Methods

Return	Name	Description
`void`	`drawBackground`	Fills the widget’s background area with the active background color.
`void`	`drawBorder`	Draws the widget’s border using the active border style.

drawBackground

void drawBackground(backend::Buffer & buf)

Fills the widget’s background area with the active background color.

Parameters

buf The buffer to draw to

drawBorder

void drawBorder(backend::Buffer & buf)

Draws the widget’s border using the active border style.

Parameters

buf The buffer to draw to