Navigator

#include <Navigator.hpp>

Inherits: Widget

A screen navigation widget that manages a stack of screens.

Navigator implements a stack-based navigation pattern, allowing you to push, pop, and replace screens. It maintains a stack of widgets and always displays the topmost one. This is useful for implementing multi-screen applications with back button support.

Example Usage:

auto nav = std::make_shared<Navigator>();
auto home = std::make_shared<HomeScreen>();
nav->push(home);

// When user clicks a button to go to another screen:
auto details = std::make_shared<DetailsScreen>();
nav->push(details);

// When user clicks back:
nav->pop();

Public Attributes

Return	Name	Description
`std::function< void(std::shared_ptr< Widget >)>`	`onPush`	Callback fired when a screen is pushed onto the stack.
`std::function< void(std::shared_ptr< Widget >)>`	`onPop`	Callback fired when a screen is popped from the stack.
`std::function< void(std::shared_ptr< Widget >)>`	`onReplace`	Callback fired when a screen is replaced.

onPush

std::function< void(std::shared_ptr< Widget >)> onPush

Callback fired when a screen is pushed onto the stack.

Parameters

screen The widget that was pushed.

onPop

std::function< void(std::shared_ptr< Widget >)> onPop

Callback fired when a screen is popped from the stack.

Parameters

screen The widget that was popped.

onReplace

std::function< void(std::shared_ptr< Widget >)> onReplace

Callback fired when a screen is replaced.

Parameters

screen The widget that replaced the previous one.

Public Methods

Return	Name	Description
`void`	`push`	Pushes a widget onto the navigation stack.
`void`	`pop`	Pops the current widget from the stack.
`void`	`replace`	Replaces the current widget with a new one.
`std::shared_ptr< Widget >`	`current` `const`	Returns the currently active widget.
`bool`	`canPop` `const` `inline`	Checks if the stack can be popped.
`int`	`depth` `const` `inline`	Returns the current depth of the navigation stack.
`core::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`	Handles an input event.
`std::vector< std::shared_ptr< Widget > >`	`getChildren` `virtual` `const` `inline`	Returns this widget’s children.

push

void push(std::shared_ptr< Widget > screen)

Pushes a widget onto the navigation stack.

Makes the given widget the current active screen. The previous screen remains on the stack and can be returned to via pop(). Triggers the onPush callback.

Parameters

screen The widget to push onto the stack. Must not be null.

pop

void pop()

Pops the current widget from the stack.

Removes the topmost widget from the stack and displays the one beneath it. Does nothing if the stack has only one widget (cannot pop the root). Triggers the onPop callback.

replace

void replace(std::shared_ptr< Widget > screen)

Replaces the current widget with a new one.

Removes the topmost widget and pushes a new one in its place. This is useful for transitions that don’t preserve history. Triggers the onReplace callback.

Parameters

screen The widget to replace the current one with. Must not be null.

current

const

std::shared_ptr< Widget > current() const

Returns the currently active widget.

Returns

A shared pointer to the topmost widget on the stack, or nullptr if the stack is empty.

canPop

const inline

inline bool canPop() const

Checks if the stack can be popped.

Returns true if there is more than one widget on the stack. Always returns false if there is only one (root) widget.

Returns

True if pop() would succeed, false otherwise.

depth

const inline

inline int depth() const

Returns the current depth of the navigation stack.

Returns

The number of widgets currently on the stack.

measure

virtual

virtual core::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

virtual bool onEvent(const core::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

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)

Private Attributes

Return	Name	Description
`std::vector< std::shared_ptr< Widget > >`	`stack`

stack

std::vector< std::shared_ptr< Widget > > stack