UI Surfaces

Surfaces are the visible building blocks of the UI framework. The built-in set focuses on common terminal patterns: fills, text labels, scrolling buffer content, visual scroll bars, and single-line status bars.

Important

The UI Framework is currently in beta, and parts of the API may change in future releases.

Usage

Painting Themed Backgrounds with Panel

Panel fills its region with the theme block and style for theme::Element::Panel and theme::Part::Background. Use a custom theme when you want panels to have a different fill character, color, or inset rules across the whole application.

auto body = ui::Panel::create();
body->addSurface(ui::TextBox::create("Connected", Alignment::Center));

Panels can host child surfaces, so they are useful as themed background regions in larger layouts. The theme system keeps this styling out of each individual panel instance.

Centering Labels with TextBox

TextBox renders one terminal string using the same alignment and wrapping rules as Text. The Text theme part may add margins and padding around this content: margins stay outside the text box’s painted area, while padding is filled with the text part’s background block and style.

auto title = ui::TextBox::create("Hello World!", Alignment::Center);
title->editLayoutMetrics().setFixedHeight(3);

Making Buffer Views Scrollable

ScrollingBufferView turns a readable buffer into a ready-to-use scrollable surface. This is especially useful with CursorBuffer or BufferView style content. It derives from AbstractScrollArea, so it uses the same scrollOffset API and optional scroll bars as other scrollable UI components.

auto history = std::make_shared<CursorBuffer>(
    Size{80, 1},
    CursorBuffer::OverflowMode::ExpandThenShift,
    Size{80, 500},
    Char{" ", bg::Black});

auto view = ui::ScrollingBufferView::create(history);
view->setShowCropCharacters(true);
view->setCropCharacter(Direction::North, Char{U'▲', fg::BrightBlue, bg::Black});
view->setCropCharacter(Direction::South, Char{U'▼', fg::BrightBlue, bg::Black});
view->setScrollBarMode(Orientation::Vertical, ui::ScrollBarMode::Automatic);

auto scrollUpAction = ui::Action::create("up");
scrollUpAction->setKeys({Key::Up, U'k'});
scrollUpAction->setTriggerFn([view] { view->scrollUp(); });
page->actions().add(scrollUpAction);

auto pageDownAction = ui::Action::create("page down");
pageDownAction->setKeys({Key::PageDown, Key::Space});
pageDownAction->setTriggerFn([view] { view->pageDown(); });
page->actions().add(pageDownAction);

visibleContentRect() reports the buffer rectangle currently visible through the viewport. scrollIntoView() adjusts the offset by the smallest amount needed to reveal a content rectangle.

Painting Custom Scrollable Surfaces

Use AbstractScrollArea when the content is not represented by one child surface and is instead painted directly by a custom surface. The base class owns the scrolling state, common scroll helpers, scroll bar modes, and scroll bar surfaces. Subclasses provide content metrics and painting.

class WorldView final : public ui::AbstractScrollArea {
public:
    explicit WorldView(ProtectedTag protectedTag) noexcept : AbstractScrollArea{protectedTag} {}

    [[nodiscard]] static auto create() -> std::shared_ptr<WorldView> {
        auto view = std::make_shared<WorldView>(ProtectedTag{});
        view->initializeScrollAreaChildren();
        return view;
    }

protected:
    [[nodiscard]] auto contentSizeForViewport(Size viewportSize) const noexcept -> Size override {
        static_cast<void>(viewportSize);
        return Size{360, 180};
    }

    void onPaintArea(
        Position scrollOffset,
        Rectangle targetRect,
        WritableBuffer &buffer,
        const ui::PaintContext &context) noexcept override {
        static_cast<void>(context);
        // Paint content coordinates starting at scrollOffset into targetRect.
    }
};

The targetRect passed to onPaintArea() is the local viewport rectangle. scrollOffset is already clamped for the current content and viewport size. Applications bind keys to scrollUp(), pageDown(), scrollToBottom(), or any of the other scroll helpers.

Showing Scroll Position with Scroll Bars

HorizontalScrollBar and VerticalScrollBar render visual indicators for a visible range inside a larger scroll region. They do not handle input themselves, so application code remains free to connect them to any scrolling model. AbstractScrollArea and ScrollArea update their owned scroll bars automatically, so manual region setup is only needed when using scroll bars as standalone visual surfaces.

auto horizontal = ui::HorizontalScrollBar::create();
horizontal->setScrollRegion(IndexRange{0, 2'000});
horizontal->setVisibleRegion(IndexRange{320, 160});

auto vertical = ui::VerticalScrollBar::create();
vertical->setScrollRegion(IndexRange{0, 800});
vertical->setVisibleRegion(IndexRange{120, 40});

Scroll bar colors, track blocks, thumb blocks, and track content margins come from the active theme. Set a theme on the application or page when you want all owned and standalone scroll bars to share the same visual language.

Layout Rules

Scroll bars always use a fixed thickness of one cell:

  • horizontal scroll bars keep a fixed height of 1 and grow in width

  • vertical scroll bars keep a fixed width of 1 and grow in height

The active theme paints the track across the full scroll bar rectangle. The track block’s content margins define the usable area for the thumb. The default classic terminal blocks use one-cell margins for arrow cells, while plain blocks allow the thumb to use the full surface. The handle is projected from visibleRegion() into the usable track area using IndexRange’s exclusive end semantics.

If the visible region does not intersect the scroll region, the surface renders only the themed track. A handle that would otherwise become too small is expanded to stay readable:

  • tracks with three or more cells use at least a three-cell thumb

  • a two-cell track uses a two-cell thumb

  • a one-cell track uses a one-cell thumb

Building Reusable Lines

DynamicTextLine is a composed one-line surface for headers and compact status rows. It owns three managed DynamicText children for the left, middle, and right sections. The line calculates where those children belong; the children paint and crop their own text.

auto header = ui::HeaderLine::create();
using Section = ui::DynamicTextLine::Section;
using SpacePriority = ui::DynamicTextLine::SpacePriority;

header->setText(
    Section::Left,
    String{"Viewer", Color{fg::BrightWhite, bg::Inherited}});
header->setMargins(Section::Left, Margins{1, 0});

header->dynamicText(Section::Right)->setUpdateFn([](String &text, Coordinate width) {
    text = String{std::format("{} cells", width), Color{fg::BrightYellow, bg::Inherited}};
});
header->dynamicText(Section::Right)->updateText();
header->setSpacePriority(Section::Right, SpacePriority::Shrink);

The line background itself comes from the active theme. This lets you change the full application color scheme without rewriting each section. HeaderLine is a thin specialization with its own theme element for header styling.

Line Layout Rules

Line surfaces always use a fixed height of one row and resolve sections in this order:

  • left first

  • right second

  • middle last inside the remaining gap

The sectionWidth() value is the current width assigned to the child text surface. It excludes the section’s own left and right margins.

Sections with empty text reserve no width and their margins are ignored. This means a header with only a left section can naturally use the whole line, while a middle section shrinks only when visible left or right sections actually consume space.

Margins only affect the horizontal layout:

  • the left section uses its left margin as an inset from the line edge and its right margin as spacing towards the center

  • the middle section uses left and right margins as breathing room around the centered text

  • the right section uses its right margin as an inset from the line edge and its left margin as spacing towards the center

The managed DynamicText children also honor horizontal margins and padding from the line’s Text theme part. Top and bottom values are ignored because these are strict one-line surfaces.

Space priority is evaluated after the width budget is known:

  • Keep preserves the section’s preferred width even if sections overlap.

  • Shrink assigns no more than the available width and lets DynamicText crop the visible text.

  • Hide omits the section entirely when it does not fit, releasing both text width and margins.

Use dynamicText() when you need the full text-surface API, for example to install an update callback, schedule periodic updates, or adjust alignment.

Dynamic Text, Action Help, and Footers

DynamicText is a one-line text surface for compact labels whose content can update on resize or every repaint. It is useful for status text that does not need three sections.

ActionHelp finds the nearest page, collects enabled actions from the focused surface chain, deduplicates shared ActionPtr instances, and renders the available keyboard help. The spaces between key brackets, key labels, and action names come from collapsed horizontal margins on the Key, KeyBracket, and Text theme parts. FooterLine combines a left-side DynamicText with right-side action help and can temporarily overlay centered status messages.

auto footer = ui::FooterLine::create();
footer->leftText()->setUpdateFn([](String &text, Coordinate width) {
    text = String{std::format("width {}", width)};
});
footer->leftText()->updateText();
footer->displayMessage(
    "Saved",
    CharStyle{Color{fg::BrightWhite, bg::Blue}},
    std::chrono::milliseconds{1500});

Messages are queued. A timeout of 0ms keeps the current message visible until hideMessage() is called, then the next queued message is shown.

Action Buttons

Button is a compact focusable view for one Action. It displays the action name and main key, triggers on Enter and Space while focused, and still lets the action key dispatch through the normal focus chain.

Reference

class Panel : public erbsland::cterm::ui::Surface

A fill surface that paints a themed background behind its child surfaces.

Subclassed by erbsland::cterm::ui::surface::DynamicTextLine, erbsland::cterm::ui::surface::FooterLine

Public Functions

explicit Panel(ProtectedTag) noexcept

Create a panel surface.

virtual bool isOpaque() const noexcept override

Test if this surface paints every cell in its rectangle.

Returns:

true if the surface is opaque.

virtual void onPaint(WritableBuffer &buffer, const PaintContext &context) noexcept override

Paint this surface into the target buffer.

Parameters:

  • buffer – The target buffer.

  • context – The paint context for the current paint pass.

Public Static Functions

static PanelPtr create()

Create a panel that grows to fill free space in layouts.

Returns:

The new panel instance.

class TextBox : public erbsland::cterm::ui::Surface

A surface that renders one string using alignment and wrapping rules.

Public Functions

TextBox(String text, Alignment alignment, ProtectedTag)

Create a text box for the given text and alignment.

Parameters:

  • text – The initial text to render.

  • alignment – The alignment inside the allocated rectangle.

const String &text() const noexcept

Get the current text content.

Returns:

The text rendered by this text box.

void setText(String text)

Replace the current text content.

Parameters:

text – The new text to render.

Alignment alignment() const noexcept

Get the text alignment.

void setAlignment(Alignment alignment)

Set the text alignment.

Parameters:

alignment – The new text alignment.

std::optional<Coordinate> preferredLineWidth() const noexcept

Access the preferred content line width.

Returns:

The preferred line width, or an empty value for natural unwrapped width.

void setPreferredLineWidth(std::optional<Coordinate> width)

Replace the preferred content line width.

Parameters:

width – The preferred line width, or an empty value for natural unwrapped width.

virtual LayoutMetrics onMeasure(MeasureScope &scope, const LayoutProposal &proposal) noexcept override

Measure this text box for a proposed width.

virtual void onPaint(WritableBuffer &buffer, const PaintContext &context) noexcept override

Render the text into the target rectangle.

Parameters:

  • buffer – The destination buffer.

  • context – The paint context.

Public Static Functions

static TextBoxPtr create(String text, Alignment alignment = Alignment::TopLeft)

Create a text box from a terminal string.

Parameters:

  • text – The initial text to render.

  • alignment – The alignment inside the allocated rectangle.

Returns:

The new text box instance.

static TextBoxPtr create(std::string_view text, Alignment alignment = Alignment::TopLeft)

Create a text box from UTF-8 text.

Parameters:

  • text – The initial text to render.

  • alignment – The alignment inside the allocated rectangle. Invalid UTF-8 bytes are replaced with the Unicode replacement character.

Returns:

The new text box instance.

class AbstractScrollArea : public erbsland::cterm::ui::Surface, protected erbsland::cterm::ui::ExclusiveSurfaceManager

Shared base for scrollable surfaces that paint custom content into a viewport.

Subclassed by erbsland::cterm::ui::layout::ScrollArea, erbsland::cterm::ui::surface::ScrollingBufferView

Public Functions

explicit AbstractScrollArea(ProtectedTag) noexcept

Create a scroll area base with grow/fill geometry.

Position scrollOffset() const noexcept

Get the current scroll offset.

Returns:

The clamped scroll offset.

void setScrollOffset(Position scrollOffset) noexcept

Replace the scroll offset.

Parameters:

scrollOffset – The new scroll offset.

void scrollBy(Position delta) noexcept

Scroll by the given delta.

Parameters:

delta – The scroll delta.

void scrollUp(Coordinate count = 1) noexcept

Scroll one or more rows up.

Parameters:

count – The number of rows.

void scrollDown(Coordinate count = 1) noexcept

Scroll one or more rows down.

Parameters:

count – The number of rows.

void scrollLeft(Coordinate count = 1) noexcept

Scroll one or more columns left.

Parameters:

count – The number of columns.

void scrollRight(Coordinate count = 1) noexcept

Scroll one or more columns right.

Parameters:

count – The number of columns.

void pageUp() noexcept

Scroll one page up.

void pageDown() noexcept

Scroll one page down.

void pageLeft() noexcept

Scroll one page left.

void pageRight() noexcept

Scroll one page right.

void scrollToTop() noexcept

Scroll to the top edge.

void scrollToBottom() noexcept

Scroll to the bottom edge.

void scrollToLeftEdge() noexcept

Scroll to the left edge.

void scrollToRightEdge() noexcept

Scroll to the right edge.

void scrollIntoView(Rectangle contentRect) noexcept

Scroll by the smallest amount needed to make a content rectangle visible.

Parameters:

contentRect – The rectangle in content coordinates.

ScrollBarMode scrollBarMode(Orientation orientation) const noexcept

Get one scroll bar mode.

Parameters:

orientation – The scroll bar orientation.

Returns:

The configured scroll bar mode.

void setScrollBarMode(Orientation orientation, ScrollBarMode mode) noexcept

Replace one scroll bar mode.

Parameters:

  • orientation – The scroll bar orientation.

  • mode – The new scroll bar mode.

const HorizontalScrollBarPtr &horizontalScrollBar() const noexcept

Access the horizontal scroll bar.

Returns:

The horizontal scroll bar.

const VerticalScrollBarPtr &verticalScrollBar() const noexcept

Access the vertical scroll bar.

Returns:

The vertical scroll bar.

const ScrollCornerPtr &scrollCorner() const noexcept

Access the scroll corner.

Returns:

The scroll corner.

Size contentSize() const noexcept

Get the current content size.

Returns:

The content size used for scrolling.

Rectangle viewportRect() const noexcept

Get the current viewport rectangle.

Returns:

The viewport rectangle in this surface’s local coordinates.

Rectangle visibleContentRect() const noexcept

Get the visible content rectangle.

Returns:

The visible rectangle in content coordinates.

virtual void onLayout(LayoutScope &scope) noexcept override

Layout direct children within this surface.

Parameters:

scope – Layout access for measuring and placing child surfaces.

virtual void onPaint(WritableBuffer &buffer, const PaintContext &context) noexcept override

Paint this surface into the target buffer.

Parameters:

  • buffer – The target buffer.

  • context – The paint context for the current paint pass.

class ScrollingBufferView : public erbsland::cterm::ui::surface::AbstractScrollArea

A surface that renders a scrollable viewport into one readable buffer.

Public Functions

explicit ScrollingBufferView(ReadableBufferPtr source, ProtectedTag) noexcept

Create a scrolling buffer view.

Parameters:

source – The optional source buffer.

const ReadableBufferPtr &source() const noexcept

Access the source buffer.

Returns:

The current source buffer.

void setSource(ReadableBufferPtr source) noexcept

Replace the source buffer and clamp the stored view offset to the new content.

Parameters:

source – The new source buffer.

bool showCropCharacters() const noexcept

Test whether crop indicator characters are shown.

Returns:

true if crop indicator characters are shown.

void setShowCropCharacters(bool show) noexcept

Enable or disable crop indicator characters.

Parameters:

show – true to show crop indicator characters.

Char cropCharacter(Direction direction) const noexcept

Get one crop indicator character.

Parameters:

direction – The crop direction to query.

Returns:

The configured crop indicator character.

void setCropCharacter(Direction direction, Char character) noexcept

Replace one crop indicator character.

Parameters:

  • direction – The crop direction to update.

  • character – The new crop indicator character.

Public Static Functions

static ScrollingBufferViewPtr create(ReadableBufferPtr source = {})

Create a scrolling buffer view for one source buffer.

Parameters:

source – The optional source buffer.

Returns:

The new scrolling buffer view.

class AbstractScrollBar : public erbsland::cterm::ui::Surface

Shared base class for one-dimensional scroll bar surfaces.

The scroll bar is a purely visual indicator for a visible region inside a larger scroll region.

Subclassed by erbsland::cterm::ui::surface::HorizontalScrollBar, erbsland::cterm::ui::surface::VerticalScrollBar

Public Functions

explicit AbstractScrollBar(Orientation orientation, const LayoutMetrics &layoutSize, ProtectedTag) noexcept

Create a scroll bar with explicit layout metrics and orientation.

Parameters:

  • orientation – The scroll bar orientation.

  • layoutSize – The initial layout metrics.

IndexRange scrollRegion() const noexcept

Get the total scrollable region.

Returns:

The configured scroll region.

void setScrollRegion(IndexRange scrollRegion) noexcept

Replace the total scrollable region.

Parameters:

scrollRegion – The new scroll region.

IndexRange visibleRegion() const noexcept

Get the currently visible region.

Returns:

The configured visible region.

void setVisibleRegion(IndexRange visibleRegion) noexcept

Replace the currently visible region.

Parameters:

visibleRegion – The new visible region.

virtual bool isOpaque() const noexcept override

Test if this surface paints every cell in its rectangle.

Returns:

true if the surface is opaque.

virtual void onPaint(WritableBuffer &buffer, const PaintContext &context) noexcept override

Paint this surface into the target buffer.

Parameters:

  • buffer – The target buffer.

  • context – The paint context for the current paint pass.

class HorizontalScrollBar : public erbsland::cterm::ui::surface::AbstractScrollBar

A one-row horizontal scroll bar that grows along its width.

Public Functions

explicit HorizontalScrollBar(ProtectedTag) noexcept

Create a horizontal scroll bar.

Public Static Functions

static HorizontalScrollBarPtr create()

Create a horizontal scroll bar.

Returns:

The new horizontal scroll bar.

class VerticalScrollBar : public erbsland::cterm::ui::surface::AbstractScrollBar

A one-column vertical scroll bar that grows along its height.

Public Functions

explicit VerticalScrollBar(ProtectedTag) noexcept

Create a vertical scroll bar.

Public Static Functions

static VerticalScrollBarPtr create()

Create a vertical scroll bar.

Returns:

The new vertical scroll bar.

class ScrollCorner : public erbsland::cterm::ui::Surface

The one-cell fill surface where horizontal and vertical scroll bars meet.

Public Functions

explicit ScrollCorner(ProtectedTag) noexcept

Create a scroll corner.

const Char &fill() const noexcept

Get the fill character.

Returns:

The fill character.

void setFill(Char fill) noexcept

Replace the fill character.

Parameters:

fill – The new fill character.

virtual bool isOpaque() const noexcept override

Test if this surface paints every cell in its rectangle.

Returns:

true if the surface is opaque.

virtual void onPaint(WritableBuffer &buffer, const PaintContext &context) noexcept override

Paint this surface into the target buffer.

Parameters:

  • buffer – The target buffer.

  • context – The paint context for the current paint pass.

Public Static Functions

static ScrollCornerPtr create()

Create a scroll corner.

Returns:

The new scroll corner.

class DynamicTextLine : public erbsland::cterm::ui::surface::Panel, protected erbsland::cterm::ui::ExclusiveSurfaceManager

A composed one-line surface with left, middle, and right dynamic text sections.

Subclassed by erbsland::cterm::ui::surface::HeaderLine

Public Types

enum class Section : uint8_t

The available logical sections of the line.

Values:

enumerator Left

The section anchored to the left edge.

enumerator Middle

The section centered inside the remaining gap.

enumerator Right

The section anchored to the right edge.

enum class SpacePriority : uint8_t

Layout priority for keeping, shrinking, or hiding one section.

Values:

enumerator Keep

Keep the preferred width even if sections overlap.

enumerator Shrink

Shrink the assigned width to the available budget.

enumerator Hide

Hide the section when it does not fit into the available budget.

Public Functions

explicit DynamicTextLine(ProtectedTag) noexcept

Create a dynamic text line with fixed height 1.

const DynamicTextPtr &dynamicText(Section section) const noexcept

Access the dynamic text surface for one section.

Parameters:

section – The section to query.

Returns:

The dynamic text surface.

const String &text(Section section) const noexcept

Get the text for one section.

Parameters:

section – The section to query.

Returns:

The text for the section.

void setText(Section section, String text)

Replace the text for one section.

Parameters:

  • section – The section to update.

  • text – The new section text.

void setText(Section section, std::string_view text)

Replace the text for one section from UTF-8 text.

Parameters:

  • section – The section to update.

  • text – The new section text.

void clearText(Section section)

Clear the text for one section.

Parameters:

section – The section to clear.

void setMargins(Section section, Margins margins) noexcept

Replace the margins for one section.

Parameters:

  • section – The section to update.

  • margins – The new section margins.

Margins margins(Section section) const noexcept

Get the margins for one section.

Parameters:

section – The section to query.

Returns:

The configured section margins.

void setSpacePriority(Section section, SpacePriority priority) noexcept

Replace the space priority for one section.

Parameters:

  • section – The section to update.

  • priority – The new section space priority.

SpacePriority spacePriority(Section section) const noexcept

Get the space priority for one section.

Parameters:

section – The section to query.

Returns:

The configured section space priority.

Coordinate sectionWidth(Section section) const noexcept

Get the current width assigned to one section, excluding margins.

Parameters:

section – The section to query.

Returns:

The assigned width in terminal cells.

virtual void onLayout(LayoutScope &scope) noexcept override

Layout direct children within this surface.

Parameters:

scope – Layout access for measuring and placing child surfaces.

Public Static Functions

static DynamicTextLinePtr create()

Create a dynamic text line.

Returns:

The new dynamic text line.

class HeaderLine : public erbsland::cterm::ui::surface::DynamicTextLine

A themed header line.

Public Functions

explicit HeaderLine(ProtectedTag) noexcept

Create a header line with fixed height 1.

Public Static Functions

static HeaderLinePtr create()

Create a header line.

Returns:

The new header line.

class DynamicText : public erbsland::cterm::ui::surface::StaticText

A one-line text surface with optional manual or scheduled updates.

Public Types

using milliseconds = std::chrono::milliseconds

Duration type used for the automatic update interval.

using UpdateFn = std::function<void(String &text, Coordinate availableWidth)>

Callback type used to update the text.

Public Functions

DynamicText(String text, Alignment alignment, ProtectedTag)

Create dynamic text with an initial text and alignment.

Parameters:

  • text – The initial text.

  • alignment – The alignment used when painting.

void setUpdateFn(UpdateFn updateFn)

Replace the update function.

Parameters:

updateFn – The new update function.

void clearUpdateFn() noexcept

Remove the update function.

void updateText()

Update the text once by calling the update function.

inline milliseconds updateInterval() const noexcept

Get the automatic update interval.

Returns:

A non-positive duration for manual updates.

void setUpdateInterval(milliseconds interval)

Replace the automatic update interval.

A value less than or equal to zero disables automatic updates.

Parameters:

interval – The new interval.

Public Static Functions

static DynamicTextPtr create(String text = {}, Alignment alignment = Alignment::TopLeft)

Create dynamic text with an initial terminal string.

Parameters:

  • text – The initial text.

  • alignment – The alignment used when painting.

Returns:

The new dynamic text.

static DynamicTextPtr create(std::string_view text, Alignment alignment = Alignment::TopLeft)

Create dynamic text with an initial UTF-8 text.

Parameters:

  • text – The initial text.

  • alignment – The alignment used when painting.

Returns:

The new dynamic text.

class ActionHelp : public erbsland::cterm::ui::Surface

A one-line surface that renders the currently available keyboard actions for the focused surface chain.

Public Functions

explicit ActionHelp(ProtectedTag) noexcept

Create an action-help surface.

std::vector<ActionPtr> collectActions()

Collect currently displayable actions for the nearest page.

Returns:

The sorted and deduplicated actions.

String renderHelpText(const PaintContext &context, Coordinate width)

Render currently displayable actions for a fixed width.

Parameters:

  • context – The current paint context.

  • width – The available width.

Returns:

The rendered help line.

virtual void onPaint(WritableBuffer &buffer, const PaintContext &context) noexcept override

Paint this surface into the target buffer.

Parameters:

  • buffer – The target buffer.

  • context – The paint context for the current paint pass.

Public Static Functions

static ActionHelpPtr create()

Create an action-help surface.

Returns:

The new action-help surface.

class Button : public erbsland::cterm::ui::Surface

A focusable action view rendered as a compact terminal button.

Public Functions

explicit Button(ButtonActionPtr action, ProtectedTag)

Create a button for an action.

Parameters:

action – The action represented by the button.

const ButtonActionPtr &action() const noexcept

Access the represented action.

bool isEnabled() const noexcept

Test if the represented action is enabled.

virtual LayoutMetrics onMeasure(MeasureScope &scope, const LayoutProposal &proposal) noexcept override

Measure this surface for a proposed size.

The returned layout sizes describe the margin-free content rectangle. The optional margins in the returned metrics are recommendations for the parent layout and are not included in these sizes.

Parameters:

  • scope – Measurement access for child surfaces.

  • proposal – The proposed size.

Returns:

The measured layout metrics.

virtual void onPaint(WritableBuffer &buffer, const PaintContext &context) noexcept override

Paint this surface into the target buffer.

Parameters:

  • buffer – The target buffer.

  • context – The paint context for the current paint pass.

virtual void onKeyPress(KeyPressEvent &keyPressEvent) noexcept override

Handle a key press event.

This is the low-level event handler for key press events. If a surface handles a key press event, it should mark it as handled.

Parameters:

keyPressEvent – The key press event to handle.

Public Static Functions

static ButtonPtr create(ButtonActionPtr action)

Create a button for an action.

Parameters:

action – The action represented by the button.

Returns:

The new button.

class FooterLine : public erbsland::cterm::ui::surface::Panel, protected erbsland::cterm::ui::ExclusiveSurfaceManager

A themed footer line with dynamic text, action help, and queued overlay messages.

Public Functions

explicit FooterLine(ProtectedTag) noexcept

Create a footer line with fixed height 1.

inline const DynamicTextPtr &leftText() const noexcept

Access the dynamic text surface on the left side.

inline const ActionHelpPtr &actionHelp() const noexcept

Access the action-help surface on the right side.

void setText(String text)

Replace the static/dynamic left-side text.

Parameters:

text – The new text.

void setText(std::string_view text)

Replace the static/dynamic left-side text from UTF-8.

Parameters:

text – The new text.

void displayMessage(String message, CharStyle style = {}, milliseconds timeout = {})

Display a queued overlay message.

A timeout of 0ms keeps the message visible until hideMessage() is called.

Parameters:

  • message – The message text.

  • style – The message style.

  • timeout – The display timeout.

void displayMessage(std::string_view message, CharStyle style = {}, milliseconds timeout = {})

Display a queued overlay message from UTF-8 text.

Parameters:

  • message – The message text.

  • style – The message style.

  • timeout – The display timeout.

void hideMessage()

Hide the current overlay message and show the next queued message if present.

virtual void onLayout(LayoutScope &scope) noexcept override

Layout direct children within this surface.

Parameters:

scope – Layout access for measuring and placing child surfaces.

Public Static Functions

static FooterLinePtr create()

Create a footer line.

Returns:

The new footer line.