Windows for the GUI

Description

This module provides the support for creating windows in the ZXEcosystem

Copyright

See LICENSE.txt and AUTHORS.txt file.

http://jafma.net

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

Collaboration diagram for Windows 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::Window
	A window on the screen. More...
class	zxeco::gui::Window::DepthFirstInserter
	To insert widgets in a window in a depth-first fashion. More...

Typedefs
using	zxeco::gui::Window::Ptr = std::unique_ptr< Window >
	Safe pointer to a window. More...

Enumerations
enum class	zxeco::gui::Window::MngResult { zxeco::gui::Window::MngResult::DESKCLOSE_EVENT , zxeco::gui::Window::MngResult::FINISHING_CALLBACK , zxeco::gui::Window::MngResult::OUT_CLICK }
	Possible results of calling the manage() method. More...

Variables
static constexpr CharDist	zxeco::gui::Window::kLengthBars = 7
	Number of chars printed in the title ZX when there are bars. More...

---

Class Documentation

zxeco::gui::Window

class zxeco::gui::Window

A window on the screen.

A window is a rectangular, char-aligned container for widgets, able to save and restore the background where it is placed, if needed.

Definition at line 49 of file ZXWindows.h.

Public Types
enum class	MngResult { MngResult::DESKCLOSE_EVENT , MngResult::FINISHING_CALLBACK , MngResult::OUT_CLICK }
	Possible results of calling the manage() method. More...
using	Ptr = std::unique_ptr< Window >
	Safe pointer to a window. More...
Static Public Attributes
static constexpr CharDist	kLengthBars = 7
	Number of chars printed in the title ZX when there are bars. More...
Public Member Functions
	Window (ZXEco &zxe, const CharRect &placem, const std::string &title, bool withborder=true, bool withzxbands=true, const WinColors &wincols=WinColors::kLight, bool preserveback=true)
	A window with the given parameters. More...
	Window (const Window &)=delete
	A window with the given parameters. More...
	Window (Window &&)=delete
	A window with the given parameters. More...
Window &	operator= (const Window &)=delete
	A window with the given parameters. More...
Window &	operator= (Window &&)=delete
	A window with the given parameters. More...
virtual	~Window (void)
	Destructor. More...
ZXEco &	zxEco (void) noexcept
	Return the ecosystem where the window is working. More...
const DoubleRect &	placement (void) const noexcept
	Return a reference to the absolute placement of the window. More...
const CharRect &	bodyRelRect (void) const noexcept
	Return a reference to the body rectangle of the window w.r.t. its orig. More...
const WinColors &	winColors (void) const noexcept
	Return the ecosystem where the window is working. More...
bool	hasBorder (void) const noexcept
	Return TRUE if the window has a border. More...
Widget *	rootWidget (void)
	Return the root widget or nullptr if none. More...
MngResult	manage (unsigned permill=10)
	Show the window and interact with the user in the given ecosystem. More...
void	show (void)
	Show the window space preserving previous background if desired. More...
void	hide (bool preservcontent=true)
	Hide the window, preserving the window contents if desired. More...
void	clearBody (void)
	Clear the body area. Do nothing if the current state is not visible. More...
std::string	to_string (void) const
	Return a text explaining the window.

Constructor & Destructor Documentation

Window() [1/3]

zxeco::gui::Window::Window	(	ZXEco &	zxe,
		const CharRect &	placem,
		const std::string &	title,
		bool	withborder = true,
		bool	withzxbands = true,
		const WinColors &	wincols = WinColors::kLight,
		bool	preserveback = true
	)

A window with the given parameters.

If it has border, the body of the window will respect 1-char border to the left, right and bottom of the entire window.

Parameters

zxe	is the ZXEcosystem used by the window.
placem	is the placement of the window on a given screen. The width and height must be at least 2 and 1, respectively, and the height must be at least 2 if there is a title and/ or border.
title	is the title; if empty, the window will have no title bar. All ctrl characters will be removed.
withborder	will draw a border around the screen if true.
withzxbands	will put ZX color bands at the title bar (if any) when it is TRUE. An exception will be raised if there is not enough width in the window to print these bands plus the title.
wincols	are the colors used for drawing the background of the window and diverse decorators (e.g., frames). Flash will be ignored.
preserveback	preserves the background before showing the window if TRUE, or does not preserve anything if FALSE.

Window() [2/3]

zxeco::gui::Window::Window ( const Window &  )

delete

A window with the given parameters.

If it has border, the body of the window will respect 1-char border to the left, right and bottom of the entire window.

Parameters

zxe	is the ZXEcosystem used by the window.
placem	is the placement of the window on a given screen. The width and height must be at least 2 and 1, respectively, and the height must be at least 2 if there is a title and/ or border.
title	is the title; if empty, the window will have no title bar. All ctrl characters will be removed.
withborder	will draw a border around the screen if true.
withzxbands	will put ZX color bands at the title bar (if any) when it is TRUE. An exception will be raised if there is not enough width in the window to print these bands plus the title.
wincols	are the colors used for drawing the background of the window and diverse decorators (e.g., frames). Flash will be ignored.
preserveback	preserves the background before showing the window if TRUE, or does not preserve anything if FALSE.

Window() [3/3]

zxeco::gui::Window::Window ( Window &&  )

delete

A window with the given parameters.

If it has border, the body of the window will respect 1-char border to the left, right and bottom of the entire window.

Parameters

zxe	is the ZXEcosystem used by the window.
placem	is the placement of the window on a given screen. The width and height must be at least 2 and 1, respectively, and the height must be at least 2 if there is a title and/ or border.
title	is the title; if empty, the window will have no title bar. All ctrl characters will be removed.
withborder	will draw a border around the screen if true.
withzxbands	will put ZX color bands at the title bar (if any) when it is TRUE. An exception will be raised if there is not enough width in the window to print these bands plus the title.
wincols	are the colors used for drawing the background of the window and diverse decorators (e.g., frames). Flash will be ignored.
preserveback	preserves the background before showing the window if TRUE, or does not preserve anything if FALSE.

~Window()

virtual zxeco::gui::Window::~Window ( void  )

virtual

Destructor.

Hide the window first, restoring background if any. Also set all its widgets to undrawn in case they are reused in another window because their smartpointers are stored elsewhere (e.g., in dialogs).

Member Function Documentation

operator=() [1/2]

Window & zxeco::gui::Window::operator= ( const Window &  )

delete

A window with the given parameters.

If it has border, the body of the window will respect 1-char border to the left, right and bottom of the entire window.

Parameters

zxe	is the ZXEcosystem used by the window.
placem	is the placement of the window on a given screen. The width and height must be at least 2 and 1, respectively, and the height must be at least 2 if there is a title and/ or border.
title	is the title; if empty, the window will have no title bar. All ctrl characters will be removed.
withborder	will draw a border around the screen if true.
withzxbands	will put ZX color bands at the title bar (if any) when it is TRUE. An exception will be raised if there is not enough width in the window to print these bands plus the title.
wincols	are the colors used for drawing the background of the window and diverse decorators (e.g., frames). Flash will be ignored.
preserveback	preserves the background before showing the window if TRUE, or does not preserve anything if FALSE.

operator=() [2/2]

Window & zxeco::gui::Window::operator= ( Window &&  )

delete

A window with the given parameters.

If it has border, the body of the window will respect 1-char border to the left, right and bottom of the entire window.

Parameters

zxe	is the ZXEcosystem used by the window.
placem	is the placement of the window on a given screen. The width and height must be at least 2 and 1, respectively, and the height must be at least 2 if there is a title and/ or border.
title	is the title; if empty, the window will have no title bar. All ctrl characters will be removed.
withborder	will draw a border around the screen if true.
withzxbands	will put ZX color bands at the title bar (if any) when it is TRUE. An exception will be raised if there is not enough width in the window to print these bands plus the title.
wincols	are the colors used for drawing the background of the window and diverse decorators (e.g., frames). Flash will be ignored.
preserveback	preserves the background before showing the window if TRUE, or does not preserve anything if FALSE.

zxEco()

ZXEco & zxeco::gui::Window::zxEco ( void  )

inlinenoexcept

Return the ecosystem where the window is working.

Definition at line 170 of file ZXWindows.h.

placement()

const DoubleRect & zxeco::gui::Window::placement ( void  ) const

inlinenoexcept

Return a reference to the absolute placement of the window.

Definition at line 173 of file ZXWindows.h.

bodyRelRect()

const CharRect & zxeco::gui::Window::bodyRelRect ( void  ) const

inlinenoexcept

Return a reference to the body rectangle of the window w.r.t. its orig.

That body area is where the window can place its contents; the rest, if any, is devoted to the title and border.

Definition at line 176 of file ZXWindows.h.

winColors()

const WinColors & zxeco::gui::Window::winColors ( void  ) const

inlinenoexcept

Return the ecosystem where the window is working.

Definition at line 180 of file ZXWindows.h.

hasBorder()

bool zxeco::gui::Window::hasBorder ( void  ) const

inlinenoexcept

Return TRUE if the window has a border.

Definition at line 182 of file ZXWindows.h.

rootWidget()

Widget * zxeco::gui::Window::rootWidget

(

void

)

Return the root widget or nullptr if none.

Throw if there are no widgets inserted in the window.

manage()

MngResult zxeco::gui::Window::manage

(

unsigned

permill = 10

)

Show the window and interact with the user in the given ecosystem.

This method must be called from within some automatically refreshed code in order to have access to the latest events in the desktop. The method does not hide the window when returning, but shows it at first if it is hidden. Furthermore, this method can be called (for a different window) from code that is managed by the same method in another window.

Parameters

permill

is the period in milliseconds for sampling user interaction.

Note

-All the container widgets in the widget tree of the window must be closed for additions before calling this method.

show()

void zxeco::gui::Window::show

(

void

)

Show the window space preserving previous background if desired.

If in UNDRAWN state, do preservation and redraw with blank body; if in VISIBLE_* states, do nothing; if in HIDDEN_PRES, do preservation and restore previous contents; if in HIDDEN_UNPRES, do preservation and redraw blank.

Note

Drawing the screen changes the state of the underlying Screen (cursor, colors, etc.).

hide()

void zxeco::gui::Window::hide

(

bool

preservcontent = true

)

Hide the window, preserving the window contents if desired.

If in UNDRAWN or HIDDEN_* states, do nothing; if in VISIBLE_PRES, over- write the previous preservation if any and restore previous background; if in VISIBLE_UNPRES, do preservation if required and do not modify the screen.

clearBody()

void zxeco::gui::Window::clearBody ( void  )

inline

Clear the body area. Do nothing if the current state is not visible.

Definition at line 230 of file ZXWindows.h.

zxeco::gui::Window::DepthFirstInserter

class zxeco::gui::Window::DepthFirstInserter

To insert widgets in a window in a depth-first fashion.

Definition at line 60 of file ZXWindows.h.

Public Member Functions
	DepthFirstInserter (bool autoid=false)
	Default constructor. More...
void	changeAutoID (bool autoid)
	Change the current auto-ID mode to AUTOID (see the constructor). More...
bool	autoIDMode (void) const noexcept
	Return the current auto-ID mode (see the constructor). More...
void	checkAutoIDMode (void) const
	If the inserter is not in auto-ID mode, throw (see the constructor)
Widget &	add (const Widget::Ptr &wp)
	Add a new widget as child of the current parent. More...
void	closeContainer (void)
	Close additions of widgets to the current container. More...
Widget *	root (void) const noexcept
	Return a pointer to the root widget, if any, or nullptr otherwise. More...
void	setInWindow (Window &w)
	Set the root widget of W to the root widget of this inserter. More...

Constructor & Destructor Documentation

DepthFirstInserter()

zxeco::gui::Window::DepthFirstInserter::DepthFirstInserter ( bool  autoid = false )

inline

Default constructor.

<

Parameters

autoid

must be true for the add() method to ignore the error when an already existing ID is added -substituting that ID for an unused one-. If you use this possibility, it is recommended to set all your widgets ID to 0 for more efficient ID replacements.

Definition at line 69 of file ZXWindows.h.

Member Function Documentation

changeAutoID()

void zxeco::gui::Window::DepthFirstInserter::changeAutoID ( bool  autoid )

inline

Change the current auto-ID mode to AUTOID (see the constructor).

Definition at line 72 of file ZXWindows.h.

autoIDMode()

bool zxeco::gui::Window::DepthFirstInserter::autoIDMode ( void  ) const

inlinenoexcept

Return the current auto-ID mode (see the constructor).

Definition at line 75 of file ZXWindows.h.

add()

Widget & zxeco::gui::Window::DepthFirstInserter::add

(

const Widget::Ptr &

wp

)

Add a new widget as child of the current parent.

If WP is a user container, it becomes the new current parent. The first add widget in the inserter must be a container (user or not). The parents of the widgets added with this method will be modified in order to form the tree. If autoid is activated when creating the inserter and WP has an already existing ID in the to-be-inserted tree, the WP ID will be changed by this method to avoid the duplication.

closeContainer()

void zxeco::gui::Window::DepthFirstInserter::closeContainer ( void  )

inline

Close additions of widgets to the current container.

Next widgets will be added to the previous opened container. If the tree is closed more than possible, do nothing, but further additions will throw.

Definition at line 91 of file ZXWindows.h.

root()

Widget * zxeco::gui::Window::DepthFirstInserter::root ( void  ) const

inlinenoexcept

Return a pointer to the root widget, if any, or nullptr otherwise.

Definition at line 96 of file ZXWindows.h.

setInWindow()

void zxeco::gui::Window::DepthFirstInserter::setInWindow

(

Window &

w

)

Set the root widget of W to the root widget of this inserter.

Does not clear the inserter. Throw if the window has already a root widget.

Typedef Documentation

Ptr

using zxeco::gui::Window::Ptr = std::unique_ptr<Window>

Safe pointer to a window.

Definition at line 57 of file ZXWindows.h.

Enumeration Type Documentation

MngResult

enum class zxeco::gui::Window::MngResult

strong

Possible results of calling the manage() method.

Enumerator
DESKCLOSE_EVENT	A close of desktop received.
FINISHING_CALLBACK	A callback tells to finish.
OUT_CLICK	A click/unclick out of win.

Definition at line 114 of file ZXWindows.h.

Variable Documentation

kLengthBars

constexpr CharDist zxeco::gui::Window::kLengthBars = 7

staticconstexpr

Number of chars printed in the title ZX when there are bars.

spc + 5 bands + spc

Definition at line 121 of file ZXWindows.h.