Widgets system for the GUI

Description

This module provides the widgets for making GUIs for the ZXEcosystem.

Collaboration diagram for Widgets system for the GUI:

Modules
	Base for all widgets in the GUI
	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::CanvasWidget
	A possibly scrollable canvas where to write/draw things. More...
class	zxeco::gui::ComboBoxWidget
	A widget that allows the user to select one from a deployable list, and edit. More...
class	zxeco::gui::CounterWidget
	A counter (on integer values). More...
class	zxeco::gui::FileBrowserWidget
	A widget that allows the user to browse files in the filesystem. More...
class	zxeco::gui::ListWidget
	A sequence of text lines with possibly scroll bars and selection of elements. More...
class	zxeco::gui::MenuBarWidget
	A widget to show a horizontal menu bar with a menu in each element. More...
class	zxeco::gui::WidgetsForm< Underlying >
	Class from which any form must derive. More...
class	zxeco::gui::WidgetsFormBroker
	The subscription/production intercommunicator of a number of forms. More...
class	zxeco::gui::SlideWidget
	A slide, either horizontal or vertical, e.g., to serve as scroll bar. More...
class	zxeco::gui::TextEditorWidget
	A widget that shows an area for editing multi-line text with word-wrapping. More...

Functions
void	zxeco::gui::WidgetsForm< Underlying >::checkIsPopulated (const std::string &place="") const
	Throw if unpopulated. More...

---

Class Documentation

zxeco::gui::CanvasWidget

class zxeco::gui::CanvasWidget

A possibly scrollable canvas where to write/draw things.

The user must attach suitable event callback functions (setCallback method) to capture events and do their effects on the canvas by writing/drawing on it. This class does not store the complete canvas as a screen; i.e., it is assumed to be calculated in each user draw callback.

Definition at line 44 of file ZXWidgetCanvas.h.

Inheritance diagram for zxeco::gui::CanvasWidget:

Collaboration diagram for zxeco::gui::CanvasWidget:

Public Types
using	DrawCallback = std::function< void(CanvasWidget &) >
	Callback called every time the viewport is moved or the canvas drawn. More...
Public Types inherited from zxeco::gui::ContainerWidget
enum class	OrType { VERTICAL , HORIZONTAL , DEEP }
	Types of containers according to the spatial orientation of their contnt. More...
enum class	CCType { USER , OWN }
	Types of container according to the creation of their children. More...
enum class	FMType { NORMAL , PRESERVE }
	Types of management of focus among descendant widgets. More...
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 &)>
Public Member Functions
	CanvasWidget (ID id, const std::string &name, const CharArea &totdims, const CharArea &viewportdims, const DrawCallback &drawcallback, bool movekeys=false, CharDist inchor=1, CharDist incver=1, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. The underlying canvas is also constructed and owned here. More...
void	changeDrawCallback (const DrawCallback &newcbk)
Screen &	canvas (void)
	Return the portion of screen where to write/draw; size of the viewport. More...
CharRect	viewport (void) const
	Return the current location of the viewport within underlying canvas. More...
void	moveViewport (const CharCursor &corner)
	Set the new viewport to the given one. More...
CharCursor	maxViewportPos (void) const
	Return the maximum coordinates that the viewport corner may have. More...
bool	eventProcessedByViewport (const CallbackParms &cbp) const noexcept
	< Return TRUE if the event has processed within viewport and not scrolls. More...
bool	mouseCharPosInViewport (const PointingStatus &mouse, CharCursor &relpos) const
	Calculate the char-relative position of MOUSE into the canvas. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
void	setTooltip (const std::string &ttt) override
	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...
Widget *	setDrawingZone (const CharRect &zone)
	Set the final drawing zone for the widget and the aligned one. More...
Public Member Functions inherited from zxeco::gui::ContainerWidget
	ContainerWidget (ID id, const std::string &name, CCType cctype=CCType::USER, OrType ortype=OrType::VERTICAL, FMType foctype=FMType::NORMAL, bool withframe=false, const std::string &title="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP, const std::string &tooltiptext="")
	Constructor. More...
CCType	ccType (void) const noexcept
	Return its children creation type. More...
OrType	orType (void) const noexcept
	Return its orientation type. More...
FMType	focusMngType (void) const noexcept
	Return its focus management type. More...
bool	getFrame (void) const noexcept
	Return whether the widget has currently a frame. More...
const std::string &	getTitle (void) const noexcept
	Return the widtget current title, or empty if none. More...
bool	cursorInTopFrame (const CharCursor &cc) const
	Return TRUE if CC lies in the top (title) line of the container frame. More...
const PVector &	children (void) noexcept
	Return the widgets contained into the container. More...
Widget *	addChild (const Ptr &ch)
	Return its children creation type. More...
void	setDeepSelected (PVector::size_type who)
	Set the WHO-th children as the one visible if the container is DEEP. More...
PVector::size_type	getDeepSelected (void) const
	Get the WHO-th children that is the one visible if the cont. is DEEP. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
bool	isContainer (void) const noexcept override
	Return whether the widget is a container of other widgets. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. More...
void	moveDrawingZones (IntDist incx, IntDist incy) noexcept override
	Move the drawing and aligned zones corners by those increments. More...
void	setWindow (Window &win) noexcept override
	Set the Window where the widget is being managed. More...
void	setWinColors (const WinColors &wincols) noexcept override
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
ChainEventResult	chainEvent (const EventData &data) override
	Deal with the event at this widget and its descendants (if container). 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...
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...
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...
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...
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	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
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...

Member Typedef Documentation

DrawCallback

using zxeco::gui::CanvasWidget::DrawCallback = std::function< void(CanvasWidget &) >

Callback called every time the viewport is moved or the canvas drawn.

Definition at line 48 of file ZXWidgetCanvas.h.

Constructor & Destructor Documentation

CanvasWidget()

zxeco::gui::CanvasWidget::CanvasWidget	(	ID	id,
		const std::string &	name,
		const CharArea &	totdims,
		const CharArea &	viewportdims,
		const DrawCallback &	drawcallback,
		bool	movekeys = false,
		CharDist	inchor = 1,
		CharDist	incver = 1,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor. The underlying canvas is also constructed and owned here.

The canvas has a viewport that is the only portion shown to the user, while the underlying screen is larger (totdims). The viewport can be moved over that screen.

Parameters

totdims	are the dimensions of the underlying screen. They cannot be empty.
viewportdims	are the dimensions of the viewport (not considering the possible scroll bars), and must be less than or equal to totdims. If empty, the viewport is adjusted to the available area (keeping it always less than or equal to totdims). If the viewport is less than totdims, scrolls are added, placed out of it.
drawcallback	is a routine that will be called at any time the user changes the viewport location on the total underlying canvas, and also each time the canvas widget is drawn. Its purpose is to fill the canvas visible screen -viewport- with the corresponding drawing; you can get the Screen to draw on from the canvas() method. NOTE: Do not call the same routine on your own; in the case you need to redraw the canvas content out of these cases, call drawMe() to do that.
movekeys	indicates whether to move automatically the viewport when the arrow keys or the mouse wheel are used.
inchor,incver	are the step size of the movements in the scroll slides, in chars.

Member Function Documentation

changeDrawCallback()

void zxeco::gui::CanvasWidget::changeDrawCallback ( const DrawCallback &  newcbk )

inline

Parameters

newcbk

Change the current callback for NEWCBK.

Definition at line 84 of file ZXWidgetCanvas.h.

canvas()

Screen & zxeco::gui::CanvasWidget::canvas

(

void

)

Return the portion of screen where to write/draw; size of the viewport.

The returned screen is a delegated subscreen onto the zxeco::screen(). You need to call viewport() to get the position of that viewport into the underlying complete canvas. That screen is a focusable zone in this widget, thus it can receive key input events. Throw if the widget is not drawn yet.

viewport()

CharRect zxeco::gui::CanvasWidget::viewport

(

void

)

const

Return the current location of the viewport within underlying canvas.

Throw if the widget has not been drawn yet.

moveViewport()

void zxeco::gui::CanvasWidget::moveViewport

(

const CharCursor &

corner

)

Set the new viewport to the given one.

Initially, the viewport is at (0,0). This method throws if the corner is out of the possible positions (see maxViewportPos) or if the widget is not drawn yet.

maxViewportPos()

CharCursor zxeco::gui::CanvasWidget::maxViewportPos

(

void

)

const

Return the maximum coordinates that the viewport corner may have.

The corner is the top-left one, and the maxima are calculated for the viewport area not to go outside the underlying screen even partially. Since the viewport size is not set until the widget is drawn, this method throw if the widget is not drawn.

eventProcessedByViewport()

bool zxeco::gui::CanvasWidget::eventProcessedByViewport ( const CallbackParms &  cbp ) const

inlinenoexcept

< Return TRUE if the event has processed within viewport and not scrolls.

< Return FALSE if the callback is for an event processed in the 'B'efore path during event chaining or by the scrolls. This method is to be called in the callback routine that is set for the CanvasWidget in order to distinguish where it was served.

Definition at line 114 of file ZXWidgetCanvas.h.

mouseCharPosInViewport()

bool zxeco::gui::CanvasWidget::mouseCharPosInViewport	(	const PointingStatus &	mouse,
		CharCursor &	relpos
	)		const

Calculate the char-relative position of MOUSE into the canvas.

Return FALSE if that mouse is out of the canvas; otherwise return TRUE and fill RELPOS with its relative position.

Note

Scroll slides are included in the canvas area.

className()

const char * zxeco::gui::CanvasWidget::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 132 of file ZXWidgetCanvas.h.

setTooltip()

void zxeco::gui::CanvasWidget::setTooltip ( const std::string &  ttt )

inlineoverridevirtual

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.

Parameters

ttt	Change the tooltip text to TTT, that can be empty but with no ctrl chrs Virtual for the case that a container wish to deploy the tooltip to one of its descendants.

Reimplemented from zxeco::gui::Widget.

Definition at line 133 of file ZXWidgetCanvas.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::CanvasWidget::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.

setDrawingZone()

Widget * zxeco::gui::CanvasWidget::setDrawingZone ( const CharRect &  zone )

virtual

Set the final drawing zone for the widget and the aligned one.

Return a pointer to the first (higher) widget in the tree equal or below this that gets an aligned drawing zone different from its current one (or its first zone if not drawn before), or nullptr if all widgets below this (including this) get the same zones as before. The available drawing zone of the widget is the space where it can align its content; the aligned zone is the final rectangle where it must be drawn, already aligned within the drawing zone.

ZONE.corner uses absolute coords within the global screen. ZONE can have the same area as the needed one or a different, larger one (that leaves room for alignment), but not smaller.

This method will be called after calculating the widget fitting needs & before drawing. It 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).

Container widgets override this method to deploy it to their children. Also, widgets derived from containers can override it to adjust the visibility of some children if that is to be calculated dynamically, since ZONE may be larger than the one proposed by calcFittingNeeds(), which may affect that visibility.

If the calculated aligned drawing zone is different from the previous one or if the widget was not previously drawn, sets the drawn_ flag to false. Otherwise, leave it unchanged.

Reimplemented from zxeco::gui::Widget.

zxeco::gui::ComboBoxWidget

class zxeco::gui::ComboBoxWidget

A widget that allows the user to select one from a deployable list, and edit.

The list itself is unmutable. This widget also works as a menu.

Definition at line 43 of file ZXWidgetComboBox.h.

Inheritance diagram for zxeco::gui::ComboBoxWidget:

Collaboration diagram for zxeco::gui::ComboBoxWidget:

Public Member Functions
	ComboBoxWidget (ID id, const std::string &name, const LabelList &l, const std::string &inittext="", CharDist maxwidths=0, bool editable=false, bool showing=true, bool deploybutton=true, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
const std::string &	text (void) const noexcept
	Return the current text in the editing zone. More...
const LabelList &	list (void) const
size_t	lastSelected (void) const noexcept
	Return the index in the list of the element that was selected last time. More...
void	clearLastSelected (void)
	Clear the last selected element. More...
void	setSelected (const std::string &txt)
	Set the given text as the selection in the edit area. More...
void	setSelected (size_t ind)
	Set the given index of the list as the current selection in the edit a. More...
bool	processedByEditing (const CallbackParms &cbps) const noexcept
	< Return TRUE if the event of CBPS was processed in the edition zone. More...
bool	itemLeftClicked (const CallbackParms &cbps) const noexcept
	< Return TRUE if the event of CBPS is a click on the list. More...
bool	itemLeftClickedOrEnter (const CallbackParms &cbps) const noexcept
	< Return TRUE if the event of CBPS is a click on the list or an enter. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
Public Member Functions inherited from zxeco::gui::ContainerWidget
	ContainerWidget (ID id, const std::string &name, CCType cctype=CCType::USER, OrType ortype=OrType::VERTICAL, FMType foctype=FMType::NORMAL, bool withframe=false, const std::string &title="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP, const std::string &tooltiptext="")
	Constructor. More...
CCType	ccType (void) const noexcept
	Return its children creation type. More...
OrType	orType (void) const noexcept
	Return its orientation type. More...
FMType	focusMngType (void) const noexcept
	Return its focus management type. More...
bool	getFrame (void) const noexcept
	Return whether the widget has currently a frame. More...
const std::string &	getTitle (void) const noexcept
	Return the widtget current title, or empty if none. More...
bool	cursorInTopFrame (const CharCursor &cc) const
	Return TRUE if CC lies in the top (title) line of the container frame. More...
const PVector &	children (void) noexcept
	Return the widgets contained into the container. More...
Widget *	addChild (const Ptr &ch)
	Return its children creation type. More...
void	setDeepSelected (PVector::size_type who)
	Set the WHO-th children as the one visible if the container is DEEP. More...
PVector::size_type	getDeepSelected (void) const
	Get the WHO-th children that is the one visible if the cont. is DEEP. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
bool	isContainer (void) const noexcept override
	Return whether the widget is a container of other widgets. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. More...
void	moveDrawingZones (IntDist incx, IntDist incy) noexcept override
	Move the drawing and aligned zones corners by those increments. More...
void	setWindow (Window &win) noexcept override
	Set the Window where the widget is being managed. More...
void	setWinColors (const WinColors &wincols) noexcept override
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
ChainEventResult	chainEvent (const EventData &data) override
	Deal with the event at this widget and its descendants (if container). 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...
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...
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...
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	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::ContainerWidget
enum class	OrType { VERTICAL , HORIZONTAL , DEEP }
	Types of containers according to the spatial orientation of their contnt. More...
enum class	CCType { USER , OWN }
	Types of container according to the creation of their children. More...
enum class	FMType { NORMAL , PRESERVE }
	Types of management of focus among descendant widgets. More...
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

ComboBoxWidget()

zxeco::gui::ComboBoxWidget::ComboBoxWidget	(	ID	id,
		const std::string &	name,
		const LabelList &	l,
		const std::string &	inittext = "",
		CharDist	maxwidths = 0,
		bool	editable = false,
		bool	showing = true,
		bool	deploybutton = true,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor.

Parameters

l	is a list containing the elements to deploy. It is copied internally in this widget, thus it can be safely deleted. It must have at least two markigns: #0 will be used for the cursor and therefore must be 'S' (single choice) and #1 for the selections, that must be 'S' (single choice). If a third marking exists (#2), it will indicate whether that element of the list must be shown enabled (true) or disabled (false); disabled markers have no effect when selected by the user.
inittext	is the initial text put in the selected element line. If it coincides with an entry in L, the lastSelected() method is prepared to return that one after the user selects another.
maxwidths	is the maximum width in chars of the line displaying the currently selected element, or 0 for taking the length of the longest element in l.
editable	indicates whether the selected element may be edited by the user or not.
deploybutton	indicates whether there is a deploy button at the right side of the combo (otherwise, clicking on the inittext zone will deploy).
showing	indicates whether to copy into the selected element line the one selected by the user. This parameter is only used if the widget is non- editable; otherwise, the selected element is always copied into that line.

Member Function Documentation

text()

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

inlinenoexcept

Return the current text in the editing zone.

Definition at line 77 of file ZXWidgetComboBox.h.

list()

const LabelList & zxeco::gui::ComboBoxWidget::list ( void  ) const

inline

Definition at line 80 of file ZXWidgetComboBox.h.

lastSelected()

size_t zxeco::gui::ComboBoxWidget::lastSelected ( void  ) const

inlinenoexcept

Return the index in the list of the element that was selected last time.

If no element was selected the last time the list was deployed, return the size of the list. The last element is updated before any 'after' call to the user callback, thus, it is available in that callback routine.

Definition at line 82 of file ZXWidgetComboBox.h.

clearLastSelected()

void zxeco::gui::ComboBoxWidget::clearLastSelected ( void  )

inline

Clear the last selected element.

This should be called after processing the last selected element in order to capture the next last selected element.

Definition at line 87 of file ZXWidgetComboBox.h.

setSelected() [1/2]

void zxeco::gui::ComboBoxWidget::setSelected

(

const std::string &

txt

)

Set the given text as the selection in the edit area.

If drawn, redraw the widget.

setSelected() [2/2]

void zxeco::gui::ComboBoxWidget::setSelected

(

size_t

ind

)

Set the given index of the list as the current selection in the edit a.

If drawn, redraw the widget.

processedByEditing()

bool zxeco::gui::ComboBoxWidget::processedByEditing ( const CallbackParms &  cbps ) const

inlinenoexcept

< Return TRUE if the event of CBPS was processed in the edition zone.

Definition at line 99 of file ZXWidgetComboBox.h.

itemLeftClicked()

bool zxeco::gui::ComboBoxWidget::itemLeftClicked ( const CallbackParms &  cbps ) const

inlinenoexcept

< Return TRUE if the event of CBPS is a click on the list.

Definition at line 104 of file ZXWidgetComboBox.h.

itemLeftClickedOrEnter()

bool zxeco::gui::ComboBoxWidget::itemLeftClickedOrEnter ( const CallbackParms &  cbps ) const

inlinenoexcept

< Return TRUE if the event of CBPS is a click on the list or an enter.

Definition at line 108 of file ZXWidgetComboBox.h.

className()

const char * zxeco::gui::ComboBoxWidget::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 113 of file ZXWidgetComboBox.h.

zxeco::gui::CounterWidget

class zxeco::gui::CounterWidget

A counter (on integer values).

Definition at line 38 of file ZXWidgetCounter.h.

Inheritance diagram for zxeco::gui::CounterWidget:

Collaboration diagram for zxeco::gui::CounterWidget:

Public Types
enum	: uint8_t { FAST_ARROWS = 1 , EXTREME_ARROWS = 2 }
	Kind of additional controls for the widget (to be OR-ed). More...
Public Types inherited from zxeco::gui::ContainerWidget
enum class	OrType { VERTICAL , HORIZONTAL , DEEP }
	Types of containers according to the spatial orientation of their contnt. More...
enum class	CCType { USER , OWN }
	Types of container according to the creation of their children. More...
enum class	FMType { NORMAL , PRESERVE }
	Types of management of focus among descendant widgets. More...
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 &)>
Public Member Functions
	CounterWidget (ID id, const std::string &name, int rangemin, int rangemax, bool editable=false, uint8_t addarrows=0, int fastinc=2, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. The initial numerical value will be rangemin. More...
int	value (void) const noexcept
	Return the current numerical value of the counter. More...
int	minValue (void) const noexcept
	Return the minimum value possible. More...
int	maxValue (void) const noexcept
	Return the minimum value possible. More...
void	setValue (int value)
	Change the current numerical value of the counter. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
Public Member Functions inherited from zxeco::gui::ContainerWidget
	ContainerWidget (ID id, const std::string &name, CCType cctype=CCType::USER, OrType ortype=OrType::VERTICAL, FMType foctype=FMType::NORMAL, bool withframe=false, const std::string &title="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP, const std::string &tooltiptext="")
	Constructor. More...
CCType	ccType (void) const noexcept
	Return its children creation type. More...
OrType	orType (void) const noexcept
	Return its orientation type. More...
FMType	focusMngType (void) const noexcept
	Return its focus management type. More...
bool	getFrame (void) const noexcept
	Return whether the widget has currently a frame. More...
const std::string &	getTitle (void) const noexcept
	Return the widtget current title, or empty if none. More...
bool	cursorInTopFrame (const CharCursor &cc) const
	Return TRUE if CC lies in the top (title) line of the container frame. More...
const PVector &	children (void) noexcept
	Return the widgets contained into the container. More...
Widget *	addChild (const Ptr &ch)
	Return its children creation type. More...
void	setDeepSelected (PVector::size_type who)
	Set the WHO-th children as the one visible if the container is DEEP. More...
PVector::size_type	getDeepSelected (void) const
	Get the WHO-th children that is the one visible if the cont. is DEEP. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
bool	isContainer (void) const noexcept override
	Return whether the widget is a container of other widgets. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. More...
void	moveDrawingZones (IntDist incx, IntDist incy) noexcept override
	Move the drawing and aligned zones corners by those increments. More...
void	setWindow (Window &win) noexcept override
	Set the Window where the widget is being managed. More...
void	setWinColors (const WinColors &wincols) noexcept override
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
ChainEventResult	chainEvent (const EventData &data) override
	Deal with the event at this widget and its descendants (if container). 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...
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...
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...
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	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
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...

Member Enumeration Documentation

anonymous enum

anonymous enum : uint8_t

Kind of additional controls for the widget (to be OR-ed).

These appear in addition to the always present inc/dec arrows, that work in increments/decrements of 1.

Enumerator
FAST_ARROWS	Provide increments/decrements > 1.
EXTREME_ARROWS	Provide motion to the extremes of the range.

Definition at line 45 of file ZXWidgetCounter.h.

Constructor & Destructor Documentation

CounterWidget()

zxeco::gui::CounterWidget::CounterWidget	(	ID	id,
		const std::string &	name,
		int	rangemin,
		int	rangemax,
		bool	editable = false,
		uint8_t	addarrows = 0,
		int	fastinc = 2,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor. The initial numerical value will be rangemin.

Parameters

rangemin,rangemax	are the limits of the values of the counter, and must be that rangemin < rangemax.
editable	indicates if the value can be edited by user typing, in addition to be changed by arrows.
addarrows	indicates which additional arrows to show.
fastinc	is only used if FAST_ARROWS, and defines the increment for those arrows. It must be > 1.

Member Function Documentation

value()

int zxeco::gui::CounterWidget::value ( void  ) const

inlinenoexcept

Return the current numerical value of the counter.

Definition at line 67 of file ZXWidgetCounter.h.

minValue()

int zxeco::gui::CounterWidget::minValue ( void  ) const

inlinenoexcept

Return the minimum value possible.

Definition at line 70 of file ZXWidgetCounter.h.

maxValue()

int zxeco::gui::CounterWidget::maxValue ( void  ) const

inlinenoexcept

Return the minimum value possible.

Definition at line 73 of file ZXWidgetCounter.h.

setValue()

void zxeco::gui::CounterWidget::setValue

(

int

value

)

Change the current numerical value of the counter.

Throw if out of range. Do nothing if VALUE is equal to the current value.

className()

const char * zxeco::gui::CounterWidget::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 82 of file ZXWidgetCounter.h.

zxeco::gui::FileBrowserWidget

class zxeco::gui::FileBrowserWidget

A widget that allows the user to browse files in the filesystem.

Note

Browsing with this widget does not change the current working path of the program. You must do that manually with std::filesystem::current_path().

Definition at line 43 of file ZXWidgetFileBrowser.h.

Inheritance diagram for zxeco::gui::FileBrowserWidget:

Collaboration diagram for zxeco::gui::FileBrowserWidget:

Public Types
enum	: uint8_t { WITH_TREE = 1 , WITH_PATH = 2 , WITH_EDIT = 4 }
	Elements that can have the widget. More...
Public Types inherited from zxeco::gui::ContainerWidget
enum class	OrType { VERTICAL , HORIZONTAL , DEEP }
	Types of containers according to the spatial orientation of their contnt. More...
enum class	CCType { USER , OWN }
	Types of container according to the creation of their children. More...
enum class	FMType { NORMAL , PRESERVE }
	Types of management of focus among descendant widgets. More...
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 &)>
Public Member Functions
	FileBrowserWidget (ID id, const std::string &name, uint8_t elements=WITH_TREE|WITH_PATH|WITH_EDIT, const std::filesystem::path &initpath=std::filesystem::path{}, const std::string &initedit="", char markingsinfiles='N', const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
bool	changeDir (const std::filesystem::path &path)
	Change the current path to the given one. More...
void	reload (void)
const std::string &	editedText (void) const
	Return the currently text in the editing line. More...
const std::filesystem::path &	browserPath (void) const noexcept
	< Return a ref to the current path of the browser (empty after creation). More...
bool	eventProcessedByTree (const CallbackParms &cbp) const noexcept
	< Return TRUE if the callback is for an event already processed by tree. More...
bool	eventProcessedByFiles (const CallbackParms &cbp) const noexcept
	< Return TRUE if the callback is for an event already processed by files. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. 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...
Public Member Functions inherited from zxeco::gui::ContainerWidget
	ContainerWidget (ID id, const std::string &name, CCType cctype=CCType::USER, OrType ortype=OrType::VERTICAL, FMType foctype=FMType::NORMAL, bool withframe=false, const std::string &title="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP, const std::string &tooltiptext="")
	Constructor. More...
CCType	ccType (void) const noexcept
	Return its children creation type. More...
OrType	orType (void) const noexcept
	Return its orientation type. More...
FMType	focusMngType (void) const noexcept
	Return its focus management type. More...
bool	getFrame (void) const noexcept
	Return whether the widget has currently a frame. More...
const std::string &	getTitle (void) const noexcept
	Return the widtget current title, or empty if none. More...
bool	cursorInTopFrame (const CharCursor &cc) const
	Return TRUE if CC lies in the top (title) line of the container frame. More...
const PVector &	children (void) noexcept
	Return the widgets contained into the container. More...
Widget *	addChild (const Ptr &ch)
	Return its children creation type. More...
void	setDeepSelected (PVector::size_type who)
	Set the WHO-th children as the one visible if the container is DEEP. More...
PVector::size_type	getDeepSelected (void) const
	Get the WHO-th children that is the one visible if the cont. is DEEP. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
bool	isContainer (void) const noexcept override
	Return whether the widget is a container of other widgets. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. More...
void	moveDrawingZones (IntDist incx, IntDist incy) noexcept override
	Move the drawing and aligned zones corners by those increments. More...
void	setWindow (Window &win) noexcept override
	Set the Window where the widget is being managed. More...
void	setWinColors (const WinColors &wincols) noexcept override
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
ChainEventResult	chainEvent (const EventData &data) override
	Deal with the event at this widget and its descendants (if container). 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...
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...
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...
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	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
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...

Member Enumeration Documentation

anonymous enum

anonymous enum : uint8_t

Elements that can have the widget.

< There is an additional, always present element: a list of files in the current path.

Enumerator
WITH_TREE	A tree for browsing directories.
WITH_PATH	To show current path.
WITH_EDIT	To show currently selected filename.

Definition at line 50 of file ZXWidgetFileBrowser.h.

Constructor & Destructor Documentation

FileBrowserWidget()

zxeco::gui::FileBrowserWidget::FileBrowserWidget	(	ID	id,
		const std::string &	name,
		uint8_t	elements = WITH_TREE|WITH_PATH|WITH_EDIT,
		const std::filesystem::path &	initpath = std::filesystem::path{},
		const std::string &	initedit = "",
		char	markingsinfiles = 'N',
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor.

Parameters

elements	indicates the elements to show in the widget.
initpath	is the initial path; if empty, the current dir is used. To use the root path, pass std::filesystem::current_path().root_path().
markingsinfiles	is the marking allowed in the list of files (either 'N' for no marking, 'S' for marking only one at a time, or 'M' for marking several at a time).

Member Function Documentation

changeDir()

bool zxeco::gui::FileBrowserWidget::changeDir

(

const std::filesystem::path &

path

)

Change the current path to the given one.

If it could change it, return TRUE; otherwise (non-existing path, for instance), return FALSE and do nothing.

reload()

void zxeco::gui::FileBrowserWidget::reload ( void  )

inline

Definition at line 78 of file ZXWidgetFileBrowser.h.

editedText()

const std::string & zxeco::gui::FileBrowserWidget::editedText

(

void

)

const

Return the currently text in the editing line.

If no editing line, throw.

browserPath()

const std::filesystem::path & zxeco::gui::FileBrowserWidget::browserPath ( void  ) const

inlinenoexcept

< Return a ref to the current path of the browser (empty after creation).

Definition at line 87 of file ZXWidgetFileBrowser.h.

eventProcessedByTree()

bool zxeco::gui::FileBrowserWidget::eventProcessedByTree ( const CallbackParms &  cbp ) const

inlinenoexcept

< Return TRUE if the callback is for an event already processed by tree.

< Return FALSE if the callback is for an event not processed by the tree but by the other components of the FileBrowserWidget. This method is to be called in the callback set for the FileBrowserWidget in order to distinguish whether it was served in the tree or not.

Definition at line 91 of file ZXWidgetFileBrowser.h.

eventProcessedByFiles()

bool zxeco::gui::FileBrowserWidget::eventProcessedByFiles ( const CallbackParms &  cbp ) const

inlinenoexcept

< Return TRUE if the callback is for an event already processed by files.

< Return FALSE if the callback is for an event not processed by the files but by the other components of the FileBrowserWidget. This method is to be called in the callback set for the FileBrowserWidget in order to distinguish whether it was served in the files list or not.

Definition at line 101 of file ZXWidgetFileBrowser.h.

className()

const char * zxeco::gui::FileBrowserWidget::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 111 of file ZXWidgetFileBrowser.h.

hasFocusZone()

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

overridevirtualnoexcept

< 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.

zxeco::gui::ListWidget

class zxeco::gui::ListWidget

A sequence of text lines with possibly scroll bars and selection of elements.

The list can be cursored (only one element at a time) and user's selected (either none, single or multiple selections are allowed). Optionally, elements in the list may have a third marking indicating whether they should be shown as "disabled". Furthermore: any element in the list that is set as invisible will be ignored (skipped) by the widget and therefore never shown.

The cursored line, if any, will be within the viewport shown in the screen, thus if it is move, the viewport will follow accordingly.

If this is the only widget in a single non-framed container in the window, the list automatically expands the cursor one character to each side to emulate the aspect of the original ZX menuses. This can be also used to display LabelTree's, in which case the list will show deployment icons.

Note

Keys to navigate the list:

-Cursors: 1-character movement in each direction.
-Enter: toggle deployment of an element of the list if it is a tree.
-Space: toggle the user's marking of an element of the list.
-Home/End: moves to the left/right ends of the current element in the list.
-PgUp/PgDown: moves one page towards the top/bottom ends of the list.

Definition at line 63 of file ZXWidgetList.h.

Inheritance diagram for zxeco::gui::ListWidget:

Collaboration diagram for zxeco::gui::ListWidget:

Public Member Functions
	ListWidget (ID id, const std::string &name, const LabelList &initllist, const CharArea &minsize, uint8_t flexdims=AreaFitting::FLEX_HOR|AreaFitting::FLEX_VER, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
LabelList &	list (void) noexcept
	Return the current list of elements. More...
void	append (const Label::Vector &v)
	Append all elements of V to the list but with just 1 refresh call. More...
size_t	howManyLinesCanBeShown (void) const
	Return how many lines can be shown currently in the viewport for list. More...
size_t	listSizeOfVisible (void) const
	Return the number of lines marked as visible in the list. More...
size_t	indexOfTopLine (void) const
	Return the index in the list of the current top line, if any. More...
LabelList::Iterator	lastLineInteracted (void) const noexcept
	< Return the last line involved in a mouse event or in an ENTER pressing. More...
LabelList::Iterator	cursoredLine (void) const
	Return an iterator to the current line with the cursor, or end(). More...
void	moveCursoredLine (bool upordown, size_t howmany)
	Move the cursored line up (true) or down (false) howmany times. More...
void	moveCursoredLineToExtreme (bool beginningorend)
	Move the cursored line to the beginning (true) or end (false) of list. More...
void	moveCursoredLine (size_t where)
	Move the cursored line to that position within the visible lines. More...
bool	eventProcessedByList (const CallbackParms &cbp) const noexcept
	< Return TRUE if the callback is for an event already processed by list. More...
char	eventProcessedWentBeyond (const CallbackParms &cbp) const noexcept
	Return an indicator of whether the processed event in CBP went beyond. More...
bool	eventLeftClickedOrEnter (const CallbackParms &cbp) const noexcept
	< Return TRUE if the callback is for a list-processed left click or enter More...
bool	eventHasChangedCursored (const CallbackParms &cbp) const noexcept
	< Return TRUE if the callback is for some event that may change cursored. More...
CharRect	zoneForLineContent (const LabelList::Iterator &itl) const
	Return the zone in the drawing for line ITL, or {{0,0},{0,0}} if none. More...
void	setUDGs (const uint8_t *udgs)
	Assign an UDG character set for the widget drawing (do not copy them). More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. 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 AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. More...
void	setTooltip (const std::string &ttt) override
	Must return a text with the name of the class. More...
Public Member Functions inherited from zxeco::gui::ContainerWidget
	ContainerWidget (ID id, const std::string &name, CCType cctype=CCType::USER, OrType ortype=OrType::VERTICAL, FMType foctype=FMType::NORMAL, bool withframe=false, const std::string &title="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP, const std::string &tooltiptext="")
	Constructor. More...
CCType	ccType (void) const noexcept
	Return its children creation type. More...
OrType	orType (void) const noexcept
	Return its orientation type. More...
FMType	focusMngType (void) const noexcept
	Return its focus management type. More...
bool	getFrame (void) const noexcept
	Return whether the widget has currently a frame. More...
const std::string &	getTitle (void) const noexcept
	Return the widtget current title, or empty if none. More...
bool	cursorInTopFrame (const CharCursor &cc) const
	Return TRUE if CC lies in the top (title) line of the container frame. More...
const PVector &	children (void) noexcept
	Return the widgets contained into the container. More...
Widget *	addChild (const Ptr &ch)
	Return its children creation type. More...
void	setDeepSelected (PVector::size_type who)
	Set the WHO-th children as the one visible if the container is DEEP. More...
PVector::size_type	getDeepSelected (void) const
	Get the WHO-th children that is the one visible if the cont. is DEEP. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
bool	isContainer (void) const noexcept override
	Return whether the widget is a container of other widgets. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. More...
void	moveDrawingZones (IntDist incx, IntDist incy) noexcept override
	Move the drawing and aligned zones corners by those increments. More...
void	setWindow (Window &win) noexcept override
	Set the Window where the widget is being managed. More...
void	setWinColors (const WinColors &wincols) noexcept override
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
ChainEventResult	chainEvent (const EventData &data) override
	Deal with the event at this widget and its descendants (if container). 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...
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...
const WinColors &	getWinColors (void) const noexcept
	Return the current window colors. More...
const uint8_t *	getUDGs (void)
	Return the current UDGs. *‍/. 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...
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	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::ContainerWidget
enum class	OrType { VERTICAL , HORIZONTAL , DEEP }
	Types of containers according to the spatial orientation of their contnt. More...
enum class	CCType { USER , OWN }
	Types of container according to the creation of their children. More...
enum class	FMType { NORMAL , PRESERVE }
	Types of management of focus among descendant widgets. More...
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

ListWidget()

zxeco::gui::ListWidget::ListWidget	(	ID	id,
		const std::string &	name,
		const LabelList &	initllist,
		const CharArea &	minsize,
		uint8_t	flexdims = AreaFitting::FLEX_HOR|AreaFitting::FLEX_VER,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor.

If the list is a tree, some UDGs are defined for drawing the branches that can be deployed or not; thus, in that case, the method to set UDGs will throw.

Parameters

initllist	must have 2 markings at least: #0 will be used for the cursor and therefore must be 'S' (single choice) and #1 for the selections, that can be of any kind ('S' (single choice), 'M' (Multiple choice) or 'N' (no choice)). If a third marking exists (#2), those elements unmarked (false) will be shown in disabled colors and cannot be selected in marking #1. Note that if you set this third marking as single ('S'), marking one element will unmark the previous one, if any; the usual option is to set it as multiple ('M'). Any item in the list that is "=" is a separator. The list will be cloned internally, thus it can be safely deleted. It can be a LabelList or any of its derivatives such as LabelTree. In the case of LabelTree, the widget manages correctly the deployment / undeployment of the tree elements.
minsize	is the minimum area to use for the nude listing (not counting possible scroll bars). It cannot be empty.
flexdims	indicates in which dimensions the list widget will have flexible size (i.e., maybe longer size that the one in minsize). NOTE: If the list is expected to change in number/length of elements and therefore in the visibility of vertical/horizontal scrolls, it should use flexibility in both directions in order to accomodate those changes.

Member Function Documentation

list()

LabelList & zxeco::gui::ListWidget::list ( void  )

inlinenoexcept

Return the current list of elements.

Any modification in that list will produce a redrawing of the widget. Do not change the observer in that list.

Definition at line 102 of file ZXWidgetList.h.

append()

void zxeco::gui::ListWidget::append

(

const Label::Vector &

v

)

Append all elements of V to the list but with just 1 refresh call.

This is useful when forming long lists, in order not to call the redraw observer of the list after each insertion, which slows down everything.

howManyLinesCanBeShown()

size_t zxeco::gui::ListWidget::howManyLinesCanBeShown

(

void

)

const

Return how many lines can be shown currently in the viewport for list.

This is O(1).

listSizeOfVisible()

size_t zxeco::gui::ListWidget::listSizeOfVisible

(

void

)

const

Return the number of lines marked as visible in the list.

Those lines are not the lines shown in the viewport, but the ones marked in the list as visible, either shown or not. This is O(N), being N the size of the list.

indexOfTopLine()

size_t zxeco::gui::ListWidget::indexOfTopLine

(

void

)

const

Return the index in the list of the current top line, if any.

If none visible, return >= size of the list.

lastLineInteracted()

LabelList::Iterator zxeco::gui::ListWidget::lastLineInteracted ( void  ) const

inlinenoexcept

< Return the last line involved in a mouse event or in an ENTER pressing.

< The iterator is updated at each event that involves the mouse left butt or mouse move or the pressing of the ENTER key. It can be list().end() if no line (e.g., clicked outside the list content but inside the list widget area).

Definition at line 126 of file ZXWidgetList.h.

cursoredLine()

LabelList::Iterator zxeco::gui::ListWidget::cursoredLine

(

void

)

const

Return an iterator to the current line with the cursor, or end().

The current cursored line is always shown in the portion of the list that is displayed, even when it is changed from the outside through the modification of the list marking. Therefore, the scrolls cannot be moved beyond the portion of the list that contains the cursor.

moveCursoredLine() [1/2]

void zxeco::gui::ListWidget::moveCursoredLine	(	bool	upordown,
		size_t	howmany
	)

Move the cursored line up (true) or down (false) howmany times.

Do nothing if howmany == 0 or the list is empty. If there are not enough lines to move, move whatever it can. If there is no cursored line previously, spent the first movement in cursoring the first line in the list. After this, the cursored line is guaranteed to be shown in the portion of the list that is displayed.

moveCursoredLineToExtreme()

void zxeco::gui::ListWidget::moveCursoredLineToExtreme

(

bool

beginningorend

)

Move the cursored line to the beginning (true) or end (false) of list.

If no cursored line, set the cursored line. After this, the cursored line is guaranteed to be shown in the portion of the list that is displayed.

moveCursoredLine() [2/2]

void zxeco::gui::ListWidget::moveCursoredLine

(

size_t

where

)

Move the cursored line to that position within the visible lines.

After this, the cursored line is guaranteed to be shown in the portion of the list that is displayed.

eventProcessedByList()

bool zxeco::gui::ListWidget::eventProcessedByList ( const CallbackParms &  cbp ) const

inlinenoexcept

< Return TRUE if the callback is for an event already processed by list.

< Return FALSE if the callback is for an event in the 'before' chain or not processed by the list but by the scroll bars. This method is to be called in the callback routine that is set for the ListWidget in order to distinguish where it was served.

Definition at line 161 of file ZXWidgetList.h.

eventProcessedWentBeyond()

char zxeco::gui::ListWidget::eventProcessedWentBeyond ( const CallbackParms &  cbp ) const

noexcept

Return an indicator of whether the processed event in CBP went beyond.

The event went beyond if the user tried to go beyond the existing list, either downwards (return 'd') or upwards (return 'u'), independently on the list doing a wrap around or not. Return ' ' if no going-beyond happened. Notice that the user cannot go beyond by using the slide of the scroll bars, only by using the keyboard or the arrows of the scrolls. Return 'x' if the callback parameters indicate that the list has not been processed yet (the event is still before processing). If the list wraps around, if the event is already processed, the list will be updated with the new position of the user's cursor at the time this method returns 'u' or 'd'.

eventLeftClickedOrEnter()

bool zxeco::gui::ListWidget::eventLeftClickedOrEnter ( const CallbackParms &  cbp ) const

inlinenoexcept

< Return TRUE if the callback is for a list-processed left click or enter

Definition at line 184 of file ZXWidgetList.h.

eventHasChangedCursored()

bool zxeco::gui::ListWidget::eventHasChangedCursored ( const CallbackParms &  cbp ) const

inlinenoexcept

< Return TRUE if the callback is for some event that may change cursored.

Definition at line 189 of file ZXWidgetList.h.

zoneForLineContent()

CharRect zxeco::gui::ListWidget::zoneForLineContent

(

const LabelList::Iterator &

itl

)

const

Return the zone in the drawing for line ITL, or {{0,0},{0,0}} if none.

Do not use the expandedcursor state; the area returned is just the one for the content of the line. This is O(n), being N the length of the list. ITL must have, as conditions, to be visible, but no more than that.

setUDGs()

void zxeco::gui::ListWidget::setUDGs ( const uint8_t *  udgs )

inlinevirtual

Assign an UDG character set for the widget drawing (do not copy them).

The drawing method should use udgs_ member to set its UDGs. By default, the member is nullptr.

Reimplemented from zxeco::gui::Widget.

Definition at line 208 of file ZXWidgetList.h.

className()

const char * zxeco::gui::ListWidget::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 213 of file ZXWidgetList.h.

hasFocusZone()

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

overridevirtualnoexcept

< 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.

calcFittingNeeds()

const AreaFitting & zxeco::gui::ListWidget::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.

setDrawingZone()

Widget * zxeco::gui::ListWidget::setDrawingZone ( const CharRect &  zone )

overridevirtual

Set the final drawing zone for the widget and the aligned one.

Return a pointer to the first (higher) widget in the tree equal or below this that gets an aligned drawing zone different from its current one (or its first zone if not drawn before), or nullptr if all widgets below this (including this) get the same zones as before. The available drawing zone of the widget is the space where it can align its content; the aligned zone is the final rectangle where it must be drawn, already aligned within the drawing zone.

ZONE.corner uses absolute coords within the global screen. ZONE can have the same area as the needed one or a different, larger one (that leaves room for alignment), but not smaller.

This method will be called after calculating the widget fitting needs & before drawing. It 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).

Container widgets override this method to deploy it to their children. Also, widgets derived from containers can override it to adjust the visibility of some children if that is to be calculated dynamically, since ZONE may be larger than the one proposed by calcFittingNeeds(), which may affect that visibility.

If the calculated aligned drawing zone is different from the previous one or if the widget was not previously drawn, sets the drawn_ flag to false. Otherwise, leave it unchanged.

Reimplemented from zxeco::gui::Widget.

setTooltip()

void zxeco::gui::ListWidget::setTooltip ( const std::string &  ttt )

overridevirtual

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.

Parameters

ttt	Change the tooltip text to TTT, that can be empty but with no ctrl chrs Virtual for the case that a container wish to deploy the tooltip to one of its descendants.

Reimplemented from zxeco::gui::Widget.

zxeco::gui::MenuBarWidget

class zxeco::gui::MenuBarWidget

A widget to show a horizontal menu bar with a menu in each element.

The list of elements and their menuses are unmutable.

Definition at line 43 of file ZXWidgetMenuBar.h.

Inheritance diagram for zxeco::gui::MenuBarWidget:

Collaboration diagram for zxeco::gui::MenuBarWidget:

Public Member Functions
	MenuBarWidget (ID id, const std::string &name, const LabelTree &menuses, bool extend=true, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. More...
size_t	lastSelected (void) const noexcept
	Return the index in the original tree of the last element selected. More...
void	clearLastSelected (void)
	Clear the last selected element. 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::ContainerWidget
	ContainerWidget (ID id, const std::string &name, CCType cctype=CCType::USER, OrType ortype=OrType::VERTICAL, FMType foctype=FMType::NORMAL, bool withframe=false, const std::string &title="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP, const std::string &tooltiptext="")
	Constructor. More...
CCType	ccType (void) const noexcept
	Return its children creation type. More...
OrType	orType (void) const noexcept
	Return its orientation type. More...
FMType	focusMngType (void) const noexcept
	Return its focus management type. More...
bool	getFrame (void) const noexcept
	Return whether the widget has currently a frame. More...
const std::string &	getTitle (void) const noexcept
	Return the widtget current title, or empty if none. More...
bool	cursorInTopFrame (const CharCursor &cc) const
	Return TRUE if CC lies in the top (title) line of the container frame. More...
const PVector &	children (void) noexcept
	Return the widgets contained into the container. More...
Widget *	addChild (const Ptr &ch)
	Return its children creation type. More...
void	setDeepSelected (PVector::size_type who)
	Set the WHO-th children as the one visible if the container is DEEP. More...
PVector::size_type	getDeepSelected (void) const
	Get the WHO-th children that is the one visible if the cont. is DEEP. More...
const char *	className (void) const noexcept
	Must return a text with the name of the class. More...
bool	isContainer (void) const noexcept override
	Return whether the widget is a container of other widgets. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
void	drawRaw (void)
	Must draw itself in the decided aligned zone withing the drawing zone. More...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. More...
void	moveDrawingZones (IntDist incx, IntDist incy) noexcept override
	Move the drawing and aligned zones corners by those increments. More...
void	setWindow (Window &win) noexcept override
	Set the Window where the widget is being managed. More...
void	setWinColors (const WinColors &wincols) noexcept override
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
ChainEventResult	chainEvent (const EventData &data) override
	Deal with the event at this widget and its descendants (if container). 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...
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...
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...
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	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::ContainerWidget
enum class	OrType { VERTICAL , HORIZONTAL , DEEP }
	Types of containers according to the spatial orientation of their contnt. More...
enum class	CCType { USER , OWN }
	Types of container according to the creation of their children. More...
enum class	FMType { NORMAL , PRESERVE }
	Types of management of focus among descendant widgets. More...
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

MenuBarWidget()

zxeco::gui::MenuBarWidget::MenuBarWidget	(	ID	id,
		const std::string &	name,
		const LabelTree &	menuses,
		bool	extend = true,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor.

Parameters

menuses	contains the tree defining all menuses. Depth 0 elements will show as the elements in the menu bar, while the rest will deploy as the user clicks. Its data is copied internally, thus it can be safely deleted after constructing the menu bar.
extend	indicates whether the bar will extend to the entire dimension of the window (true) or just occupy the space needed for its depth-0 elements.

Member Function Documentation

lastSelected()

size_t zxeco::gui::MenuBarWidget::lastSelected ( void  ) const

noexcept

Return the index in the original tree of the last element selected.

If no element was selected the last time some menu was deployed, return the size of the tree. The last element is updated before any 'after' call to the user callback, thus, it is available in that callback routine.

clearLastSelected()

void zxeco::gui::MenuBarWidget::clearLastSelected

(

void

)

Clear the last selected element.

This should be called after processing the last selected element in order to capture the next last selected element.

className()

const char * zxeco::gui::MenuBarWidget::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 74 of file ZXWidgetMenuBar.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::MenuBarWidget::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::WidgetsForm

class zxeco::gui::WidgetsForm

template<class Underlying>
class zxeco::gui::WidgetsForm< Underlying >

Class from which any form must derive.

This models a form (a number of widgets grouped into a container) that shows data to the user; those data can be attached to an underlying system, where they are updated after changes and read from to refresh the form.

Definition at line 49 of file ZXWidgetsForm.h.

Collaboration diagram for zxeco::gui::WidgetsForm< Underlying >:

Public Types
using	Callback = std::function< bool(void) >
	A callback for some interacting element of the form. More...
Public Member Functions
	WidgetsForm (const std::string &formname, Underlying &under)
	Base constructor. Derived constructors must not populate the form. More...
	WidgetsForm (const WidgetsForm &)=delete
	WidgetsForm (WidgetsForm &&)=delete
WidgetsForm &	operator= (const WidgetsForm &)=delete
WidgetsForm &	operator= (WidgetsForm &&)=delete
virtual void	populateGUI (zxeco::gui::Window::DepthFirstInserter &wins)=0
	Must create form widgets in WINS, fill CONT_ and set POPULATED_ to true. More...
virtual void	fill (void)=0
	Must fill the fields with their current values from the underlying sys.
virtual void	dump (void)=0
	Must dump the current form field values into the underlying system.
zxeco::gui::ContainerWidget &	mainContainer (void)
	Return a reference to the main container of the form. More...
Protected Member Functions
void	checkIsPopulated (const std::string &place="") const
	Throw if unpopulated. More...
void	checkIsUnpopulated (const std::string &place="") const
	Throw if populated. More...
Protected Attributes
const std::string	formname_
bool	populated_
	Whether the form has already been populated. More...
Underlying &	underlying_
zxeco::gui::ContainerWidget *	cont_
	Main container of the form. More...

Member Typedef Documentation

Callback

template<class Underlying >

using zxeco::gui::WidgetsForm< Underlying >::Callback = std::function< bool(void) >

A callback for some interacting element of the form.

It will be called if that element is interacted with; its return will be used inside a Widget callback routine.

Definition at line 56 of file ZXWidgetsForm.h.

Constructor & Destructor Documentation

WidgetsForm()

template<class Underlying >

zxeco::gui::WidgetsForm< Underlying >::WidgetsForm ( const std::string &  formname, Underlying &  under  )

inline

Base constructor. Derived constructors must not populate the form.

UNDER must outlive this class.

Definition at line 61 of file ZXWidgetsForm.h.

Member Function Documentation

populateGUI()

template<class Underlying >

virtual void zxeco::gui::WidgetsForm< Underlying >::populateGUI ( zxeco::gui::Window::DepthFirstInserter &  wins )

pure virtual

Must create form widgets in WINS, fill CONT_ and set POPULATED_ to true.

Must do it only once. CONT_ must be a reference to the main container of the form. At the start, this method should check that the form is unpopulated. Then, it must create the container that will contain its widgets, thus it can decide their spatial orientation. This is intended to be called from the code that is populating the window with the WINS used there, in such a way that the widgets of this form add to the rest of widgets in the same window.

mainContainer()

template<class Underlying >

zxeco::gui::ContainerWidget & zxeco::gui::WidgetsForm< Underlying >::mainContainer

(

void

)

Return a reference to the main container of the form.

Throw if unpopulated.

Definition at line 213 of file ZXWidgetsForm.h.

checkIsUnpopulated()

template<class Underlying >

void zxeco::gui::WidgetsForm< Underlying >::checkIsUnpopulated ( const std::string &  place = "" ) const

protected

Throw if populated.

Definition at line 205 of file ZXWidgetsForm.h.

Member Data Documentation

formname_

template<class Underlying >

const std::string zxeco::gui::WidgetsForm< Underlying >::formname_

protected

Definition at line 99 of file ZXWidgetsForm.h.

populated_

template<class Underlying >

bool zxeco::gui::WidgetsForm< Underlying >::populated_

protected

Whether the form has already been populated.

Definition at line 100 of file ZXWidgetsForm.h.

underlying_

template<class Underlying >

Underlying& zxeco::gui::WidgetsForm< Underlying >::underlying_

protected

Definition at line 101 of file ZXWidgetsForm.h.

cont_

template<class Underlying >

zxeco::gui::ContainerWidget* zxeco::gui::WidgetsForm< Underlying >::cont_

protected

Main container of the form.

Derived classes must set a pointer here with no ownership; ownership must be in the window inserter.

Definition at line 102 of file ZXWidgetsForm.h.

zxeco::gui::WidgetsFormBroker

class zxeco::gui::WidgetsFormBroker

The subscription/production intercommunicator of a number of forms.

It implements a subscribe/produce pattern where there are a number of (unparameterized) topics. It is useful for the forms and other components to exchange information as callbacks without knowing each other.

Definition at line 125 of file ZXWidgetsForm.h.

Public Types
using	Topic = int
	A topic. More...
using	Handler = std::pair< Topic, size_t >
	A handler for a subscription. More...
using	Callback = std::function< bool(Topic, void *, Widget *, const Widget::EventData *) >
	A callback to be called when a topic produces a new value. More...
Public Member Functions
Handler	subscribe (Topic topic, const Callback &cbck)
	Subscribe the caller to the given topic. More...
bool	produce (Topic topic, void *parms=nullptr, Widget *w=nullptr, const Widget::EventData *ed=nullptr)
	Produce the given topic. More...
std::string	to_string (void) const
	Return a string with info about the current state of the broker.

Member Typedef Documentation

Topic

using zxeco::gui::WidgetsFormBroker::Topic = int

A topic.

Definition at line 130 of file ZXWidgetsForm.h.

Handler

using zxeco::gui::WidgetsFormBroker::Handler = std::pair<Topic,size_t>

A handler for a subscription.

Definition at line 133 of file ZXWidgetsForm.h.

Callback

using zxeco::gui::WidgetsFormBroker::Callback = std::function< bool(Topic, void *, Widget *, const Widget::EventData *) >

A callback to be called when a topic produces a new value.

It may receive some parameters (the void *), and/or a pointer to the widget that produced the topic + a pointer to the event that produced the topic (depending on the producer). It will always receive the topic itself. It must return FALSE to indicate that the event processing routine within which the callback is called must make the window manager to return from its management; in that case, the rest of subscribers will not receive the signal of the topic.

Definition at line 143 of file ZXWidgetsForm.h.

Member Function Documentation

subscribe()

Handler zxeco::gui::WidgetsFormBroker::subscribe	(	Topic	topic,
		const Callback &	cbck
	)

Subscribe the caller to the given topic.

If already subscribed, CBCK will the put at the end of the list of previous callbacks for the topic. Return a handler for the subscription.

produce()

bool zxeco::gui::WidgetsFormBroker::produce	(	Topic	topic,
		void *	parms = nullptr,
		Widget *	w = nullptr,
		const Widget::EventData *	ed = nullptr
	)

Produce the given topic.

Depending on the producer, you can use PARMS to hold parameters, and W and ED to indicate info about the widget producing the event. All subscribers will be called sequentially. This method returns FALSE if any of them returned FALSE (in that case, the rest of subscribers will not be called).

zxeco::gui::SlideWidget

class zxeco::gui::SlideWidget

A slide, either horizontal or vertical, e.g., to serve as scroll bar.

Definition at line 38 of file ZXWidgetSlide.h.

Inheritance diagram for zxeco::gui::SlideWidget:

Collaboration diagram for zxeco::gui::SlideWidget:

Static Public Member Functions
static CharDist	kLength (bool witharrows) noexcept
	< Length in chars of the slide (not considering the numeric value if any) More...
static CharArea	calcScrollVisibilityForArea (const CharArea &content, bool &vert, bool &horiz, const CharArea &area, bool &changed, SlideWidget *phorscr=nullptr, SlideWidget *pverscr=nullptr, bool scrollfromcontent=true)
	Check whether sliders (scrolls) are visib. to display CONTENT into AREA. More...
static void	calcScrollBoundsForArea (const CharArea &content, const CharArea &nudearea, size_t &vertbound, size_t &horizbound, SlideWidget *phorizscroll=nullptr, SlideWidget *pvertscroll=nullptr)
	Calc. bounds to set in the scrolls after calcScrollVisibilityForArea(). More...
static bool	updateScrollsForAreaSilently (const CharArea &content, const CharArea &area, SlideWidget &horizscroll, SlideWidget &vertscroll)
	Update visibility + bounds of scrolls and return TRUE if visib. changed. More...
static int	calcMaxBoundScroll (size_t needed, CharDist availleninnude) noexcept
	< Calculate the maximum value for a slide used as a scroll bar. More...
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
static const CharDist	kThickness
	Thickness in chars of the nude slide (only considering the sliding bar) 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...
Public Member Functions
	SlideWidget (ID id, const std::string &name, char orientation, bool witharrows, CharDist maxlen, const std::string &valformat, char kindofvalue, double minval, double maxval, double incval, const std::string &tooltiptext="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor. The initial numerical value will be minval. More...
double	value (void) const
	Return the current numerical value represented by the slide.
void	setValue (double value)
	Change the current numerical value represented by the slide. More...
double	minBound (void) const noexcept
	Return the minimum bound of the widget.
double	maxBound (void) const noexcept
	Return the maximum bound of the widget.
void	bounds (double &minval, double &maxval) const noexcept
	Fill MINVAL and MAXVAL with the current value bounds of the widget.
bool	changeBounds (double minval, double maxval, bool noredraw=false)
	Set new value bounds for the widget, redrawing only if they change. More...
const char *	className (void) const noexcept
	Return the current numerical value represented by the slide. More...
Public Member Functions inherited from zxeco::gui::ContainerWidget
	ContainerWidget (ID id, const std::string &name, CCType cctype=CCType::USER, OrType ortype=OrType::VERTICAL, FMType foctype=FMType::NORMAL, bool withframe=false, const std::string &title="", HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP, const std::string &tooltiptext="")
	Constructor. More...
CCType	ccType (void) const noexcept
	Return its children creation type. More...
OrType	orType (void) const noexcept
	Return its orientation type. More...
FMType	focusMngType (void) const noexcept
	Return its focus management type. More...
bool	getFrame (void) const noexcept
	Return whether the widget has currently a frame. More...
const std::string &	getTitle (void) const noexcept
	Return the widtget current title, or empty if none. More...
bool	cursorInTopFrame (const CharCursor &cc) const
	Return TRUE if CC lies in the top (title) line of the container frame. More...
const PVector &	children (void) noexcept
	Return the widgets contained into the container. More...
Widget *	addChild (const Ptr &ch)
	Return its children creation type. More...
void	setDeepSelected (PVector::size_type who)
	Set the WHO-th children as the one visible if the container is DEEP. More...
PVector::size_type	getDeepSelected (void) const
	Get the WHO-th children that is the one visible if the cont. is DEEP. More...
bool	isContainer (void) const noexcept override
	Return whether the widget is a container of other widgets. More...
const AreaFitting &	calcFittingNeeds (const CharArea &area)
	Must calculate the widget fitting within the dimensions of AREA. More...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. More...
void	moveDrawingZones (IntDist incx, IntDist incy) noexcept override
	Move the drawing and aligned zones corners by those increments. More...
void	setWindow (Window &win) noexcept override
	Set the Window where the widget is being managed. More...
void	setWinColors (const WinColors &wincols) noexcept override
	< Assign the colors used to draw the widget. WINCOLS must outlive this. More...
ChainEventResult	chainEvent (const EventData &data) override
	Deal with the event at this widget and its descendants (if container). 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...
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...
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...
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	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::ContainerWidget
enum class	OrType { VERTICAL , HORIZONTAL , DEEP }
	Types of containers according to the spatial orientation of their contnt. More...
enum class	CCType { USER , OWN }
	Types of container according to the creation of their children. More...
enum class	FMType { NORMAL , PRESERVE }
	Types of management of focus among descendant widgets. More...
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 &)>
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

SlideWidget()

zxeco::gui::SlideWidget::SlideWidget	(	ID	id,
		const std::string &	name,
		char	orientation,
		bool	witharrows,
		CharDist	maxlen,
		const std::string &	valformat,
		char	kindofvalue,
		double	minval,
		double	maxval,
		double	incval,
		const std::string &	tooltiptext = "",
		HorAlign	hal = HorAlign::LEFT,
		VertAlign	val = VertAlign::TOP
	)

Constructor. The initial numerical value will be minval.

Parameters

orientation	must be either 'V' for vertical or 'H' for horizontal slide.
witharrows	must be TRUE for adding arrows in the extremes.
maxlen	is the maximum length occuppied by the widget, or 0 for not limiting it.
valformat	must be empty to not show the value numerically or a printf like format text to show it.
kindofvalue	must be either 'I' (integer) or 'R' (real).
minval	must be the minimum numerical value the slide may represent.
maxval	must be the maximum numerical value the slide may represent. The maximum value may be equal to the minimum value (then, the slide cannot be dragged or changed of value; it will be always the minimum).
incval	must be the increment in value when an arrow is pressed.

Member Function Documentation

kLength()

static CharDist zxeco::gui::SlideWidget::kLength ( bool  witharrows )

inlinestaticnoexcept

< Length in chars of the slide (not considering the numeric value if any)

Definition at line 45 of file ZXWidgetSlide.h.

calcScrollVisibilityForArea()

static CharArea zxeco::gui::SlideWidget::calcScrollVisibilityForArea ( const CharArea &  content, bool &  vert, bool &  horiz, const CharArea &  area, bool &  changed, SlideWidget *  phorscr = nullptr, SlideWidget *  pverscr = nullptr, bool  scrollfromcontent = true  )

static

Check whether sliders (scrolls) are visib. to display CONTENT into AREA.

Fill VERT and HORIZ with the slides visibilities needed for fitting the content and their presence into AREA. If SCROLLFROMCONTENT, consider that the horizontal slide will consume kThickness from the intended height of the content and the vertical slide will consume kThickness from the intended width of the content (e.g., adding a vertical slide will produce smaller horizontal space and therefore may need the addition of the horizontal slide too). Otherwise, the appearance of scrolls will not consume space from the given content. If PHORIZSCROLL is not null and its visibility is different from VERT, set its visibility without redrawing it and fill CHANGED with TRUE; the same for PVERTSCROLL and HORIZ. Otherwise, CHANGED is set to false. Return the area occupied by the nude content if the scrolling slides are set as it has calculated (it can be shrinked to make room for the scrolls).

calcScrollBoundsForArea()

static void zxeco::gui::SlideWidget::calcScrollBoundsForArea ( const CharArea &  content, const CharArea &  nudearea, size_t &  vertbound, size_t &  horizbound, SlideWidget *  phorizscroll = nullptr, SlideWidget *  pvertscroll = nullptr  )

static

Calc. bounds to set in the scrolls after calcScrollVisibilityForArea().

Fill VERTBOUND and HORIZBOUND with the maximum bounds (0 if invisible). If PHORIZSCROLL is not nullptr, set its new bound (no redraw); the same for PVERTSCROLL. Max. scroll values are set for showing the rest of the content from them, without any blank content (see calcMaxBoundScroll).

updateScrollsForAreaSilently()

static bool zxeco::gui::SlideWidget::updateScrollsForAreaSilently ( const CharArea &  content, const CharArea &  area, SlideWidget &  horizscroll, SlideWidget &  vertscroll  )

static

Update visibility + bounds of scrolls and return TRUE if visib. changed.

No redrawing of the scrolls. This method calls both calcScrollVisibilityForArea() and calcScrollBoundsForArea().

calcMaxBoundScroll()

static int zxeco::gui::SlideWidget::calcMaxBoundScroll ( size_t  needed, CharDist  availleninnude  )

inlinestaticnoexcept

< Calculate the maximum value for a slide used as a scroll bar.

< The max. value will be placed at the point when the AVAILLENINNUDE show the rest of the NEEDED content without leaving any blank content afterwards.

Definition at line 101 of file ZXWidgetSlide.h.

setValue()

void zxeco::gui::SlideWidget::setValue

(

double

value

)

Change the current numerical value represented by the slide.

Throw if out of range. Redraw the cursor of the slide and the label value, if needed.

changeBounds()

bool zxeco::gui::SlideWidget::changeBounds	(	double	minval,
		double	maxval,
		bool	noredraw = false
	)

Set new value bounds for the widget, redrawing only if they change.

If NOREDRAW == TRUE, does not redraw even if they change. If the widget is drawn, keep the current cursor position by possibly changing the value_ (and drawRaw() again); if it is not drawn and the value is outside the new bounds, bound the value by them. Return TRUE if the bounds have changed.

className()

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

inlinevirtualnoexcept

Return the current numerical value represented by the slide.

Reimplemented from zxeco::gui::ContainerWidget.

Definition at line 170 of file ZXWidgetSlide.h.

Member Data Documentation

kThickness

const CharDist zxeco::gui::SlideWidget::kThickness

static

Thickness in chars of the nude slide (only considering the sliding bar)

Definition at line 42 of file ZXWidgetSlide.h.

zxeco::gui::TextEditorWidget

class zxeco::gui::TextEditorWidget

A widget that shows an area for editing multi-line text with word-wrapping.

It can also serve as a rectangular label, if not editable.

Definition at line 40 of file ZXWidgetTextEditor.h.

Inheritance diagram for zxeco::gui::TextEditorWidget:

Collaboration diagram for zxeco::gui::TextEditorWidget:

Public Member Functions
	TextEditorWidget (ID id, const std::string &name, const CharArea &area, const std::string &tooltiptext="", bool editable=true, HorAlign hal=HorAlign::LEFT, VertAlign val=VertAlign::TOP)
	Constructor (initially empty text). More...
const std::string &	text (void) const
	Return a ref to consult the current edited text. More...
void	setText (const std::string &txt)
	Change the current text by TXT, ignoring all ctrl chars. More...
void	moveTop (void)
	Move the content to start showing the first line at top.
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...
Widget *	setDrawingZone (const CharRect &zone) override
	Set the final drawing zone for the widget and the aligned one. 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...
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

TextEditorWidget()

zxeco::gui::TextEditorWidget::TextEditorWidget ( ID  id, const std::string &  name, const CharArea &  area, const std::string &  tooltiptext = "", bool  editable = true, HorAlign  hal = HorAlign::LEFT, VertAlign  val = VertAlign::TOP  )

inline

Constructor (initially empty text).

Parameters

area	is the visible area for editing. If it is empty, the widget adjust to the maximum area possible.
editable	indicate if the text can be edited or just shown.

Definition at line 44 of file ZXWidgetTextEditor.h.

Member Function Documentation

text()

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

inline

Return a ref to consult the current edited text.

Definition at line 61 of file ZXWidgetTextEditor.h.

setText()

void zxeco::gui::TextEditorWidget::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.

moveDrawingZones()

void zxeco::gui::TextEditorWidget::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 71 of file ZXWidgetTextEditor.h.

hasFocusZone()

std::pair< bool, const CharRect * > zxeco::gui::TextEditorWidget::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 73 of file ZXWidgetTextEditor.h.

className()

const char * zxeco::gui::TextEditorWidget::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 76 of file ZXWidgetTextEditor.h.

calcFittingNeeds()

const AreaFitting & zxeco::gui::TextEditorWidget::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.

setDrawingZone()

Widget * zxeco::gui::TextEditorWidget::setDrawingZone ( const CharRect &  zone )

overridevirtual

Set the final drawing zone for the widget and the aligned one.

Return a pointer to the first (higher) widget in the tree equal or below this that gets an aligned drawing zone different from its current one (or its first zone if not drawn before), or nullptr if all widgets below this (including this) get the same zones as before. The available drawing zone of the widget is the space where it can align its content; the aligned zone is the final rectangle where it must be drawn, already aligned within the drawing zone.

ZONE.corner uses absolute coords within the global screen. ZONE can have the same area as the needed one or a different, larger one (that leaves room for alignment), but not smaller.

This method will be called after calculating the widget fitting needs & before drawing. It 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).

Container widgets override this method to deploy it to their children. Also, widgets derived from containers can override it to adjust the visibility of some children if that is to be calculated dynamically, since ZONE may be larger than the one proposed by calcFittingNeeds(), which may affect that visibility.

If the calculated aligned drawing zone is different from the previous one or if the widget was not previously drawn, sets the drawn_ flag to false. Otherwise, leave it unchanged.

Reimplemented from zxeco::gui::Widget.

Function Documentation

checkIsPopulated()

template<class Underlying >

void zxeco::gui::WidgetsForm< Underlying >::checkIsPopulated ( const std::string &  place = "" ) const

protected

#include <ZXWidgetsForm.h>

Throw if unpopulated.

Definition at line 197 of file ZXWidgetsForm.h.