Set of simple widgets for the GUI

Description

This module provides widgets not composed of other widgets.

Copyright

See LICENSE.txt and AUTHORS.txt file.

http://jafma.net

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Collaboration diagram for Set of simple widgets for the GUI:

Namespaces
namespace	zxeco
	The main namespace of the library, that spans across all the zx modules.
namespace	zxeco::gui
	The namespace of the GUI companion sub-library.

Classes
class	zxeco::gui::LabelWidget
	A widget consisting only in a single-line label, with possibly control codes. More...
class	zxeco::gui::ButtonWidget
	A widget that is a button, either text or image. More...
class	zxeco::gui::SwitchWidget
	A widget that is a button with two positions that are held over time. More...
class	zxeco::gui::LineInputWidget
	A widget that shows a line for user typing. More...
class	zxeco::gui::ChoiceWidget
	A widget consisting of a number of options, for single or multiple selection. More...
class	zxeco::gui::SeparatorWidget
	A separator between adjacent widgets. More...
class	zxeco::gui::ImageWidget
	A widget consisting in just one image. More...

---

Class Documentation

zxeco::gui::LabelWidget

class zxeco::gui::LabelWidget

A widget consisting only in a single-line label, with possibly control codes.

If you need a label with fixed size and/or the possibility to navigate along it with the keyboard, use the LineInputWidget instead in non-editable mode. If you need a label with rectangular shape that in addition separates words by spaces, use a non-editable TextEditorWidget instead.

Definition at line 44 of file ZXWidgetsSimple.h.

Inheritance diagram for zxeco::gui::LabelWidget:

Collaboration diagram for zxeco::gui::LabelWidget:

Public Member Functions
	LabelWidget (ID id, const std::string &name, const std::string &initlabel, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. The initial label is copied internally. More...
const std::string &	getLabel (void) noexcept
	Return the current label text. More...
void	setLabel (const std::string &newlab)
	Change the label and redraw the widget.
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Public Member Functions inherited from zxeco::gui::Widget
	Widget (ID id, const std::string &name, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
	Widget (const Widget &)=delete
	Constructor. More...
	Widget (Widget &&)=delete
	Constructor. More...
Widget &	operator= (const Widget &)=delete
	Constructor. More...
Widget &	operator= (Widget &&)=delete
	Constructor. More...
virtual	~Widget (void)=default
	Just to activate polymorphic deletes.
std::string	idText (bool withpointer=false) const
	Return a text with the identification of this widget. More...
virtual bool	isContainer (void) const noexcept
	Return whether the widget is a container of other widgets. More...
bool	isUserContainer (void) const noexcept
	Return whether the widget is a USER-type container. More...
ID	getID (void) const noexcept
	Return the ID assigned to the widget at creation. More...
void	changeID (ID id) noexcept
	Change the ID without checking for duplicates in this widget tree. More...
const std::string &	getName (void) const noexcept
	Return the name of the widget. More...
bool	operator== (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
bool	operator!= (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
virtual std::pair< bool, const CharRect * >	hasFocusZone (void) const noexcept
	< Must return TRUE and the zone if the widget contains a focus-able zone. More...
virtual void	setWindow (Window &win) noexcept
	Set the Window where the widget is being managed. More...
virtual void	setWinColors (const WinColors &wincols) noexcept
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
const WinColors &	getWinColors (void) const noexcept
	Return the current window colors. More...
virtual void	setUDGs (const uint8_t *udgs)
	Assign an UDG character set for the widget drawing (do not copy them). More...
const uint8_t *	getUDGs (void)
	Return the current UDGs. *‍/. More...
virtual void	setTooltip (const std::string &ttt)
	Must return a text with the name of the class. More...
const std::string &	getTooltip (void) const noexcept
	Return the tooltip for the widget. More...
void	setParent (Widget *parent)
	Sets the parent of the widget to PARENT, that must outlive it. More...
Widget *	getParent (void) const noexcept
	Return a pointer to the parent of the widget, or nullptr if none. More...
Widget *	getRoot (void)
	Return a pointer to the root widget of the tree. More...
bool	isRoot (void) const noexcept
	Return TRUE if this widget is the root of the tree. More...
bool	isDescendantOf (Widget &w) const
	Return TRUE if this is W or a descendant of W. More...
Widget *	searchID (ID id) const
	Search the first appearance of the given ID in this and its descendants. More...
ID	maxUsedID (void) const
	Search in this widget and its descendants the maximum ID used. More...
TravResult	traverse (const TraverseObserver &obs)
	Traverse this widget and its descendants, calling OBS on each one. More...
TravResult	revTraverse (const TraverseObserver &obs)
	Traverse this widget and its ascendants, calling OBS on each one. More...
void	setVisibility (bool visible=true)
	Set the desired visibility of the widget. More...
void	setVisibilityNoRedrawing (bool vis) noexcept
	Set the widget visibility without redrawing or modifying focus. More...
bool	getVisibility (void) const noexcept
	Get current visibility of the widget, considering also its parents. More...
void	setEnabled (bool enabled=true)
	Set whether the widget is enabld or disabld; drawRaw() widget if changd. More...
bool	getEnabled (void) const noexcept
	Get current enabled state of the widget, considering its parents. More...
bool	isFocusable (bool drawntoo=true) const
	Return TRUE if the widget is focusable now. More...
bool	isInFocusPath (void) const noexcept
	Return TRUE if the widget is in the path from root to the leaf focused. More...
bool	isLeafFocused (void) const noexcept
	< Return TRUE if it is in the focus path and it is the leaf of that path. More...
Widget *	whoIsFocused (void)
	Get the leaf focused widget in the tree, or nullptr if none. More...
void	acquireFocus (const PointingStatus *m=nullptr)
	Give the focus to this widget and quit it from the current focused one. More...
void	releaseFocus (void)
	Quit focus from this leaf widget or below it; no one acquires it. More...
void	drawAll (const CharRect &rect)
	Calculate and set the placement of all widgets within RECT and draw'em. More...
Widget *	redrawAll (void)
	Recalculate, place and redraw all widgets that have changed in the tree. More...
void	redrawMe (void)
	Recalculate and place all widgets in the tree forcing this to be drawn. More...
void	drawMe (void)
	Just force to draw the widget in the current drawing zone. More...
const AreaFitting &	fittingNeeds (void) const noexcept
	< Return the last calculation of the fitting needs of the widget. More...
virtual Widget *	setDrawingZone (const CharRect &zone)
	Set the final drawing zone for the widget and the aligned one. More...
const CharRect &	drawingZone (void) const noexcept
	< Get the drawing zone decided for the widget within the global screen. More...
const CharRect &	alignedDrawingZone (void) const noexcept
	< Get the part of the drawing zone that is already aligned. More...
virtual void	moveDrawingZones (IntDist incx, IntDist incy) noexcept
	Move the drawing and aligned zones corners by those increments. More...
bool	drawn (void) const noexcept
	Return TRUE if the widget has already been drawn in current dimensions. More...
void	undraw (void) noexcept
	Method for external agents (e.g., Windows) to mark the widget undrawn. More...
void	setExplanations (bool setit=true) noexcept
	< Set/unset the generation of explanations when calculating drawing. More...
bool	getExplanations (void) const noexcept
	Return the current status of drawing explanations. More...
std::string	traceOfDrawing (bool withoutprivate=true) const
	< Return an explanation with the drawing status of this and child widgets More...
virtual void	traceOfDrawingRecursive (size_t level, std::stringstream &ss, bool withoutprivate=true) const
	Same as traceOfDrawing() but indicating the depth level and using SS. More...
virtual ChainEventResult	chainEvent (const EventData &data)
	Deal with the event at this widget and its descendants (if container). More...
virtual void	setCallback (const CallbackRout &callback=NullCallback)
	Deal with the event at this widget and its descendants (if container). More...
const CallbackRout &	getCallback (void) const noexcept
	Get the current callback routine. More...
void	addCallback (const CallbackRout &cbk)
	Add callback CBK to the end of the current callback routine. More...

Additional Inherited Members
Public Types inherited from zxeco::gui::Widget
enum class	TravResult { FINISH_OK , FINISH_FAIL , BACKTRACK , CONTINUE }
	Possible results of observer when traversing widgets in the widget tree. More...
using	ID = int
	A numeric ID associated to the widget. More...
using	Ptr = std::shared_ptr< Widget >
	A polymorphic ptr to a widget. More...
using	TraverseObserver = std::function< TravResult(Widget &) >
enum class	HorAlign { LEFT , RIGHT , CENTER }
	Horizontal alignment of widgets within the areas of their containers. More...
enum class	VertAlign { TOP , BOTTOM , MIDDLE }
	Vertical alignment of widgets within the areas of their containers. More...
enum class	EventType { MOUSE , KEYBOARD , FOCUS }
	Kinds of events that the widgets may process from the graphical environ. More...
enum class	SubEvType {   MOUSE_MOVE , MOUSE_CLICK , MOUSE_UNCLICK , MOUSE_WHEEL ,   KEYB_PRESS , KEYB_UNPRESS , KEYB_TEXT , FOCUS_GOT ,   FOCUS_LOST }
	Concrete events for each event kind. More...
using	CallbackRout = std::function< bool(Widget &, const CallbackParms &)>
Static Public Member Functions inherited from zxeco::gui::Widget
static void	addGlobalTraces (Trace::Type traces) noexcept
	< Add TRACES to the currently active traces (initially none). More...
static void	delGlobalTraces (Trace::Type traces) noexcept
	< Delete the given traces from the current active ones. More...
static Trace::Type	isTracing (Trace::Type traces) noexcept
	< Return a non-zero value if any of TRACES is currently active. More...
static void	printTrace (Trace::Type trace, const std::string &tr)
	Put TR in console as a trace, with a mark indicating TRACE.
static void	printIfTrace (Trace::Type trace, const std::string &tr)
	The same as printTrace() but only print if any of TRACE is active. More...
Static Public Attributes inherited from zxeco::gui::Widget
static const CallbackRout	NullCallback
	Callback routine that does nothing. More...
static const std::string	kTraceBegin
	< Add TRACES to the currently active traces (initially none). More...
static const std::string	kTraceEnd
	< Add TRACES to the currently active traces (initially none). More...
Protected Member Functions inherited from zxeco::gui::Widget
virtual void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
virtual int	processEvent (const EventData &evdata, Widget *who)
void	addLineToExplanation (const std::string &line)
	Add LINE to the existing explanation in fitting_needs_. More...
Protected Attributes inherited from zxeco::gui::Widget
ID	id_
const std::string	name_
const WinColors *	pwincols_
const uint8_t *	udgs_
Window *	pwin_
CallbackRout	callback_
std::string	tooltiptext_
HorAlign	hal_
VertAlign	val_
AreaFitting	fitting_needs_
CharRect	drawing_zone_
CharRect	aligned_drawing_zone_
Widget *	parent_
bool	explaindrawing_
Static Protected Attributes inherited from zxeco::gui::Widget
static Trace::Type	traces_
	Currently active traces. More...

Constructor & Destructor Documentation

LabelWidget()

zxeco::gui::LabelWidget::LabelWidget ( ID  id, const std::string &  name, const std::string &  initlabel, const std::string &  tooltiptext = "", HorAlign  hal = HorAlign::LEFT, VertAlign  val = VertAlign::TOP  )

inline

Constructor. The initial label is copied internally.

Since the internal label is of Label type, it can contain colour ctrls but not location ones.

Definition at line 48 of file ZXWidgetsSimple.h.

Member Function Documentation

getLabel()

const std::string & zxeco::gui::LabelWidget::getLabel ( void  )

inlinenoexcept

Return the current label text.

Definition at line 59 of file ZXWidgetsSimple.h.

className()

const char * zxeco::gui::LabelWidget::className ( void  ) const

inlinevirtualnoexcept

Must return a text with the name of the class.

The text should be a literal local to the method, since text literals have static storage and therefore exist for the entire duration of the program.

Implements zxeco::gui::Widget.

Definition at line 66 of file ZXWidgetsSimple.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::LabelWidget::calcFittingNeeds ( const CharArea &  area )

virtual

Must calculate the widget fitting within the dimensions of AREA.

It must consider all the content of the widget, set the visibility or invisibility of the children if it is a container with dynamically visible children (e.g., scroll slides), store internally the result of the fitting into the protected member fitting_needs_, and return a reference to it.

If the calculations lead to an unfitting situation, the widgetcause field of the result must indicate the first (lowest) widget that produced that unfit.

The area needed calculated by this method must be equal or smaller than AREA, and must be considered to begin at the corner (0,0) of AREA. It'll be used for drawing.

This method will be called at least once before a widget can be drawn (it needs not to be called again as long as the widget drawing dimensions do not change). It will not be called if the widget is invisible (invisible widgets occupy no space when drawing). Recall that the root widget of the widget tree is always considered visible.

The ContainerWidget class provide code for this in charge of calling their children method. Derived containers should call that base method to complete their calculations.

Implements zxeco::gui::Widget.

zxeco::gui::ButtonWidget

class zxeco::gui::ButtonWidget

A widget that is a button, either text or image.

Definition at line 86 of file ZXWidgetsSimple.h.

Inheritance diagram for zxeco::gui::ButtonWidget:

Collaboration diagram for zxeco::gui::ButtonWidget:

Public Member Functions
	ButtonWidget (ID id, const std::string &name, const std::string &initlabel, bool withborder=true, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	ButtonWidget (ID id, const std::string &name, const DoubleGraphic &img, const CharRect &region, bool withborder=false, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
const std::string &	getLabel (void) noexcept
	Return the label text. More...
void	setLabel (const std::string &newlab)
	Change the label and redraw the widget or throw if it is not text buttn.
DoubleGraphic &	getImage (void)
	Return a reference to the image or throw if it is not an image button.
void	setImage (const DoubleGraphic &img, const CharRect &region)
	Change the image and redraw the widget or throw if not an image button.
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Public Member Functions inherited from zxeco::gui::Widget
	Widget (ID id, const std::string &name, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
	Widget (const Widget &)=delete
	Constructor. More...
	Widget (Widget &&)=delete
	Constructor. More...
Widget &	operator= (const Widget &)=delete
	Constructor. More...
Widget &	operator= (Widget &&)=delete
	Constructor. More...
virtual	~Widget (void)=default
	Just to activate polymorphic deletes.
std::string	idText (bool withpointer=false) const
	Return a text with the identification of this widget. More...
virtual bool	isContainer (void) const noexcept
	Return whether the widget is a container of other widgets. More...
bool	isUserContainer (void) const noexcept
	Return whether the widget is a USER-type container. More...
ID	getID (void) const noexcept
	Return the ID assigned to the widget at creation. More...
void	changeID (ID id) noexcept
	Change the ID without checking for duplicates in this widget tree. More...
const std::string &	getName (void) const noexcept
	Return the name of the widget. More...
bool	operator== (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
bool	operator!= (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
virtual std::pair< bool, const CharRect * >	hasFocusZone (void) const noexcept
	< Must return TRUE and the zone if the widget contains a focus-able zone. More...
virtual void	setWindow (Window &win) noexcept
	Set the Window where the widget is being managed. More...
virtual void	setWinColors (const WinColors &wincols) noexcept
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
const WinColors &	getWinColors (void) const noexcept
	Return the current window colors. More...
virtual void	setUDGs (const uint8_t *udgs)
	Assign an UDG character set for the widget drawing (do not copy them). More...
const uint8_t *	getUDGs (void)
	Return the current UDGs. *‍/. More...
virtual void	setTooltip (const std::string &ttt)
	Must return a text with the name of the class. More...
const std::string &	getTooltip (void) const noexcept
	Return the tooltip for the widget. More...
void	setParent (Widget *parent)
	Sets the parent of the widget to PARENT, that must outlive it. More...
Widget *	getParent (void) const noexcept
	Return a pointer to the parent of the widget, or nullptr if none. More...
Widget *	getRoot (void)
	Return a pointer to the root widget of the tree. More...
bool	isRoot (void) const noexcept
	Return TRUE if this widget is the root of the tree. More...
bool	isDescendantOf (Widget &w) const
	Return TRUE if this is W or a descendant of W. More...
Widget *	searchID (ID id) const
	Search the first appearance of the given ID in this and its descendants. More...
ID	maxUsedID (void) const
	Search in this widget and its descendants the maximum ID used. More...
TravResult	traverse (const TraverseObserver &obs)
	Traverse this widget and its descendants, calling OBS on each one. More...
TravResult	revTraverse (const TraverseObserver &obs)
	Traverse this widget and its ascendants, calling OBS on each one. More...
void	setVisibility (bool visible=true)
	Set the desired visibility of the widget. More...
void	setVisibilityNoRedrawing (bool vis) noexcept
	Set the widget visibility without redrawing or modifying focus. More...
bool	getVisibility (void) const noexcept
	Get current visibility of the widget, considering also its parents. More...
void	setEnabled (bool enabled=true)
	Set whether the widget is enabld or disabld; drawRaw() widget if changd. More...
bool	getEnabled (void) const noexcept
	Get current enabled state of the widget, considering its parents. More...
bool	isFocusable (bool drawntoo=true) const
	Return TRUE if the widget is focusable now. More...
bool	isInFocusPath (void) const noexcept
	Return TRUE if the widget is in the path from root to the leaf focused. More...
bool	isLeafFocused (void) const noexcept
	< Return TRUE if it is in the focus path and it is the leaf of that path. More...
Widget *	whoIsFocused (void)
	Get the leaf focused widget in the tree, or nullptr if none. More...
void	acquireFocus (const PointingStatus *m=nullptr)
	Give the focus to this widget and quit it from the current focused one. More...
void	releaseFocus (void)
	Quit focus from this leaf widget or below it; no one acquires it. More...
void	drawAll (const CharRect &rect)
	Calculate and set the placement of all widgets within RECT and draw'em. More...
Widget *	redrawAll (void)
	Recalculate, place and redraw all widgets that have changed in the tree. More...
void	redrawMe (void)
	Recalculate and place all widgets in the tree forcing this to be drawn. More...
void	drawMe (void)
	Just force to draw the widget in the current drawing zone. More...
const AreaFitting &	fittingNeeds (void) const noexcept
	< Return the last calculation of the fitting needs of the widget. More...
virtual Widget *	setDrawingZone (const CharRect &zone)
	Set the final drawing zone for the widget and the aligned one. More...
const CharRect &	drawingZone (void) const noexcept
	< Get the drawing zone decided for the widget within the global screen. More...
const CharRect &	alignedDrawingZone (void) const noexcept
	< Get the part of the drawing zone that is already aligned. More...
virtual void	moveDrawingZones (IntDist incx, IntDist incy) noexcept
	Move the drawing and aligned zones corners by those increments. More...
bool	drawn (void) const noexcept
	Return TRUE if the widget has already been drawn in current dimensions. More...
void	undraw (void) noexcept
	Method for external agents (e.g., Windows) to mark the widget undrawn. More...
void	setExplanations (bool setit=true) noexcept
	< Set/unset the generation of explanations when calculating drawing. More...
bool	getExplanations (void) const noexcept
	Return the current status of drawing explanations. More...
std::string	traceOfDrawing (bool withoutprivate=true) const
	< Return an explanation with the drawing status of this and child widgets More...
virtual void	traceOfDrawingRecursive (size_t level, std::stringstream &ss, bool withoutprivate=true) const
	Same as traceOfDrawing() but indicating the depth level and using SS. More...
virtual ChainEventResult	chainEvent (const EventData &data)
	Deal with the event at this widget and its descendants (if container). More...
virtual void	setCallback (const CallbackRout &callback=NullCallback)
	Deal with the event at this widget and its descendants (if container). More...
const CallbackRout &	getCallback (void) const noexcept
	Get the current callback routine. More...
void	addCallback (const CallbackRout &cbk)
	Add callback CBK to the end of the current callback routine. More...

Additional Inherited Members
Public Types inherited from zxeco::gui::Widget
enum class	TravResult { FINISH_OK , FINISH_FAIL , BACKTRACK , CONTINUE }
	Possible results of observer when traversing widgets in the widget tree. More...
using	ID = int
	A numeric ID associated to the widget. More...
using	Ptr = std::shared_ptr< Widget >
	A polymorphic ptr to a widget. More...
using	TraverseObserver = std::function< TravResult(Widget &) >
enum class	HorAlign { LEFT , RIGHT , CENTER }
	Horizontal alignment of widgets within the areas of their containers. More...
enum class	VertAlign { TOP , BOTTOM , MIDDLE }
	Vertical alignment of widgets within the areas of their containers. More...
enum class	EventType { MOUSE , KEYBOARD , FOCUS }
	Kinds of events that the widgets may process from the graphical environ. More...
enum class	SubEvType {   MOUSE_MOVE , MOUSE_CLICK , MOUSE_UNCLICK , MOUSE_WHEEL ,   KEYB_PRESS , KEYB_UNPRESS , KEYB_TEXT , FOCUS_GOT ,   FOCUS_LOST }
	Concrete events for each event kind. More...
using	CallbackRout = std::function< bool(Widget &, const CallbackParms &)>
Static Public Member Functions inherited from zxeco::gui::Widget
static void	addGlobalTraces (Trace::Type traces) noexcept
	< Add TRACES to the currently active traces (initially none). More...
static void	delGlobalTraces (Trace::Type traces) noexcept
	< Delete the given traces from the current active ones. More...
static Trace::Type	isTracing (Trace::Type traces) noexcept
	< Return a non-zero value if any of TRACES is currently active. More...
static void	printTrace (Trace::Type trace, const std::string &tr)
	Put TR in console as a trace, with a mark indicating TRACE.
static void	printIfTrace (Trace::Type trace, const std::string &tr)
	The same as printTrace() but only print if any of TRACE is active. More...
Static Public Attributes inherited from zxeco::gui::Widget
static const CallbackRout	NullCallback
	Callback routine that does nothing. More...
static const std::string	kTraceBegin
	< Add TRACES to the currently active traces (initially none). More...
static const std::string	kTraceEnd
	< Add TRACES to the currently active traces (initially none). More...
Protected Member Functions inherited from zxeco::gui::Widget
virtual void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
virtual int	processEvent (const EventData &evdata, Widget *who)
void	addLineToExplanation (const std::string &line)
	Add LINE to the existing explanation in fitting_needs_. More...
Protected Attributes inherited from zxeco::gui::Widget
ID	id_
const std::string	name_
const WinColors *	pwincols_
const uint8_t *	udgs_
Window *	pwin_
CallbackRout	callback_
std::string	tooltiptext_
HorAlign	hal_
VertAlign	val_
AreaFitting	fitting_needs_
CharRect	drawing_zone_
CharRect	aligned_drawing_zone_
Widget *	parent_
bool	explaindrawing_
Static Protected Attributes inherited from zxeco::gui::Widget
static Trace::Type	traces_
	Currently active traces. More...

Constructor & Destructor Documentation

ButtonWidget() [1/2]

zxeco::gui::ButtonWidget::ButtonWidget ( ID  id, const std::string &  name, const std::string &  initlabel, bool  withborder = true, const std::string &  tooltiptext = "", HorAlign  hal = HorAlign::LEFT, VertAlign  val = VertAlign::TOP  )

inline

< Since the internal label is of Label type, it can contain colour ctrls but not location ones.

Definition at line 91 of file ZXWidgetsSimple.h.

ButtonWidget() [2/2]

zxeco::gui::ButtonWidget::ButtonWidget ( ID  id, const std::string &  name, const DoubleGraphic &  img, const CharRect &  region, bool  withborder = false, const std::string &  tooltiptext = "", HorAlign  hal = HorAlign::LEFT, VertAlign  val = VertAlign::TOP  )

inline

< When clicked, the button will exchange paper and ink color in the img. IMG holds the image and REGION indicates which part will be used for the button (it will be copied from IMG); if it is empty, the entire IMG will be used.

Definition at line 110 of file ZXWidgetsSimple.h.

Member Function Documentation

getLabel()

const std::string & zxeco::gui::ButtonWidget::getLabel ( void  )

inlinenoexcept

Return the label text.

Definition at line 131 of file ZXWidgetsSimple.h.

className()

const char * zxeco::gui::ButtonWidget::className ( void  ) const

inlinevirtualnoexcept

Must return a text with the name of the class.

The text should be a literal local to the method, since text literals have static storage and therefore exist for the entire duration of the program.

Implements zxeco::gui::Widget.

Definition at line 144 of file ZXWidgetsSimple.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::ButtonWidget::calcFittingNeeds ( const CharArea &  area )

virtual

Must calculate the widget fitting within the dimensions of AREA.

It must consider all the content of the widget, set the visibility or invisibility of the children if it is a container with dynamically visible children (e.g., scroll slides), store internally the result of the fitting into the protected member fitting_needs_, and return a reference to it.

If the calculations lead to an unfitting situation, the widgetcause field of the result must indicate the first (lowest) widget that produced that unfit.

The area needed calculated by this method must be equal or smaller than AREA, and must be considered to begin at the corner (0,0) of AREA. It'll be used for drawing.

This method will be called at least once before a widget can be drawn (it needs not to be called again as long as the widget drawing dimensions do not change). It will not be called if the widget is invisible (invisible widgets occupy no space when drawing). Recall that the root widget of the widget tree is always considered visible.

The ContainerWidget class provide code for this in charge of calling their children method. Derived containers should call that base method to complete their calculations.

Implements zxeco::gui::Widget.

zxeco::gui::SwitchWidget

class zxeco::gui::SwitchWidget

A widget that is a button with two positions that are held over time.

Definition at line 172 of file ZXWidgetsSimple.h.

Inheritance diagram for zxeco::gui::SwitchWidget:

Collaboration diagram for zxeco::gui::SwitchWidget:

Public Member Functions
	SwitchWidget (ID id, const std::string &name, const std::string &labelleft, const std::string &labelright, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor for a text-label button. More...
bool	state (void) const noexcept
	Return TRUE if the switch is ON. More...
void	changeState (bool st)
	Change the state to ST if different from current one. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Public Member Functions inherited from zxeco::gui::Widget
	Widget (ID id, const std::string &name, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
	Widget (const Widget &)=delete
	Constructor. More...
	Widget (Widget &&)=delete
	Constructor. More...
Widget &	operator= (const Widget &)=delete
	Constructor. More...
Widget &	operator= (Widget &&)=delete
	Constructor. More...
virtual	~Widget (void)=default
	Just to activate polymorphic deletes.
std::string	idText (bool withpointer=false) const
	Return a text with the identification of this widget. More...
virtual bool	isContainer (void) const noexcept
	Return whether the widget is a container of other widgets. More...
bool	isUserContainer (void) const noexcept
	Return whether the widget is a USER-type container. More...
ID	getID (void) const noexcept
	Return the ID assigned to the widget at creation. More...
void	changeID (ID id) noexcept
	Change the ID without checking for duplicates in this widget tree. More...
const std::string &	getName (void) const noexcept
	Return the name of the widget. More...
bool	operator== (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
bool	operator!= (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
virtual std::pair< bool, const CharRect * >	hasFocusZone (void) const noexcept
	< Must return TRUE and the zone if the widget contains a focus-able zone. More...
virtual void	setWindow (Window &win) noexcept
	Set the Window where the widget is being managed. More...
virtual void	setWinColors (const WinColors &wincols) noexcept
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
const WinColors &	getWinColors (void) const noexcept
	Return the current window colors. More...
virtual void	setUDGs (const uint8_t *udgs)
	Assign an UDG character set for the widget drawing (do not copy them). More...
const uint8_t *	getUDGs (void)
	Return the current UDGs. *‍/. More...
virtual void	setTooltip (const std::string &ttt)
	Must return a text with the name of the class. More...
const std::string &	getTooltip (void) const noexcept
	Return the tooltip for the widget. More...
void	setParent (Widget *parent)
	Sets the parent of the widget to PARENT, that must outlive it. More...
Widget *	getParent (void) const noexcept
	Return a pointer to the parent of the widget, or nullptr if none. More...
Widget *	getRoot (void)
	Return a pointer to the root widget of the tree. More...
bool	isRoot (void) const noexcept
	Return TRUE if this widget is the root of the tree. More...
bool	isDescendantOf (Widget &w) const
	Return TRUE if this is W or a descendant of W. More...
Widget *	searchID (ID id) const
	Search the first appearance of the given ID in this and its descendants. More...
ID	maxUsedID (void) const
	Search in this widget and its descendants the maximum ID used. More...
TravResult	traverse (const TraverseObserver &obs)
	Traverse this widget and its descendants, calling OBS on each one. More...
TravResult	revTraverse (const TraverseObserver &obs)
	Traverse this widget and its ascendants, calling OBS on each one. More...
void	setVisibility (bool visible=true)
	Set the desired visibility of the widget. More...
void	setVisibilityNoRedrawing (bool vis) noexcept
	Set the widget visibility without redrawing or modifying focus. More...
bool	getVisibility (void) const noexcept
	Get current visibility of the widget, considering also its parents. More...
void	setEnabled (bool enabled=true)
	Set whether the widget is enabld or disabld; drawRaw() widget if changd. More...
bool	getEnabled (void) const noexcept
	Get current enabled state of the widget, considering its parents. More...
bool	isFocusable (bool drawntoo=true) const
	Return TRUE if the widget is focusable now. More...
bool	isInFocusPath (void) const noexcept
	Return TRUE if the widget is in the path from root to the leaf focused. More...
bool	isLeafFocused (void) const noexcept
	< Return TRUE if it is in the focus path and it is the leaf of that path. More...
Widget *	whoIsFocused (void)
	Get the leaf focused widget in the tree, or nullptr if none. More...
void	acquireFocus (const PointingStatus *m=nullptr)
	Give the focus to this widget and quit it from the current focused one. More...
void	releaseFocus (void)
	Quit focus from this leaf widget or below it; no one acquires it. More...
void	drawAll (const CharRect &rect)
	Calculate and set the placement of all widgets within RECT and draw'em. More...
Widget *	redrawAll (void)
	Recalculate, place and redraw all widgets that have changed in the tree. More...
void	redrawMe (void)
	Recalculate and place all widgets in the tree forcing this to be drawn. More...
void	drawMe (void)
	Just force to draw the widget in the current drawing zone. More...
const AreaFitting &	fittingNeeds (void) const noexcept
	< Return the last calculation of the fitting needs of the widget. More...
virtual Widget *	setDrawingZone (const CharRect &zone)
	Set the final drawing zone for the widget and the aligned one. More...
const CharRect &	drawingZone (void) const noexcept
	< Get the drawing zone decided for the widget within the global screen. More...
const CharRect &	alignedDrawingZone (void) const noexcept
	< Get the part of the drawing zone that is already aligned. More...
virtual void	moveDrawingZones (IntDist incx, IntDist incy) noexcept
	Move the drawing and aligned zones corners by those increments. More...
bool	drawn (void) const noexcept
	Return TRUE if the widget has already been drawn in current dimensions. More...
void	undraw (void) noexcept
	Method for external agents (e.g., Windows) to mark the widget undrawn. More...
void	setExplanations (bool setit=true) noexcept
	< Set/unset the generation of explanations when calculating drawing. More...
bool	getExplanations (void) const noexcept
	Return the current status of drawing explanations. More...
std::string	traceOfDrawing (bool withoutprivate=true) const
	< Return an explanation with the drawing status of this and child widgets More...
virtual void	traceOfDrawingRecursive (size_t level, std::stringstream &ss, bool withoutprivate=true) const
	Same as traceOfDrawing() but indicating the depth level and using SS. More...
virtual ChainEventResult	chainEvent (const EventData &data)
	Deal with the event at this widget and its descendants (if container). More...
virtual void	setCallback (const CallbackRout &callback=NullCallback)
	Deal with the event at this widget and its descendants (if container). More...
const CallbackRout &	getCallback (void) const noexcept
	Get the current callback routine. More...
void	addCallback (const CallbackRout &cbk)
	Add callback CBK to the end of the current callback routine. More...

Additional Inherited Members
Public Types inherited from zxeco::gui::Widget
enum class	TravResult { FINISH_OK , FINISH_FAIL , BACKTRACK , CONTINUE }
	Possible results of observer when traversing widgets in the widget tree. More...
using	ID = int
	A numeric ID associated to the widget. More...
using	Ptr = std::shared_ptr< Widget >
	A polymorphic ptr to a widget. More...
using	TraverseObserver = std::function< TravResult(Widget &) >
enum class	HorAlign { LEFT , RIGHT , CENTER }
	Horizontal alignment of widgets within the areas of their containers. More...
enum class	VertAlign { TOP , BOTTOM , MIDDLE }
	Vertical alignment of widgets within the areas of their containers. More...
enum class	EventType { MOUSE , KEYBOARD , FOCUS }
	Kinds of events that the widgets may process from the graphical environ. More...
enum class	SubEvType {   MOUSE_MOVE , MOUSE_CLICK , MOUSE_UNCLICK , MOUSE_WHEEL ,   KEYB_PRESS , KEYB_UNPRESS , KEYB_TEXT , FOCUS_GOT ,   FOCUS_LOST }
	Concrete events for each event kind. More...
using	CallbackRout = std::function< bool(Widget &, const CallbackParms &)>
Static Public Member Functions inherited from zxeco::gui::Widget
static void	addGlobalTraces (Trace::Type traces) noexcept
	< Add TRACES to the currently active traces (initially none). More...
static void	delGlobalTraces (Trace::Type traces) noexcept
	< Delete the given traces from the current active ones. More...
static Trace::Type	isTracing (Trace::Type traces) noexcept
	< Return a non-zero value if any of TRACES is currently active. More...
static void	printTrace (Trace::Type trace, const std::string &tr)
	Put TR in console as a trace, with a mark indicating TRACE.
static void	printIfTrace (Trace::Type trace, const std::string &tr)
	The same as printTrace() but only print if any of TRACE is active. More...
Static Public Attributes inherited from zxeco::gui::Widget
static const CallbackRout	NullCallback
	Callback routine that does nothing. More...
static const std::string	kTraceBegin
	< Add TRACES to the currently active traces (initially none). More...
static const std::string	kTraceEnd
	< Add TRACES to the currently active traces (initially none). More...
Protected Member Functions inherited from zxeco::gui::Widget
virtual void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
virtual int	processEvent (const EventData &evdata, Widget *who)
void	addLineToExplanation (const std::string &line)
	Add LINE to the existing explanation in fitting_needs_. More...
Protected Attributes inherited from zxeco::gui::Widget
ID	id_
const std::string	name_
const WinColors *	pwincols_
const uint8_t *	udgs_
Window *	pwin_
CallbackRout	callback_
std::string	tooltiptext_
HorAlign	hal_
VertAlign	val_
AreaFitting	fitting_needs_
CharRect	drawing_zone_
CharRect	aligned_drawing_zone_
Widget *	parent_
bool	explaindrawing_
Static Protected Attributes inherited from zxeco::gui::Widget
static Trace::Type	traces_
	Currently active traces. More...

Constructor & Destructor Documentation

SwitchWidget()

zxeco::gui::SwitchWidget::SwitchWidget	(	ID	id,
		const std::string &	name,
		const std::string &	labelleft,
		const std::string &	labelright,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor for a text-label button.

The labels may be empty, but all ctrl chars are expurged. The left label corresponds to the OFF position, while the right one to the ON. Initially, the switch is OFF.

Note

- In a callback, the switch is already changed only if the moment is 'after' and the event is 'mouse unclick left'; otherwise, the read state will be the one previous to the switching.

Member Function Documentation

state()

bool zxeco::gui::SwitchWidget::state ( void  ) const

inlinenoexcept

Return TRUE if the switch is ON.

Definition at line 190 of file ZXWidgetsSimple.h.

changeState()

void zxeco::gui::SwitchWidget::changeState

(

bool

st

)

Change the state to ST if different from current one.

Otherwise do nothing.

className()

const char * zxeco::gui::SwitchWidget::className ( void  ) const

inlinevirtualnoexcept

Must return a text with the name of the class.

The text should be a literal local to the method, since text literals have static storage and therefore exist for the entire duration of the program.

Implements zxeco::gui::Widget.

Definition at line 198 of file ZXWidgetsSimple.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::SwitchWidget::calcFittingNeeds ( const CharArea &  area )

virtual

Must calculate the widget fitting within the dimensions of AREA.

It must consider all the content of the widget, set the visibility or invisibility of the children if it is a container with dynamically visible children (e.g., scroll slides), store internally the result of the fitting into the protected member fitting_needs_, and return a reference to it.

If the calculations lead to an unfitting situation, the widgetcause field of the result must indicate the first (lowest) widget that produced that unfit.

The area needed calculated by this method must be equal or smaller than AREA, and must be considered to begin at the corner (0,0) of AREA. It'll be used for drawing.

This method will be called at least once before a widget can be drawn (it needs not to be called again as long as the widget drawing dimensions do not change). It will not be called if the widget is invisible (invisible widgets occupy no space when drawing). Recall that the root widget of the widget tree is always considered visible.

The ContainerWidget class provide code for this in charge of calling their children method. Derived containers should call that base method to complete their calculations.

Implements zxeco::gui::Widget.

zxeco::gui::LineInputWidget

class zxeco::gui::LineInputWidget

A widget that shows a line for user typing.

ESC key aborts edition retrieving the text that was in the widget at the start of that edition.

Definition at line 223 of file ZXWidgetsSimple.h.

Inheritance diagram for zxeco::gui::LineInputWidget:

Collaboration diagram for zxeco::gui::LineInputWidget:

Public Member Functions
	LineInputWidget (ID id, const std::string &name, CharDist inputlen=0, bool editable=true, bool enterendsedition=true, CharDist markedlen=0, const uint8_t *printfont=nullptr, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
virtual	~LineInputWidget (void)
	Destructor.
const std::string &	text (void) const noexcept
	Return the text currently in the line. More...
void	setText (const std::string &txt)
	Change the current text by TXT, ignoring all ctrl chars. More...
void	putCursorAtExtreme (char which)
	Put the cursor to the end ('E') or to the beginning ('B') in the text. More...
bool	hasLostFocusOrEnter (const Widget::CallbackParms &cbps) noexcept
	Return TRUE if the focus is being lost or ENTER has been pressed. More...
void	moveDrawingZones (IntDist incx, IntDist incy) noexcept override
	Move the drawing and aligned zones corners by those increments. More...
std::pair< bool, const CharRect * >	hasFocusZone (void) const noexcept override
	< Must return TRUE and the zone if the widget contains a focus-able zone. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Public Member Functions inherited from zxeco::gui::Widget
	Widget (ID id, const std::string &name, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
	Widget (const Widget &)=delete
	Constructor. More...
	Widget (Widget &&)=delete
	Constructor. More...
Widget &	operator= (const Widget &)=delete
	Constructor. More...
Widget &	operator= (Widget &&)=delete
	Constructor. More...
virtual	~Widget (void)=default
	Just to activate polymorphic deletes.
std::string	idText (bool withpointer=false) const
	Return a text with the identification of this widget. More...
virtual bool	isContainer (void) const noexcept
	Return whether the widget is a container of other widgets. More...
bool	isUserContainer (void) const noexcept
	Return whether the widget is a USER-type container. More...
ID	getID (void) const noexcept
	Return the ID assigned to the widget at creation. More...
void	changeID (ID id) noexcept
	Change the ID without checking for duplicates in this widget tree. More...
const std::string &	getName (void) const noexcept
	Return the name of the widget. More...
bool	operator== (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
bool	operator!= (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
virtual void	setWindow (Window &win) noexcept
	Set the Window where the widget is being managed. More...
virtual void	setWinColors (const WinColors &wincols) noexcept
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
const WinColors &	getWinColors (void) const noexcept
	Return the current window colors. More...
virtual void	setUDGs (const uint8_t *udgs)
	Assign an UDG character set for the widget drawing (do not copy them). More...
const uint8_t *	getUDGs (void)
	Return the current UDGs. *‍/. More...
virtual void	setTooltip (const std::string &ttt)
	Must return a text with the name of the class. More...
const std::string &	getTooltip (void) const noexcept
	Return the tooltip for the widget. More...
void	setParent (Widget *parent)
	Sets the parent of the widget to PARENT, that must outlive it. More...
Widget *	getParent (void) const noexcept
	Return a pointer to the parent of the widget, or nullptr if none. More...
Widget *	getRoot (void)
	Return a pointer to the root widget of the tree. More...
bool	isRoot (void) const noexcept
	Return TRUE if this widget is the root of the tree. More...
bool	isDescendantOf (Widget &w) const
	Return TRUE if this is W or a descendant of W. More...
Widget *	searchID (ID id) const
	Search the first appearance of the given ID in this and its descendants. More...
ID	maxUsedID (void) const
	Search in this widget and its descendants the maximum ID used. More...
TravResult	traverse (const TraverseObserver &obs)
	Traverse this widget and its descendants, calling OBS on each one. More...
TravResult	revTraverse (const TraverseObserver &obs)
	Traverse this widget and its ascendants, calling OBS on each one. More...
void	setVisibility (bool visible=true)
	Set the desired visibility of the widget. More...
void	setVisibilityNoRedrawing (bool vis) noexcept
	Set the widget visibility without redrawing or modifying focus. More...
bool	getVisibility (void) const noexcept
	Get current visibility of the widget, considering also its parents. More...
void	setEnabled (bool enabled=true)
	Set whether the widget is enabld or disabld; drawRaw() widget if changd. More...
bool	getEnabled (void) const noexcept
	Get current enabled state of the widget, considering its parents. More...
bool	isFocusable (bool drawntoo=true) const
	Return TRUE if the widget is focusable now. More...
bool	isInFocusPath (void) const noexcept
	Return TRUE if the widget is in the path from root to the leaf focused. More...
bool	isLeafFocused (void) const noexcept
	< Return TRUE if it is in the focus path and it is the leaf of that path. More...
Widget *	whoIsFocused (void)
	Get the leaf focused widget in the tree, or nullptr if none. More...
void	acquireFocus (const PointingStatus *m=nullptr)
	Give the focus to this widget and quit it from the current focused one. More...
void	releaseFocus (void)
	Quit focus from this leaf widget or below it; no one acquires it. More...
void	drawAll (const CharRect &rect)
	Calculate and set the placement of all widgets within RECT and draw'em. More...
Widget *	redrawAll (void)
	Recalculate, place and redraw all widgets that have changed in the tree. More...
void	redrawMe (void)
	Recalculate and place all widgets in the tree forcing this to be drawn. More...
void	drawMe (void)
	Just force to draw the widget in the current drawing zone. More...
const AreaFitting &	fittingNeeds (void) const noexcept
	< Return the last calculation of the fitting needs of the widget. More...
virtual Widget *	setDrawingZone (const CharRect &zone)
	Set the final drawing zone for the widget and the aligned one. More...
const CharRect &	drawingZone (void) const noexcept
	< Get the drawing zone decided for the widget within the global screen. More...
const CharRect &	alignedDrawingZone (void) const noexcept
	< Get the part of the drawing zone that is already aligned. More...
bool	drawn (void) const noexcept
	Return TRUE if the widget has already been drawn in current dimensions. More...
void	undraw (void) noexcept
	Method for external agents (e.g., Windows) to mark the widget undrawn. More...
void	setExplanations (bool setit=true) noexcept
	< Set/unset the generation of explanations when calculating drawing. More...
bool	getExplanations (void) const noexcept
	Return the current status of drawing explanations. More...
std::string	traceOfDrawing (bool withoutprivate=true) const
	< Return an explanation with the drawing status of this and child widgets More...
virtual void	traceOfDrawingRecursive (size_t level, std::stringstream &ss, bool withoutprivate=true) const
	Same as traceOfDrawing() but indicating the depth level and using SS. More...
virtual ChainEventResult	chainEvent (const EventData &data)
	Deal with the event at this widget and its descendants (if container). More...
virtual void	setCallback (const CallbackRout &callback=NullCallback)
	Deal with the event at this widget and its descendants (if container). More...
const CallbackRout &	getCallback (void) const noexcept
	Get the current callback routine. More...
void	addCallback (const CallbackRout &cbk)
	Add callback CBK to the end of the current callback routine. More...

Additional Inherited Members
Public Types inherited from zxeco::gui::Widget
enum class	TravResult { FINISH_OK , FINISH_FAIL , BACKTRACK , CONTINUE }
	Possible results of observer when traversing widgets in the widget tree. More...
using	ID = int
	A numeric ID associated to the widget. More...
using	Ptr = std::shared_ptr< Widget >
	A polymorphic ptr to a widget. More...
using	TraverseObserver = std::function< TravResult(Widget &) >
enum class	HorAlign { LEFT , RIGHT , CENTER }
	Horizontal alignment of widgets within the areas of their containers. More...
enum class	VertAlign { TOP , BOTTOM , MIDDLE }
	Vertical alignment of widgets within the areas of their containers. More...
enum class	EventType { MOUSE , KEYBOARD , FOCUS }
	Kinds of events that the widgets may process from the graphical environ. More...
enum class	SubEvType {   MOUSE_MOVE , MOUSE_CLICK , MOUSE_UNCLICK , MOUSE_WHEEL ,   KEYB_PRESS , KEYB_UNPRESS , KEYB_TEXT , FOCUS_GOT ,   FOCUS_LOST }
	Concrete events for each event kind. More...
using	CallbackRout = std::function< bool(Widget &, const CallbackParms &)>
Static Public Member Functions inherited from zxeco::gui::Widget
static void	addGlobalTraces (Trace::Type traces) noexcept
	< Add TRACES to the currently active traces (initially none). More...
static void	delGlobalTraces (Trace::Type traces) noexcept
	< Delete the given traces from the current active ones. More...
static Trace::Type	isTracing (Trace::Type traces) noexcept
	< Return a non-zero value if any of TRACES is currently active. More...
static void	printTrace (Trace::Type trace, const std::string &tr)
	Put TR in console as a trace, with a mark indicating TRACE.
static void	printIfTrace (Trace::Type trace, const std::string &tr)
	The same as printTrace() but only print if any of TRACE is active. More...
Static Public Attributes inherited from zxeco::gui::Widget
static const CallbackRout	NullCallback
	Callback routine that does nothing. More...
static const std::string	kTraceBegin
	< Add TRACES to the currently active traces (initially none). More...
static const std::string	kTraceEnd
	< Add TRACES to the currently active traces (initially none). More...
Protected Member Functions inherited from zxeco::gui::Widget
virtual void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
virtual int	processEvent (const EventData &evdata, Widget *who)
void	addLineToExplanation (const std::string &line)
	Add LINE to the existing explanation in fitting_needs_. More...
Protected Attributes inherited from zxeco::gui::Widget
ID	id_
const std::string	name_
const WinColors *	pwincols_
const uint8_t *	udgs_
Window *	pwin_
CallbackRout	callback_
std::string	tooltiptext_
HorAlign	hal_
VertAlign	val_
AreaFitting	fitting_needs_
CharRect	drawing_zone_
CharRect	aligned_drawing_zone_
Widget *	parent_
bool	explaindrawing_
Static Protected Attributes inherited from zxeco::gui::Widget
static Trace::Type	traces_
	Currently active traces. More...

Constructor & Destructor Documentation

LineInputWidget()

zxeco::gui::LineInputWidget::LineInputWidget	(	ID	id,
		const std::string &	name,
		CharDist	inputlen = 0,
		bool	editable = true,
		bool	enterendsedition = true,
		CharDist	markedlen = 0,
		const uint8_t *	printfont = nullptr,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor.

Parameters

inputlen	(>= 0) is the length in chars of the typing area, or 0 for using as much as possible the available room in the window (in one horizontal char row). The total area of the widget is the length of the typing area plus 2 (for the excess markers at both sides).
editable	allows, if true, that the user edit the text in the input area; otherwise only moving the cursor there is allowed.
enterendsedition	produces automatically a lost of focus when enter is pressed if the widget is editable.
markedlen	if > 0 indicates the number of characters from the beginning of the text that will have the paper marked with a special color (it can serve, for instance, to suggest the user a max. length for the text without constraining effectively that length).
printfont	if not null is taken as the font to use when printing the text (it is copied inside the widget).

Member Function Documentation

text()

const std::string & zxeco::gui::LineInputWidget::text ( void  ) const

inlinenoexcept

Return the text currently in the line.

Definition at line 254 of file ZXWidgetsSimple.h.

setText()

void zxeco::gui::LineInputWidget::setText

(

const std::string &

txt

)

Change the current text by TXT, ignoring all ctrl chars.

Set the cursor to 0 and show the text from its first char. This works even when the widget is not editable. UDGs, graphic blocks and any code < 32 that is not a ctrl char are not modified; tokens are substituted by their nude texts.

putCursorAtExtreme()

void zxeco::gui::LineInputWidget::putCursorAtExtreme

(

char

which

)

Put the cursor to the end ('E') or to the beginning ('B') in the text.

If the widget is not drawn and the action cannot be done, it is stored to be done right in the next drawing.

hasLostFocusOrEnter()

bool zxeco::gui::LineInputWidget::hasLostFocusOrEnter ( const Widget::CallbackParms &  cbps )

inlinenoexcept

Return TRUE if the focus is being lost or ENTER has been pressed.

Definition at line 270 of file ZXWidgetsSimple.h.

moveDrawingZones()

void zxeco::gui::LineInputWidget::moveDrawingZones ( IntDist  incx, IntDist  incy  )

inlineoverridevirtualnoexcept

Move the drawing and aligned zones corners by those increments.

Does not change the areas or the drawn_ flag. In general, this method should not be overriden by derived classes unless they need to move something else in addition to the drawing and aligned zones.

Reimplemented from zxeco::gui::Widget.

Definition at line 274 of file ZXWidgetsSimple.h.

hasFocusZone()

std::pair< bool, const CharRect * > zxeco::gui::LineInputWidget::hasFocusZone ( void  ) const

inlineoverridevirtualnoexcept

< Must return TRUE and the zone if the widget contains a focus-able zone.

< Those kinds of zones are where some events can be redirected; otherwise any event received that does not convey screen position information would not know where to be dealt with. A widget can only have one focusable zone. A feasible focusable zone in a widget is its aligned_drawing_zone_. This base method returns no focusable zone.

Reimplemented from zxeco::gui::Widget.

Definition at line 276 of file ZXWidgetsSimple.h.

className()

const char * zxeco::gui::LineInputWidget::className ( void  ) const

inlinevirtualnoexcept

Must return a text with the name of the class.

The text should be a literal local to the method, since text literals have static storage and therefore exist for the entire duration of the program.

Implements zxeco::gui::Widget.

Definition at line 279 of file ZXWidgetsSimple.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::LineInputWidget::calcFittingNeeds ( const CharArea &  area )

virtual

Must calculate the widget fitting within the dimensions of AREA.

It must consider all the content of the widget, set the visibility or invisibility of the children if it is a container with dynamically visible children (e.g., scroll slides), store internally the result of the fitting into the protected member fitting_needs_, and return a reference to it.

If the calculations lead to an unfitting situation, the widgetcause field of the result must indicate the first (lowest) widget that produced that unfit.

The area needed calculated by this method must be equal or smaller than AREA, and must be considered to begin at the corner (0,0) of AREA. It'll be used for drawing.

This method will be called at least once before a widget can be drawn (it needs not to be called again as long as the widget drawing dimensions do not change). It will not be called if the widget is invisible (invisible widgets occupy no space when drawing). Recall that the root widget of the widget tree is always considered visible.

The ContainerWidget class provide code for this in charge of calling their children method. Derived containers should call that base method to complete their calculations.

Implements zxeco::gui::Widget.

zxeco::gui::ChoiceWidget

class zxeco::gui::ChoiceWidget

A widget consisting of a number of options, for single or multiple selection.

The options are inmutable after construction.

Definition at line 315 of file ZXWidgetsSimple.h.

Inheritance diagram for zxeco::gui::ChoiceWidget:

Collaboration diagram for zxeco::gui::ChoiceWidget:

Public Member Functions
	ChoiceWidget (ID id, const std::string &name, const Label::Vector &labels, char kindofselection, bool horizorvert=false, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. Labels are copied internally. They can contain ctrl color. More...
size_t	numberOfChoices (void) const noexcept
	Return the number of choices. *‍/. More...
bool	isSelected (size_t who) const
	Return TRUE if the given option is currently selected. More...
int	firstSelected (void) const noexcept
	Return the index of the first selected option, or -1 if none.
void	setSelect (size_t who, bool select=true)
void	toggleSelect (size_t who)
void	setAll (bool select=true)
void	toggleAll (void)
	Toggle the selection of all options. More...
const LabelList &	labels (void) const noexcept
	Return the labels used by the widget. More...
size_t	whoCursor (const PointingStatus &coords) const noexcept
	Return the index of the choice pointed by COORDS, or >= N if none.
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Public Member Functions inherited from zxeco::gui::Widget
	Widget (ID id, const std::string &name, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
	Widget (const Widget &)=delete
	Constructor. More...
	Widget (Widget &&)=delete
	Constructor. More...
Widget &	operator= (const Widget &)=delete
	Constructor. More...
Widget &	operator= (Widget &&)=delete
	Constructor. More...
virtual	~Widget (void)=default
	Just to activate polymorphic deletes.
std::string	idText (bool withpointer=false) const
	Return a text with the identification of this widget. More...
virtual bool	isContainer (void) const noexcept
	Return whether the widget is a container of other widgets. More...
bool	isUserContainer (void) const noexcept
	Return whether the widget is a USER-type container. More...
ID	getID (void) const noexcept
	Return the ID assigned to the widget at creation. More...
void	changeID (ID id) noexcept
	Change the ID without checking for duplicates in this widget tree. More...
const std::string &	getName (void) const noexcept
	Return the name of the widget. More...
bool	operator== (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
bool	operator!= (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
virtual std::pair< bool, const CharRect * >	hasFocusZone (void) const noexcept
	< Must return TRUE and the zone if the widget contains a focus-able zone. More...
virtual void	setWindow (Window &win) noexcept
	Set the Window where the widget is being managed. More...
virtual void	setWinColors (const WinColors &wincols) noexcept
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
const WinColors &	getWinColors (void) const noexcept
	Return the current window colors. More...
virtual void	setUDGs (const uint8_t *udgs)
	Assign an UDG character set for the widget drawing (do not copy them). More...
const uint8_t *	getUDGs (void)
	Return the current UDGs. *‍/. More...
virtual void	setTooltip (const std::string &ttt)
	Must return a text with the name of the class. More...
const std::string &	getTooltip (void) const noexcept
	Return the tooltip for the widget. More...
void	setParent (Widget *parent)
	Sets the parent of the widget to PARENT, that must outlive it. More...
Widget *	getParent (void) const noexcept
	Return a pointer to the parent of the widget, or nullptr if none. More...
Widget *	getRoot (void)
	Return a pointer to the root widget of the tree. More...
bool	isRoot (void) const noexcept
	Return TRUE if this widget is the root of the tree. More...
bool	isDescendantOf (Widget &w) const
	Return TRUE if this is W or a descendant of W. More...
Widget *	searchID (ID id) const
	Search the first appearance of the given ID in this and its descendants. More...
ID	maxUsedID (void) const
	Search in this widget and its descendants the maximum ID used. More...
TravResult	traverse (const TraverseObserver &obs)
	Traverse this widget and its descendants, calling OBS on each one. More...
TravResult	revTraverse (const TraverseObserver &obs)
	Traverse this widget and its ascendants, calling OBS on each one. More...
void	setVisibility (bool visible=true)
	Set the desired visibility of the widget. More...
void	setVisibilityNoRedrawing (bool vis) noexcept
	Set the widget visibility without redrawing or modifying focus. More...
bool	getVisibility (void) const noexcept
	Get current visibility of the widget, considering also its parents. More...
void	setEnabled (bool enabled=true)
	Set whether the widget is enabld or disabld; drawRaw() widget if changd. More...
bool	getEnabled (void) const noexcept
	Get current enabled state of the widget, considering its parents. More...
bool	isFocusable (bool drawntoo=true) const
	Return TRUE if the widget is focusable now. More...
bool	isInFocusPath (void) const noexcept
	Return TRUE if the widget is in the path from root to the leaf focused. More...
bool	isLeafFocused (void) const noexcept
	< Return TRUE if it is in the focus path and it is the leaf of that path. More...
Widget *	whoIsFocused (void)
	Get the leaf focused widget in the tree, or nullptr if none. More...
void	acquireFocus (const PointingStatus *m=nullptr)
	Give the focus to this widget and quit it from the current focused one. More...
void	releaseFocus (void)
	Quit focus from this leaf widget or below it; no one acquires it. More...
void	drawAll (const CharRect &rect)
	Calculate and set the placement of all widgets within RECT and draw'em. More...
Widget *	redrawAll (void)
	Recalculate, place and redraw all widgets that have changed in the tree. More...
void	redrawMe (void)
	Recalculate and place all widgets in the tree forcing this to be drawn. More...
void	drawMe (void)
	Just force to draw the widget in the current drawing zone. More...
const AreaFitting &	fittingNeeds (void) const noexcept
	< Return the last calculation of the fitting needs of the widget. More...
virtual Widget *	setDrawingZone (const CharRect &zone)
	Set the final drawing zone for the widget and the aligned one. More...
const CharRect &	drawingZone (void) const noexcept
	< Get the drawing zone decided for the widget within the global screen. More...
const CharRect &	alignedDrawingZone (void) const noexcept
	< Get the part of the drawing zone that is already aligned. More...
virtual void	moveDrawingZones (IntDist incx, IntDist incy) noexcept
	Move the drawing and aligned zones corners by those increments. More...
bool	drawn (void) const noexcept
	Return TRUE if the widget has already been drawn in current dimensions. More...
void	undraw (void) noexcept
	Method for external agents (e.g., Windows) to mark the widget undrawn. More...
void	setExplanations (bool setit=true) noexcept
	< Set/unset the generation of explanations when calculating drawing. More...
bool	getExplanations (void) const noexcept
	Return the current status of drawing explanations. More...
std::string	traceOfDrawing (bool withoutprivate=true) const
	< Return an explanation with the drawing status of this and child widgets More...
virtual void	traceOfDrawingRecursive (size_t level, std::stringstream &ss, bool withoutprivate=true) const
	Same as traceOfDrawing() but indicating the depth level and using SS. More...
virtual ChainEventResult	chainEvent (const EventData &data)
	Deal with the event at this widget and its descendants (if container). More...
virtual void	setCallback (const CallbackRout &callback=NullCallback)
	Deal with the event at this widget and its descendants (if container). More...
const CallbackRout &	getCallback (void) const noexcept
	Get the current callback routine. More...
void	addCallback (const CallbackRout &cbk)
	Add callback CBK to the end of the current callback routine. More...

Additional Inherited Members
Public Types inherited from zxeco::gui::Widget
enum class	TravResult { FINISH_OK , FINISH_FAIL , BACKTRACK , CONTINUE }
	Possible results of observer when traversing widgets in the widget tree. More...
using	ID = int
	A numeric ID associated to the widget. More...
using	Ptr = std::shared_ptr< Widget >
	A polymorphic ptr to a widget. More...
using	TraverseObserver = std::function< TravResult(Widget &) >
enum class	HorAlign { LEFT , RIGHT , CENTER }
	Horizontal alignment of widgets within the areas of their containers. More...
enum class	VertAlign { TOP , BOTTOM , MIDDLE }
	Vertical alignment of widgets within the areas of their containers. More...
enum class	EventType { MOUSE , KEYBOARD , FOCUS }
	Kinds of events that the widgets may process from the graphical environ. More...
enum class	SubEvType {   MOUSE_MOVE , MOUSE_CLICK , MOUSE_UNCLICK , MOUSE_WHEEL ,   KEYB_PRESS , KEYB_UNPRESS , KEYB_TEXT , FOCUS_GOT ,   FOCUS_LOST }
	Concrete events for each event kind. More...
using	CallbackRout = std::function< bool(Widget &, const CallbackParms &)>
Static Public Member Functions inherited from zxeco::gui::Widget
static void	addGlobalTraces (Trace::Type traces) noexcept
	< Add TRACES to the currently active traces (initially none). More...
static void	delGlobalTraces (Trace::Type traces) noexcept
	< Delete the given traces from the current active ones. More...
static Trace::Type	isTracing (Trace::Type traces) noexcept
	< Return a non-zero value if any of TRACES is currently active. More...
static void	printTrace (Trace::Type trace, const std::string &tr)
	Put TR in console as a trace, with a mark indicating TRACE.
static void	printIfTrace (Trace::Type trace, const std::string &tr)
	The same as printTrace() but only print if any of TRACE is active. More...
Static Public Attributes inherited from zxeco::gui::Widget
static const CallbackRout	NullCallback
	Callback routine that does nothing. More...
static const std::string	kTraceBegin
	< Add TRACES to the currently active traces (initially none). More...
static const std::string	kTraceEnd
	< Add TRACES to the currently active traces (initially none). More...
Protected Member Functions inherited from zxeco::gui::Widget
virtual void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
virtual int	processEvent (const EventData &evdata, Widget *who)
void	addLineToExplanation (const std::string &line)
	Add LINE to the existing explanation in fitting_needs_. More...
Protected Attributes inherited from zxeco::gui::Widget
ID	id_
const std::string	name_
const WinColors *	pwincols_
const uint8_t *	udgs_
Window *	pwin_
CallbackRout	callback_
std::string	tooltiptext_
HorAlign	hal_
VertAlign	val_
AreaFitting	fitting_needs_
CharRect	drawing_zone_
CharRect	aligned_drawing_zone_
Widget *	parent_
bool	explaindrawing_
Static Protected Attributes inherited from zxeco::gui::Widget
static Trace::Type	traces_
	Currently active traces. More...

Constructor & Destructor Documentation

ChoiceWidget()

zxeco::gui::ChoiceWidget::ChoiceWidget	(	ID	id,
		const std::string &	name,
		const Label::Vector &	labels,
		char	kindofselection,
		bool	horizorvert = false,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor. Labels are copied internally. They can contain ctrl color.

After construction, all options are unselected.

Parameters

kindofselection	can be 'M' (multiple) or 'S' (single).
horizorvert	indicates whether the choices are drawn in a vertical stack (false) or in horizontal (true).

Member Function Documentation

numberOfChoices()

size_t zxeco::gui::ChoiceWidget::numberOfChoices ( void  ) const

inlinenoexcept

Return the number of choices. *‍/.

Definition at line 332 of file ZXWidgetsSimple.h.

isSelected()

bool zxeco::gui::ChoiceWidget::isSelected ( size_t  who ) const

inline

Return TRUE if the given option is currently selected.

Definition at line 335 of file ZXWidgetsSimple.h.

setSelect()

void zxeco::gui::ChoiceWidget::setSelect ( size_t  who, bool  select = true  )

inline

Parameters

select

Set the selection status of WHO option.

Definition at line 341 of file ZXWidgetsSimple.h.

toggleSelect()

void zxeco::gui::ChoiceWidget::toggleSelect ( size_t  who )

inline

Parameters

who	Toggle the selection status of WHO option.

Definition at line 346 of file ZXWidgetsSimple.h.

setAll()

void zxeco::gui::ChoiceWidget::setAll ( bool  select = true )

inline

Parameters

select

Set the selection of all options. May throw if not a multiple selection widget.

Definition at line 350 of file ZXWidgetsSimple.h.

toggleAll()

void zxeco::gui::ChoiceWidget::toggleAll ( void  )

inline

Toggle the selection of all options.

Throw if not a multiple selection widget.

Definition at line 356 of file ZXWidgetsSimple.h.

labels()

const LabelList & zxeco::gui::ChoiceWidget::labels ( void  ) const

inlinenoexcept

Return the labels used by the widget.

Definition at line 359 of file ZXWidgetsSimple.h.

className()

const char * zxeco::gui::ChoiceWidget::className ( void  ) const

inlinevirtualnoexcept

Must return a text with the name of the class.

The text should be a literal local to the method, since text literals have static storage and therefore exist for the entire duration of the program.

Implements zxeco::gui::Widget.

Definition at line 365 of file ZXWidgetsSimple.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::ChoiceWidget::calcFittingNeeds ( const CharArea &  area )

virtual

Must calculate the widget fitting within the dimensions of AREA.

It must consider all the content of the widget, set the visibility or invisibility of the children if it is a container with dynamically visible children (e.g., scroll slides), store internally the result of the fitting into the protected member fitting_needs_, and return a reference to it.

If the calculations lead to an unfitting situation, the widgetcause field of the result must indicate the first (lowest) widget that produced that unfit.

The area needed calculated by this method must be equal or smaller than AREA, and must be considered to begin at the corner (0,0) of AREA. It'll be used for drawing.

This method will be called at least once before a widget can be drawn (it needs not to be called again as long as the widget drawing dimensions do not change). It will not be called if the widget is invisible (invisible widgets occupy no space when drawing). Recall that the root widget of the widget tree is always considered visible.

The ContainerWidget class provide code for this in charge of calling their children method. Derived containers should call that base method to complete their calculations.

Implements zxeco::gui::Widget.

zxeco::gui::SeparatorWidget

class zxeco::gui::SeparatorWidget

A separator between adjacent widgets.

Definition at line 392 of file ZXWidgetsSimple.h.

Inheritance diagram for zxeco::gui::SeparatorWidget:

Collaboration diagram for zxeco::gui::SeparatorWidget:

Public Member Functions
	SeparatorWidget (ID id, const std::string &name, CharDist separation=1)
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Public Member Functions inherited from zxeco::gui::Widget
	Widget (ID id, const std::string &name, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
	Widget (const Widget &)=delete
	Constructor. More...
	Widget (Widget &&)=delete
	Constructor. More...
Widget &	operator= (const Widget &)=delete
	Constructor. More...
Widget &	operator= (Widget &&)=delete
	Constructor. More...
virtual	~Widget (void)=default
	Just to activate polymorphic deletes.
std::string	idText (bool withpointer=false) const
	Return a text with the identification of this widget. More...
virtual bool	isContainer (void) const noexcept
	Return whether the widget is a container of other widgets. More...
bool	isUserContainer (void) const noexcept
	Return whether the widget is a USER-type container. More...
ID	getID (void) const noexcept
	Return the ID assigned to the widget at creation. More...
void	changeID (ID id) noexcept
	Change the ID without checking for duplicates in this widget tree. More...
const std::string &	getName (void) const noexcept
	Return the name of the widget. More...
bool	operator== (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
bool	operator!= (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
virtual std::pair< bool, const CharRect * >	hasFocusZone (void) const noexcept
	< Must return TRUE and the zone if the widget contains a focus-able zone. More...
virtual void	setWindow (Window &win) noexcept
	Set the Window where the widget is being managed. More...
virtual void	setWinColors (const WinColors &wincols) noexcept
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
const WinColors &	getWinColors (void) const noexcept
	Return the current window colors. More...
virtual void	setUDGs (const uint8_t *udgs)
	Assign an UDG character set for the widget drawing (do not copy them). More...
const uint8_t *	getUDGs (void)
	Return the current UDGs. *‍/. More...
virtual void	setTooltip (const std::string &ttt)
	Must return a text with the name of the class. More...
const std::string &	getTooltip (void) const noexcept
	Return the tooltip for the widget. More...
void	setParent (Widget *parent)
	Sets the parent of the widget to PARENT, that must outlive it. More...
Widget *	getParent (void) const noexcept
	Return a pointer to the parent of the widget, or nullptr if none. More...
Widget *	getRoot (void)
	Return a pointer to the root widget of the tree. More...
bool	isRoot (void) const noexcept
	Return TRUE if this widget is the root of the tree. More...
bool	isDescendantOf (Widget &w) const
	Return TRUE if this is W or a descendant of W. More...
Widget *	searchID (ID id) const
	Search the first appearance of the given ID in this and its descendants. More...
ID	maxUsedID (void) const
	Search in this widget and its descendants the maximum ID used. More...
TravResult	traverse (const TraverseObserver &obs)
	Traverse this widget and its descendants, calling OBS on each one. More...
TravResult	revTraverse (const TraverseObserver &obs)
	Traverse this widget and its ascendants, calling OBS on each one. More...
void	setVisibility (bool visible=true)
	Set the desired visibility of the widget. More...
void	setVisibilityNoRedrawing (bool vis) noexcept
	Set the widget visibility without redrawing or modifying focus. More...
bool	getVisibility (void) const noexcept
	Get current visibility of the widget, considering also its parents. More...
void	setEnabled (bool enabled=true)
	Set whether the widget is enabld or disabld; drawRaw() widget if changd. More...
bool	getEnabled (void) const noexcept
	Get current enabled state of the widget, considering its parents. More...
bool	isFocusable (bool drawntoo=true) const
	Return TRUE if the widget is focusable now. More...
bool	isInFocusPath (void) const noexcept
	Return TRUE if the widget is in the path from root to the leaf focused. More...
bool	isLeafFocused (void) const noexcept
	< Return TRUE if it is in the focus path and it is the leaf of that path. More...
Widget *	whoIsFocused (void)
	Get the leaf focused widget in the tree, or nullptr if none. More...
void	acquireFocus (const PointingStatus *m=nullptr)
	Give the focus to this widget and quit it from the current focused one. More...
void	releaseFocus (void)
	Quit focus from this leaf widget or below it; no one acquires it. More...
void	drawAll (const CharRect &rect)
	Calculate and set the placement of all widgets within RECT and draw'em. More...
Widget *	redrawAll (void)
	Recalculate, place and redraw all widgets that have changed in the tree. More...
void	redrawMe (void)
	Recalculate and place all widgets in the tree forcing this to be drawn. More...
void	drawMe (void)
	Just force to draw the widget in the current drawing zone. More...
const AreaFitting &	fittingNeeds (void) const noexcept
	< Return the last calculation of the fitting needs of the widget. More...
virtual Widget *	setDrawingZone (const CharRect &zone)
	Set the final drawing zone for the widget and the aligned one. More...
const CharRect &	drawingZone (void) const noexcept
	< Get the drawing zone decided for the widget within the global screen. More...
const CharRect &	alignedDrawingZone (void) const noexcept
	< Get the part of the drawing zone that is already aligned. More...
virtual void	moveDrawingZones (IntDist incx, IntDist incy) noexcept
	Move the drawing and aligned zones corners by those increments. More...
bool	drawn (void) const noexcept
	Return TRUE if the widget has already been drawn in current dimensions. More...
void	undraw (void) noexcept
	Method for external agents (e.g., Windows) to mark the widget undrawn. More...
void	setExplanations (bool setit=true) noexcept
	< Set/unset the generation of explanations when calculating drawing. More...
bool	getExplanations (void) const noexcept
	Return the current status of drawing explanations. More...
std::string	traceOfDrawing (bool withoutprivate=true) const
	< Return an explanation with the drawing status of this and child widgets More...
virtual void	traceOfDrawingRecursive (size_t level, std::stringstream &ss, bool withoutprivate=true) const
	Same as traceOfDrawing() but indicating the depth level and using SS. More...
virtual ChainEventResult	chainEvent (const EventData &data)
	Deal with the event at this widget and its descendants (if container). More...
virtual void	setCallback (const CallbackRout &callback=NullCallback)
	Deal with the event at this widget and its descendants (if container). More...
const CallbackRout &	getCallback (void) const noexcept
	Get the current callback routine. More...
void	addCallback (const CallbackRout &cbk)
	Add callback CBK to the end of the current callback routine. More...

Additional Inherited Members
Public Types inherited from zxeco::gui::Widget
enum class	TravResult { FINISH_OK , FINISH_FAIL , BACKTRACK , CONTINUE }
	Possible results of observer when traversing widgets in the widget tree. More...
using	ID = int
	A numeric ID associated to the widget. More...
using	Ptr = std::shared_ptr< Widget >
	A polymorphic ptr to a widget. More...
using	TraverseObserver = std::function< TravResult(Widget &) >
enum class	HorAlign { LEFT , RIGHT , CENTER }
	Horizontal alignment of widgets within the areas of their containers. More...
enum class	VertAlign { TOP , BOTTOM , MIDDLE }
	Vertical alignment of widgets within the areas of their containers. More...
enum class	EventType { MOUSE , KEYBOARD , FOCUS }
	Kinds of events that the widgets may process from the graphical environ. More...
enum class	SubEvType {   MOUSE_MOVE , MOUSE_CLICK , MOUSE_UNCLICK , MOUSE_WHEEL ,   KEYB_PRESS , KEYB_UNPRESS , KEYB_TEXT , FOCUS_GOT ,   FOCUS_LOST }
	Concrete events for each event kind. More...
using	CallbackRout = std::function< bool(Widget &, const CallbackParms &)>
Static Public Member Functions inherited from zxeco::gui::Widget
static void	addGlobalTraces (Trace::Type traces) noexcept
	< Add TRACES to the currently active traces (initially none). More...
static void	delGlobalTraces (Trace::Type traces) noexcept
	< Delete the given traces from the current active ones. More...
static Trace::Type	isTracing (Trace::Type traces) noexcept
	< Return a non-zero value if any of TRACES is currently active. More...
static void	printTrace (Trace::Type trace, const std::string &tr)
	Put TR in console as a trace, with a mark indicating TRACE.
static void	printIfTrace (Trace::Type trace, const std::string &tr)
	The same as printTrace() but only print if any of TRACE is active. More...
Static Public Attributes inherited from zxeco::gui::Widget
static const CallbackRout	NullCallback
	Callback routine that does nothing. More...
static const std::string	kTraceBegin
	< Add TRACES to the currently active traces (initially none). More...
static const std::string	kTraceEnd
	< Add TRACES to the currently active traces (initially none). More...
Protected Member Functions inherited from zxeco::gui::Widget
virtual void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
virtual int	processEvent (const EventData &evdata, Widget *who)
void	addLineToExplanation (const std::string &line)
	Add LINE to the existing explanation in fitting_needs_. More...
Protected Attributes inherited from zxeco::gui::Widget
ID	id_
const std::string	name_
const WinColors *	pwincols_
const uint8_t *	udgs_
Window *	pwin_
CallbackRout	callback_
std::string	tooltiptext_
HorAlign	hal_
VertAlign	val_
AreaFitting	fitting_needs_
CharRect	drawing_zone_
CharRect	aligned_drawing_zone_
Widget *	parent_
bool	explaindrawing_
Static Protected Attributes inherited from zxeco::gui::Widget
static Trace::Type	traces_
	Currently active traces. More...

Constructor & Destructor Documentation

SeparatorWidget()

zxeco::gui::SeparatorWidget::SeparatorWidget ( ID  id, const std::string &  name, CharDist  separation = 1  )

inline

Definition at line 396 of file ZXWidgetsSimple.h.

Member Function Documentation

className()

const char * zxeco::gui::SeparatorWidget::className ( void  ) const

inlinevirtualnoexcept

Must return a text with the name of the class.

The text should be a literal local to the method, since text literals have static storage and therefore exist for the entire duration of the program.

Implements zxeco::gui::Widget.

Definition at line 405 of file ZXWidgetsSimple.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::SeparatorWidget::calcFittingNeeds ( const CharArea &  area )

virtual

Must calculate the widget fitting within the dimensions of AREA.

It must consider all the content of the widget, set the visibility or invisibility of the children if it is a container with dynamically visible children (e.g., scroll slides), store internally the result of the fitting into the protected member fitting_needs_, and return a reference to it.

If the calculations lead to an unfitting situation, the widgetcause field of the result must indicate the first (lowest) widget that produced that unfit.

The area needed calculated by this method must be equal or smaller than AREA, and must be considered to begin at the corner (0,0) of AREA. It'll be used for drawing.

This method will be called at least once before a widget can be drawn (it needs not to be called again as long as the widget drawing dimensions do not change). It will not be called if the widget is invisible (invisible widgets occupy no space when drawing). Recall that the root widget of the widget tree is always considered visible.

The ContainerWidget class provide code for this in charge of calling their children method. Derived containers should call that base method to complete their calculations.

Implements zxeco::gui::Widget.

zxeco::gui::ImageWidget

class zxeco::gui::ImageWidget

A widget consisting in just one image.

< If you need clickable images, use the ButtonWidget instead.

Definition at line 422 of file ZXWidgetsSimple.h.

Inheritance diagram for zxeco::gui::ImageWidget:

Collaboration diagram for zxeco::gui::ImageWidget:

Public Member Functions
	ImageWidget (ID id, const std::string &name, const DoubleGraphic &img, const CharRect &region, const std::string &tooltip="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor for an image. The image is copied internally. More...
const DoubleGraphic &	getImage (void) const noexcept
	Return the current image. More...
void	setImage (const DoubleGraphic &img, const CharRect &region)
	Change the image. Throw if it is empty. Copy it internally.
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Public Member Functions inherited from zxeco::gui::Widget
	Widget (ID id, const std::string &name, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
	Widget (const Widget &)=delete
	Constructor. More...
	Widget (Widget &&)=delete
	Constructor. More...
Widget &	operator= (const Widget &)=delete
	Constructor. More...
Widget &	operator= (Widget &&)=delete
	Constructor. More...
virtual	~Widget (void)=default
	Just to activate polymorphic deletes.
std::string	idText (bool withpointer=false) const
	Return a text with the identification of this widget. More...
virtual bool	isContainer (void) const noexcept
	Return whether the widget is a container of other widgets. More...
bool	isUserContainer (void) const noexcept
	Return whether the widget is a USER-type container. More...
ID	getID (void) const noexcept
	Return the ID assigned to the widget at creation. More...
void	changeID (ID id) noexcept
	Change the ID without checking for duplicates in this widget tree. More...
const std::string &	getName (void) const noexcept
	Return the name of the widget. More...
bool	operator== (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
bool	operator!= (const Widget &oth) const noexcept
	Operator to detect unique identities in widgets. More...
virtual std::pair< bool, const CharRect * >	hasFocusZone (void) const noexcept
	< Must return TRUE and the zone if the widget contains a focus-able zone. More...
virtual void	setWindow (Window &win) noexcept
	Set the Window where the widget is being managed. More...
virtual void	setWinColors (const WinColors &wincols) noexcept
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
const WinColors &	getWinColors (void) const noexcept
	Return the current window colors. More...
virtual void	setUDGs (const uint8_t *udgs)
	Assign an UDG character set for the widget drawing (do not copy them). More...
const uint8_t *	getUDGs (void)
	Return the current UDGs. *‍/. More...
virtual void	setTooltip (const std::string &ttt)
	Must return a text with the name of the class. More...
const std::string &	getTooltip (void) const noexcept
	Return the tooltip for the widget. More...
void	setParent (Widget *parent)
	Sets the parent of the widget to PARENT, that must outlive it. More...
Widget *	getParent (void) const noexcept
	Return a pointer to the parent of the widget, or nullptr if none. More...
Widget *	getRoot (void)
	Return a pointer to the root widget of the tree. More...
bool	isRoot (void) const noexcept
	Return TRUE if this widget is the root of the tree. More...
bool	isDescendantOf (Widget &w) const
	Return TRUE if this is W or a descendant of W. More...
Widget *	searchID (ID id) const
	Search the first appearance of the given ID in this and its descendants. More...
ID	maxUsedID (void) const
	Search in this widget and its descendants the maximum ID used. More...
TravResult	traverse (const TraverseObserver &obs)
	Traverse this widget and its descendants, calling OBS on each one. More...
TravResult	revTraverse (const TraverseObserver &obs)
	Traverse this widget and its ascendants, calling OBS on each one. More...
void	setVisibility (bool visible=true)
	Set the desired visibility of the widget. More...
void	setVisibilityNoRedrawing (bool vis) noexcept
	Set the widget visibility without redrawing or modifying focus. More...
bool	getVisibility (void) const noexcept
	Get current visibility of the widget, considering also its parents. More...
void	setEnabled (bool enabled=true)
	Set whether the widget is enabld or disabld; drawRaw() widget if changd. More...
bool	getEnabled (void) const noexcept
	Get current enabled state of the widget, considering its parents. More...
bool	isFocusable (bool drawntoo=true) const
	Return TRUE if the widget is focusable now. More...
bool	isInFocusPath (void) const noexcept
	Return TRUE if the widget is in the path from root to the leaf focused. More...
bool	isLeafFocused (void) const noexcept
	< Return TRUE if it is in the focus path and it is the leaf of that path. More...
Widget *	whoIsFocused (void)
	Get the leaf focused widget in the tree, or nullptr if none. More...
void	acquireFocus (const PointingStatus *m=nullptr)
	Give the focus to this widget and quit it from the current focused one. More...
void	releaseFocus (void)
	Quit focus from this leaf widget or below it; no one acquires it. More...
void	drawAll (const CharRect &rect)
	Calculate and set the placement of all widgets within RECT and draw'em. More...
Widget *	redrawAll (void)
	Recalculate, place and redraw all widgets that have changed in the tree. More...
void	redrawMe (void)
	Recalculate and place all widgets in the tree forcing this to be drawn. More...
void	drawMe (void)
	Just force to draw the widget in the current drawing zone. More...
const AreaFitting &	fittingNeeds (void) const noexcept
	< Return the last calculation of the fitting needs of the widget. More...
virtual Widget *	setDrawingZone (const CharRect &zone)
	Set the final drawing zone for the widget and the aligned one. More...
const CharRect &	drawingZone (void) const noexcept
	< Get the drawing zone decided for the widget within the global screen. More...
const CharRect &	alignedDrawingZone (void) const noexcept
	< Get the part of the drawing zone that is already aligned. More...
virtual void	moveDrawingZones (IntDist incx, IntDist incy) noexcept
	Move the drawing and aligned zones corners by those increments. More...
bool	drawn (void) const noexcept
	Return TRUE if the widget has already been drawn in current dimensions. More...
void	undraw (void) noexcept
	Method for external agents (e.g., Windows) to mark the widget undrawn. More...
void	setExplanations (bool setit=true) noexcept
	< Set/unset the generation of explanations when calculating drawing. More...
bool	getExplanations (void) const noexcept
	Return the current status of drawing explanations. More...
std::string	traceOfDrawing (bool withoutprivate=true) const
	< Return an explanation with the drawing status of this and child widgets More...
virtual void	traceOfDrawingRecursive (size_t level, std::stringstream &ss, bool withoutprivate=true) const
	Same as traceOfDrawing() but indicating the depth level and using SS. More...
virtual ChainEventResult	chainEvent (const EventData &data)
	Deal with the event at this widget and its descendants (if container). More...
virtual void	setCallback (const CallbackRout &callback=NullCallback)
	Deal with the event at this widget and its descendants (if container). More...
const CallbackRout &	getCallback (void) const noexcept
	Get the current callback routine. More...
void	addCallback (const CallbackRout &cbk)
	Add callback CBK to the end of the current callback routine. More...

Additional Inherited Members
Public Types inherited from zxeco::gui::Widget
enum class	TravResult { FINISH_OK , FINISH_FAIL , BACKTRACK , CONTINUE }
	Possible results of observer when traversing widgets in the widget tree. More...
using	ID = int
	A numeric ID associated to the widget. More...
using	Ptr = std::shared_ptr< Widget >
	A polymorphic ptr to a widget. More...
using	TraverseObserver = std::function< TravResult(Widget &) >
enum class	HorAlign { LEFT , RIGHT , CENTER }
	Horizontal alignment of widgets within the areas of their containers. More...
enum class	VertAlign { TOP , BOTTOM , MIDDLE }
	Vertical alignment of widgets within the areas of their containers. More...
enum class	EventType { MOUSE , KEYBOARD , FOCUS }
	Kinds of events that the widgets may process from the graphical environ. More...
enum class	SubEvType {   MOUSE_MOVE , MOUSE_CLICK , MOUSE_UNCLICK , MOUSE_WHEEL ,   KEYB_PRESS , KEYB_UNPRESS , KEYB_TEXT , FOCUS_GOT ,   FOCUS_LOST }
	Concrete events for each event kind. More...
using	CallbackRout = std::function< bool(Widget &, const CallbackParms &)>
Static Public Member Functions inherited from zxeco::gui::Widget
static void	addGlobalTraces (Trace::Type traces) noexcept
	< Add TRACES to the currently active traces (initially none). More...
static void	delGlobalTraces (Trace::Type traces) noexcept
	< Delete the given traces from the current active ones. More...
static Trace::Type	isTracing (Trace::Type traces) noexcept
	< Return a non-zero value if any of TRACES is currently active. More...
static void	printTrace (Trace::Type trace, const std::string &tr)
	Put TR in console as a trace, with a mark indicating TRACE.
static void	printIfTrace (Trace::Type trace, const std::string &tr)
	The same as printTrace() but only print if any of TRACE is active. More...
Static Public Attributes inherited from zxeco::gui::Widget
static const CallbackRout	NullCallback
	Callback routine that does nothing. More...
static const std::string	kTraceBegin
	< Add TRACES to the currently active traces (initially none). More...
static const std::string	kTraceEnd
	< Add TRACES to the currently active traces (initially none). More...
Protected Member Functions inherited from zxeco::gui::Widget
virtual void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
virtual int	processEvent (const EventData &evdata, Widget *who)
void	addLineToExplanation (const std::string &line)
	Add LINE to the existing explanation in fitting_needs_. More...
Protected Attributes inherited from zxeco::gui::Widget
ID	id_
const std::string	name_
const WinColors *	pwincols_
const uint8_t *	udgs_
Window *	pwin_
CallbackRout	callback_
std::string	tooltiptext_
HorAlign	hal_
VertAlign	val_
AreaFitting	fitting_needs_
CharRect	drawing_zone_
CharRect	aligned_drawing_zone_
Widget *	parent_
bool	explaindrawing_
Static Protected Attributes inherited from zxeco::gui::Widget
static Trace::Type	traces_
	Currently active traces. More...

Constructor & Destructor Documentation

ImageWidget()

zxeco::gui::ImageWidget::ImageWidget ( ID  id, const std::string &  name, const DoubleGraphic &  img, const CharRect &  region, const std::string &  tooltip = "", HorAlign  hal = HorAlign::LEFT, VertAlign  val = VertAlign::TOP  )

inline

Constructor for an image. The image is copied internally.

Only the REGION part of the image is copied.

Definition at line 426 of file ZXWidgetsSimple.h.

Member Function Documentation

getImage()

const DoubleGraphic & zxeco::gui::ImageWidget::getImage ( void  ) const

inlinenoexcept

Return the current image.

Definition at line 437 of file ZXWidgetsSimple.h.

className()

const char * zxeco::gui::ImageWidget::className ( void  ) const

inlinevirtualnoexcept

Must return a text with the name of the class.

The text should be a literal local to the method, since text literals have static storage and therefore exist for the entire duration of the program.

Implements zxeco::gui::Widget.

Definition at line 444 of file ZXWidgetsSimple.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::ImageWidget::calcFittingNeeds ( const CharArea &  area )

virtual

Must calculate the widget fitting within the dimensions of AREA.

It must consider all the content of the widget, set the visibility or invisibility of the children if it is a container with dynamically visible children (e.g., scroll slides), store internally the result of the fitting into the protected member fitting_needs_, and return a reference to it.

If the calculations lead to an unfitting situation, the widgetcause field of the result must indicate the first (lowest) widget that produced that unfit.

The area needed calculated by this method must be equal or smaller than AREA, and must be considered to begin at the corner (0,0) of AREA. It'll be used for drawing.

This method will be called at least once before a widget can be drawn (it needs not to be called again as long as the widget drawing dimensions do not change). It will not be called if the widget is invisible (invisible widgets occupy no space when drawing). Recall that the root widget of the widget tree is always considered visible.

The ContainerWidget class provide code for this in charge of calling their children method. Derived containers should call that base method to complete their calculations.

Implements zxeco::gui::Widget.