The common interface for all UI objects. More...

#include <widget.hpp>

Inheritance diagram for ui::Widget:

Public Member Functions
	Widget (const Position &pos={0, 0}, const Alignment &align={ALIGN_LEFT, ALIGN_TOP}, const Padding &padding={0})
	The default widget constructor.

virtual void	draw () const =0
	Render the widget to the screen.

virtual void	render (bool force) const
	Recursively render this widget and any child widgets that need it.

virtual	~Widget ()
	The default widget destructor.

virtual void	update (time_t time)
	Update any internal state of the widget, and check if it needs to be re-rendered.

virtual Size	size () const =0
	Get the size of the widget.

virtual Bounds	bounds () const
	Get the rendering bounds of this widget.

void	setPosition (const Position &pos)
	Set the position of this widget.

Position	getPosition () const
	Get the position of this widget.

void	setAlign (const Alignment &align)
	Set the alignment of this widget.

void	requestRedraw ()
	Tell this widget that it needs to be re-rendered.

void	requestParentRedraw ()
	Tell the parent widget that it needs to be re-rendered.

bool	needsRedraw () const
	Check if this widget has requested to be redrawn.

virtual void	drawDone ()
	Reset any state variables after rendering has finished.

void	setParent (Widget *parent)
	Set the parent widget.

Bounds	parentBounds () const
	Get the bounds of the parent widget, if any.

void	onpress (std::function< void(Widget &, const Event &)> callback) override
	Register a touchscreen event handler that triggers on press.

void	onblur (std::function< void(Widget &, const Event &)> callback) override
	Register a touchscreen event handler that triggers when the widget stops being pressed.

void	onhold (std::function< void(Widget &, const Event &, time_t)> callback) override
	Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

void	onrelease (std::function< void(Widget &, const Event &)> callback) override
	Register a touchscreen event handler that triggers on release.

void	click ()
	Manually trigger the onrelease event handler.

void	press ()
	Manually trigger the onpress event handler.

void	blur ()
	Manually trigger the onblur event handler.

void	release ()
	Manually trigger the onrelease event handler.

void	hold (time_t time)
	Manually trigger the onhold event handler.

virtual bool	handleEvent (Event &event)
	Handle events from the touchscreen.

virtual void	drawBoundingBox (time_t time) const
	Render the bounding box of this and any child widgets.

virtual Widget *	getWidgetById (id_t id) noexcept
	Get the first widget (this or any children) that has the given ID.

Public Member Functions inherited from ui::EventHandlers< Widget >
void	onpress (std::function< void(Widget &)> callback)
	Register a touchscreen event handler that triggers on press.

void	onpress (std::function< void(const Event &)> callback)
	Register a touchscreen event handler that triggers on press.

void	onpress (std::function< void()> callback)
	Register a touchscreen event handler that triggers on press.

void	onrelease (std::function< void(Widget &)> callback)
	Register a touchscreen event handler that triggers when the widget stops being pressed.

void	onrelease (std::function< void(const Event &)> callback)
	Register a touchscreen event handler that triggers when the widget stops being pressed.

void	onrelease (std::function< void()> callback)
	Register a touchscreen event handler that triggers when the widget stops being pressed.

void	onblur (std::function< void(Widget &)> callback)
	Register a touchscreen event handler that triggers when the widget stops being pressed.

void	onblur (std::function< void(const Event &)> callback)
	Register a touchscreen event handler that triggers when the widget stops being pressed.

void	onblur (std::function< void()> callback)
	Register a touchscreen event handler that triggers when the widget stops being pressed.

void	onhold (std::function< void(Widget &, time_t)> callback)
	Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

void	onhold (std::function< void(const Event &, time_t)> callback)
	Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

void	onhold (std::function< void(time_t)> callback)
	Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

void	onhold (std::function< void(Widget &)> callback)
	Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

void	onhold (std::function< void(const Event &)> callback)
	Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

void	onhold (std::function< void()> callback)
	Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

void	onclick (std::function< void(Widget &)> callback)
	Register a touchscreen event handler that triggers on release.

void	onclick (std::function< void(const Event &)> callback)
	Register a touchscreen event handler that triggers on release.

void	onclick (std::function< void()> callback)
	Register a touchscreen event handler that triggers on release.

Public Member Functions inherited from ui::CoreEventHandlers< T >
virtual void	onpress (std::function< void(T &, const Event &)> callback)=0
	Register a touchscreen event handler that triggers on press.

virtual void	onrelease (std::function< void(T &, const Event &)> callback)=0
	Register a touchscreen event handler that triggers when the widget stops being pressed.

virtual void	onblur (std::function< void(T &, const Event &)> callback)=0
	Register a touchscreen event handler that triggers when the widget stops being pressed.

virtual void	onhold (std::function< void(T &, const Event &, time_t)> callback)=0
	Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

void	onclick (std::function< void(T &, const Event &)> callback)
	Register a touchscreen event handler that triggers on release.

Public Attributes
id_t	id
	An optional (usually unique) identifier that can be used to search for this widget.

Protected Attributes
Padding	padding
	The padding that will be applied to any child widgets.

bool	redrawSelf
	If true, force a redraw of this widget and any child widgets.

Detailed Description

The common interface for all UI objects.

Constructor & Destructor Documentation

◆ Widget()

ui::Widget::Widget	(	const Position &	pos = `{0, 0}`,
		const Alignment &	align = `{ALIGN_LEFT, ALIGN_TOP}`,
		const Padding &	padding = `{0}`
	)

The default widget constructor.

Parameters

pos	The position of the widget relative to the parent.
align	The alignment of the widget relative to the parent.
padding	The padding to apply to any child widgets.

Member Function Documentation

◆ bounds()

virtual Bounds ui::Widget::bounds ( ) const

virtual

Get the rendering bounds of this widget.

Returns: The bounds that this widget will render in.

Warning: This value may be based on the size of the parent widget, and so should never refer to the size of any child widgets!

Reimplemented in ui::Blink, ui::Body, and ui::Box.

◆ draw()

virtual void ui::Widget::draw ( ) const

pure virtual

Render the widget to the screen.

This only gets called when widgets indicate that a redraw is needed of either themselves or their parents. Widgets that implement this method should only render graphics specific to this widget, not any children.

Implemented in ui::Blink, ui::Body, ui::Box, ui::MultiChildWidget, ui::Image, ui::Input, ui::Panel, and ui::Text.

◆ drawBoundingBox()

virtual void ui::Widget::drawBoundingBox ( time_t time ) const

virtual

Render the bounding box of this and any child widgets.

Note: This member function is only available in debug builds.

Reimplemented in ui::MultiChildWidget, and ui::SingleChildWidget.

◆ drawDone()

virtual void ui::Widget::drawDone ( )

virtual

Reset any state variables after rendering has finished.

Reimplemented in ui::Blink, ui::MultiChildWidget, ui::SingleChildWidget, and ui::Panel.

◆ getPosition()

Position ui::Widget::getPosition ( ) const

inline

Get the position of this widget.

Returns: The relative position of this widget on its parent.

◆ getWidgetById()

virtual Widget * ui::Widget::getWidgetById ( id_t id )

virtualnoexcept

Get the first widget (this or any children) that has the given ID.

An ID is expected to be a unique, typically non-zero value. To generate an id, you can either call ui::id("some text"), or (for constant strings only), "some text"_id.

Parameters

id	The unique identifier of the widget.

Returns: A pointer to the widget, or nullptr if not found.

Reimplemented in ui::MultiChildWidget, and ui::SingleChildWidget.

◆ handleEvent()

virtual bool ui::Widget::handleEvent ( Event & event )

virtual

Handle events from the touchscreen.

Parameters

event The touch event info.

Returns: True if this widget was within the event bounds, false otherwise.

Reimplemented in ui::MultiChildWidget, and ui::SingleChildWidget.

◆ hold()

void ui::Widget::hold ( time_t time )

Manually trigger the onhold event handler.

Parameters

time	The number of milliseconds that the widget has been "held".

◆ needsRedraw()

bool ui::Widget::needsRedraw ( ) const

inline

Check if this widget has requested to be redrawn.

Returns: True if this widget has requested to redraw, false otherwise.

◆ onblur()

void ui::Widget::onblur ( std::function< void(Widget &, const Event &)> callback )

override

Register a touchscreen event handler that triggers when the widget stops being pressed.

Parameters

callback A callback function that takes a reference to the clicked widget and returns nothing.

Note: Only one event handler for each type of event (press, hold, release, blur) is allowed per widget.

◆ onhold()

void ui::Widget::onhold ( std::function< void(Widget &, const Event &, time_t)> callback )

override

Register a touchscreen event handler that repeatedly triggers when the widget is held for a while.

Parameters

callback A callback function that takes a reference to the clicked widget and the number of milliseconds that the widget has been held and returns nothing.

Note: Only one event handler for each type of event (press, hold, release, blur) is allowed per widget.

◆ onpress()

void ui::Widget::onpress ( std::function< void(Widget &, const Event &)> callback )

override

Register a touchscreen event handler that triggers on press.

Parameters

callback A callback function that takes no arguments and returns nothing.

Note: Only one event handler for each type of event (press, hold, release, blur) is allowed per widget.

◆ onrelease()

void ui::Widget::onrelease ( std::function< void(Widget &, const Event &)> callback )

override

Register a touchscreen event handler that triggers on release.

Parameters

callback A callback function that takes a reference to the clicked widget and returns nothing.

Note: Only one event handler for each type of event (press, hold, release, blur) is allowed per widget.

◆ parentBounds()

Bounds ui::Widget::parentBounds ( ) const

Get the bounds of the parent widget, if any.

Returns: The parent's bounds, or {0,0,0,0} if no parent.

◆ render()

virtual void ui::Widget::render ( bool force ) const

virtual

Recursively render this widget and any child widgets that need it.

This member function does not directly draw graphics to the screen, instead it decides whether this widget will get redrawn based on its current state and that of any parents, and if needed, redraw it and any child widgets.

Parameters

force Force this widget to redraw due to parents being redrawn.

Reimplemented in ui::Blink, ui::MultiChildWidget, and ui::SingleChildWidget.

◆ requestParentRedraw()

void ui::Widget::requestParentRedraw ( )

inline

Tell the parent widget that it needs to be re-rendered.

This is usually called by a child widget whcn it is moved or otherwise needs the parent to be redrawn.

◆ requestRedraw()

void ui::Widget::requestRedraw ( )

inline

Tell this widget that it needs to be re-rendered.

This is usually called by a child widget when it changes colors or otherwise needs its background to be redrawn, but doesn't necessarily need the parent widget to be redrawn.

◆ setAlign()

void ui::Widget::setAlign ( const Alignment & align )

inline

Set the alignment of this widget.

Parameters

align The new alignment, relative to the parent widget.

◆ setParent()

void ui::Widget::setParent ( Widget * parent )

Set the parent widget.

Parameters

parent The parent widget.

◆ setPosition()

void ui::Widget::setPosition ( const Position & pos )

inline

Set the position of this widget.

Parameters

pos	The new position, relative to the parent widget.

◆ size()

virtual Size ui::Widget::size ( ) const

pure virtual

Get the size of the widget.

Returns: The width and height of the widget in pixels.

Warning: This value may be based on the size of the child widget, and so should never refer to the size of the parent widget!

Implemented in ui::Blink, ui::Body, ui::Collection, ui::SingleChildWidget, ui::Image, ui::Panel, and ui::Text.

◆ update()

virtual void ui::Widget::update ( time_t time )

virtual

Update any internal state of the widget, and check if it needs to be re-rendered.

Parameters

time	The current time in milliseconds.

Reimplemented in ui::Column, ui::Input, ui::Row, ui::Blink, ui::Box, ui::MultiChildWidget, ui::SingleChildWidget, ui::Image, and ui::Panel.

The documentation for this class was generated from the following file:

src/ui/core/widget.hpp

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Widget()

Member Function Documentation

◆ bounds()

◆ draw()

◆ drawBoundingBox()

◆ drawDone()

◆ getPosition()

◆ getWidgetById()

◆ handleEvent()

◆ hold()

◆ needsRedraw()

◆ onblur()

◆ onhold()

◆ onpress()

◆ onrelease()

◆ parentBounds()

◆ render()

◆ requestParentRedraw()

◆ requestRedraw()

◆ setAlign()

◆ setParent()

◆ setPosition()

◆ size()

◆ update()