Description

This module provides the most common dialogs.

Copyright: See LICENSE.txt and AUTHORS.txt file.

http://jafma.net

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

Collaboration diagram for Set of common dialogs 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::MessageDialog
	A dialog to provide information and request some simple user interaction. More...

class	zxeco::gui::ExplanationDialog
	A dialog to provide long, non-editable info. More...

class	zxeco::gui::FileDialog
	A dialog to let the user select a file or directory in a filesystem. More...

class	zxeco::gui::MenuDialog
	A dialog to show a plain ZX-style menu and let the user select one option. More...

Class Documentation

◆ zxeco::gui::MessageDialog

class zxeco::gui::MessageDialog

A dialog to provide information and request some simple user interaction.

The message is just a single-line text.

Definition at line 44 of file ZXDialogsCommon.h.

Inheritance diagram for zxeco::gui::MessageDialog:

[legend]

Collaboration diagram for zxeco::gui::MessageDialog:

[legend]

Public Types
enum	: uint8_t { kOk = 1 , kYes = 2 , kNo = 4 , kCancel = 8 , kClose = 16 }
	Possible buttons that the dialog will have. More...

Static Public Attributes
static const uint8_t	kOnlyClose = kClose
	A combination of buttons with only the CLOSE button. More...

static const uint8_t	kOnlyOk = kOk
	A combination of buttons with only the OK button. More...

static const uint8_t	kYesNo = kYes \| kNo
	A combination of buttons with YES + NO buttons. More...

static const uint8_t	kOkCancel = kOk \| kCancel
	A combination of buttons with OK + CANCEL buttons. More...

Public Member Functions
	MessageDialog (ZXEco &zxe, const std::string &title, const std::string &msg, uint8_t buttons)
	Constructor with a certain combination of buttons. More...

int	show (bool center=true, const CharCursor &corner={0, 0}, const CharArea &dims={0, 0})
	Show the dialog, get the user choice and close it again. More...

Public Member Functions inherited from zxeco::gui::Dialog
	Dialog (ZXEco &zxe, const std::string &title)
	Create a dialog with that ecosystem and title. More...

virtual	~Dialog (void)=default
	Just to activate polymorphism in delete.

virtual int	show (bool center, const CharCursor &corner, const CharArea &dims)=0
	Must show the dialog, interact with the user, and close it. More...

Additional Inherited Members
Static Public Member Functions inherited from zxeco::gui::Dialog
static const WinColors &	winColorsForDialogs (void)
	Return the window colors used in all dialogs.

Protected Member Functions inherited from zxeco::gui::Dialog
Window::MngResult	openAndInteract (bool closeifout=false, bool center=true, const CharCursor &corner={0, 0}, const CharArea &dims={0, 0})
	Open the dialog and interact with the user. More...

Protected Attributes inherited from zxeco::gui::Dialog
const std::string	title_

ZXEco &	zxe_

Window::DepthFirstInserter	wins_
	Note that is not in auto-ID mode. More...

Member Enumeration Documentation

◆ anonymous enum

anonymous enum : uint8_t

Possible buttons that the dialog will have.

At least one button must exist.

Definition at line 50 of file ZXDialogsCommon.h.

Constructor & Destructor Documentation

◆ MessageDialog()

zxeco::gui::MessageDialog::MessageDialog	(	ZXEco &	zxe,
		const std::string &	title,
		const std::string &	msg,
		uint8_t	buttons
	)

Constructor with a certain combination of buttons.

Parameters

zxe	is the ecosystem where the dialog will appear.
title	is the title of the dialog; if after removing all ctrl chars it gets empty, throw.
msg	is the message to show; if after removing all location ctrl chars it gets empty, throw.
buttons	is the combination of buttons desired for the dialog. They will be shown in the same order as in the Result type.

Member Function Documentation

◆ show()

int zxeco::gui::MessageDialog::show	(	bool	center = `true`,
		const CharCursor &	corner = `{0, 0}`,
		const CharArea &	dims = `{0, 0}`
	)

virtual

Show the dialog, get the user choice and close it again.

If the desktop is closed, return kDesktopClosed. It can be reopened many times.

Implements zxeco::gui::Dialog.

Member Data Documentation

◆ kOnlyClose

const uint8_t zxeco::gui::MessageDialog::kOnlyClose = kClose

static

A combination of buttons with only the CLOSE button.

Definition at line 59 of file ZXDialogsCommon.h.

◆ kOnlyOk

const uint8_t zxeco::gui::MessageDialog::kOnlyOk = kOk

static

A combination of buttons with only the OK button.

Definition at line 62 of file ZXDialogsCommon.h.

◆ kYesNo

const uint8_t zxeco::gui::MessageDialog::kYesNo = kYes | kNo

static

A combination of buttons with YES + NO buttons.

Definition at line 65 of file ZXDialogsCommon.h.

◆ kOkCancel

const uint8_t zxeco::gui::MessageDialog::kOkCancel = kOk | kCancel

static

A combination of buttons with OK + CANCEL buttons.

Definition at line 68 of file ZXDialogsCommon.h.

◆ zxeco::gui::ExplanationDialog

class zxeco::gui::ExplanationDialog

A dialog to provide long, non-editable info.

The message is a text that can be multi-line and contain any ASCII control command of the ZX.

Definition at line 105 of file ZXDialogsCommon.h.

Inheritance diagram for zxeco::gui::ExplanationDialog:

[legend]

Collaboration diagram for zxeco::gui::ExplanationDialog:

[legend]

Static Public Attributes
static const CharArea	kAreaNotMessage
	Height and width occupied by the entire dialog without message or title. More...

Public Member Functions
	ExplanationDialog (ZXEco &zxe, const std::string &title, const std::string &expl, const CharArea &explarea, const uint8_t *udgs=nullptr)
	Constructor with a certain combination of buttons. More...

int	show (bool center=true, const CharCursor &corner={0, 0}, const CharArea &dims={0, 0})
	Show the dialog, wait for the user and close it again. More...

Public Member Functions inherited from zxeco::gui::Dialog
	Dialog (ZXEco &zxe, const std::string &title)
	Create a dialog with that ecosystem and title. More...

virtual	~Dialog (void)=default
	Just to activate polymorphism in delete.

virtual int	show (bool center, const CharCursor &corner, const CharArea &dims)=0
	Must show the dialog, interact with the user, and close it. More...

Additional Inherited Members
Static Public Member Functions inherited from zxeco::gui::Dialog
static const WinColors &	winColorsForDialogs (void)
	Return the window colors used in all dialogs.

Protected Member Functions inherited from zxeco::gui::Dialog
Window::MngResult	openAndInteract (bool closeifout=false, bool center=true, const CharCursor &corner={0, 0}, const CharArea &dims={0, 0})
	Open the dialog and interact with the user. More...

Protected Attributes inherited from zxeco::gui::Dialog
const std::string	title_

ZXEco &	zxe_

Window::DepthFirstInserter	wins_
	Note that is not in auto-ID mode. More...

Constructor & Destructor Documentation

◆ ExplanationDialog()

zxeco::gui::ExplanationDialog::ExplanationDialog	(	ZXEco &	zxe,
		const std::string &	title,
		const std::string &	expl,
		const CharArea &	explarea,
		const uint8_t *	udgs = `nullptr`
	)

Constructor with a certain combination of buttons.

Parameters

zxe	is the ecosystem where the dialog will appear.
title	is the title of the dialog; if after removing all ctrl chars it gets empty, throw.
expl	is the message to show; it cannot be empty. It can contain any ZX control code.
explarea	is the total area for which the message has been designed; if a smaller area is available for the widget, scroll bars will appear; if greater area is available in some dimension, the corresponding dimension in explarea will be the one taken into account to display the text. Notice that you can use Screen::areaForPrint() to calculate an area for printing a message.

Member Function Documentation

◆ show()

int zxeco::gui::ExplanationDialog::show	(	bool	center = `true`,
		const CharCursor &	corner = `{0, 0}`,
		const CharArea &	dims = `{0, 0}`
	)

virtual

Show the dialog, wait for the user and close it again.

If the desktop is closed, return kDesktopClosed. It can be reopened many times.

Implements zxeco::gui::Dialog.

Member Data Documentation

◆ kAreaNotMessage

const CharArea zxeco::gui::ExplanationDialog::kAreaNotMessage

static

Height and width occupied by the entire dialog without message or title.

Definition at line 109 of file ZXDialogsCommon.h.

◆ zxeco::gui::FileDialog

class zxeco::gui::FileDialog

A dialog to let the user select a file or directory in a filesystem.

Definition at line 151 of file ZXDialogsCommon.h.

Inheritance diagram for zxeco::gui::FileDialog:

[legend]

Collaboration diagram for zxeco::gui::FileDialog:

[legend]

Public Types
enum class	Type : uint8_t { kForLoading , kForSaving , kForOpening , kForCreating }
	Types of file dialogs. More...

Public Member Functions
	FileDialog (ZXEco &zxe, Type t, const std::string &title, const std::filesystem::path &path=std::filesystem::path{}, const std::string &custom="", const std::string &initedit="", bool automaticoverwrite=false)
	Create a dialog for that path. More...

int	show (bool center=true, const CharCursor &corner={0, 0}, const CharArea &dims={0, 0})
	Show the dialog and get the file selection. More...

const std::filesystem::path &	lastFile (void) const noexcept
	< Return the file selected the last time (or empty if none). More...

const std::filesystem::path &	lastPath (void) const
	Return the last path set in the file browser or throw if no browser.

Public Member Functions inherited from zxeco::gui::Dialog
	Dialog (ZXEco &zxe, const std::string &title)
	Create a dialog with that ecosystem and title. More...

virtual	~Dialog (void)=default
	Just to activate polymorphism in delete.

virtual int	show (bool center, const CharCursor &corner, const CharArea &dims)=0
	Must show the dialog, interact with the user, and close it. More...

Additional Inherited Members
Static Public Member Functions inherited from zxeco::gui::Dialog
static const WinColors &	winColorsForDialogs (void)
	Return the window colors used in all dialogs.

Protected Member Functions inherited from zxeco::gui::Dialog
Window::MngResult	openAndInteract (bool closeifout=false, bool center=true, const CharCursor &corner={0, 0}, const CharArea &dims={0, 0})
	Open the dialog and interact with the user. More...

Protected Attributes inherited from zxeco::gui::Dialog
const std::string	title_

ZXEco &	zxe_

Window::DepthFirstInserter	wins_
	Note that is not in auto-ID mode. More...

Member Enumeration Documentation

◆ Type

enum class zxeco::gui::FileDialog::Type : uint8_t

strong

Types of file dialogs.

Enumerator
kForLoading	To select a file to load.
kForSaving	To select a file to save.
kForOpening	To select a directory to open.
kForCreating	To select a directory to create.

Definition at line 156 of file ZXDialogsCommon.h.

Constructor & Destructor Documentation

◆ FileDialog()

zxeco::gui::FileDialog::FileDialog	(	ZXEco &	zxe,
		Type	t,
		const std::string &	title,
		const std::filesystem::path &	path = `std::filesystem::path{}`,
		const std::string &	custom = `""`,
		const std::string &	initedit = `""`,
		bool	automaticoverwrite = `false`
	)

Create a dialog for that path.

Parameters

custom	is the text of the selection button that substitutes the default selection button text if not empty.
initedit	is the text to put initially in the filename editing field of the dialog.
automaticoverwrite	indicates whether the user will be asked to overwrite the file in a save operation if the file previously exists (true) or not asking at all (false).

Member Function Documentation

◆ show()

int zxeco::gui::FileDialog::show	(	bool	center = `true`,
		const CharCursor &	corner = `{0, 0}`,
		const CharArea &	dims = `{0, 0}`
	)

virtual

Show the dialog and get the file selection.

The DIMS param cannot be empty. Return kSelected if the user selected a file or kCancel if not. If kForSaving/kForCreating type, checks that the user allows for rewriting with another dialog and return kError if not. If kForLoading checks that the file exists and, if not, shows an info dialog and return kError.

Implements zxeco::gui::Dialog.

◆ lastFile()

const std::filesystem::path & zxeco::gui::FileDialog::lastFile ( void ) const

inlinenoexcept

< Return the file selected the last time (or empty if none).

Definition at line 188 of file ZXDialogsCommon.h.

◆ zxeco::gui::MenuDialog

class zxeco::gui::MenuDialog

A dialog to show a plain ZX-style menu and let the user select one option.

Definition at line 215 of file ZXDialogsCommon.h.

Inheritance diagram for zxeco::gui::MenuDialog:

[legend]

Collaboration diagram for zxeco::gui::MenuDialog:

[legend]

Public Member Functions
	MenuDialog (ZXEco &zxe, const std::string &title, const Label::Vector &options)
	Create the dialog with those options, that are copied internally.

int	show (bool center=true, const CharCursor &corner={0, 0}, const CharArea &dims={0, 0})
	Show the dialog and get an option. More...

int	show (const CharCursor &context)
	Show the dialog as a context menu, i.e., auto placing and sizing. More...

size_t	lastOption (void) const noexcept
	Return the last option selected, or a number >= number of options othrw. More...

const LabelList &	listOptions (void) const noexcept
	Return a reference to the list of options. More...

Public Member Functions inherited from zxeco::gui::Dialog
	Dialog (ZXEco &zxe, const std::string &title)
	Create a dialog with that ecosystem and title. More...

virtual	~Dialog (void)=default
	Just to activate polymorphism in delete.

virtual int	show (bool center, const CharCursor &corner, const CharArea &dims)=0
	Must show the dialog, interact with the user, and close it. More...

Additional Inherited Members
Static Public Member Functions inherited from zxeco::gui::Dialog
static const WinColors &	winColorsForDialogs (void)
	Return the window colors used in all dialogs.

Protected Member Functions inherited from zxeco::gui::Dialog
Window::MngResult	openAndInteract (bool closeifout=false, bool center=true, const CharCursor &corner={0, 0}, const CharArea &dims={0, 0})
	Open the dialog and interact with the user. More...

Protected Attributes inherited from zxeco::gui::Dialog
const std::string	title_

ZXEco &	zxe_

Window::DepthFirstInserter	wins_
	Note that is not in auto-ID mode. More...

Member Function Documentation

◆ show() [1/2]

int zxeco::gui::MenuDialog::show	(	bool	center = `true`,
		const CharCursor &	corner = `{0, 0}`,
		const CharArea &	dims = `{0, 0}`
	)

virtual

Show the dialog and get an option.

Return kSelected if selected, or kDesktopClosed if the desktop is closed.

Implements zxeco::gui::Dialog.

◆ show() [2/2]

int zxeco::gui::MenuDialog::show ( const CharCursor & context )

Show the dialog as a context menu, i.e., auto placing and sizing.

Unlike other dialogs, this one (opened with this method) can return OUT_CLICK if the user click out of it. It is also recommended to set the title of the dialog to "" for this case.

◆ lastOption()

size_t zxeco::gui::MenuDialog::lastOption ( void ) const

inlinenoexcept

Return the last option selected, or a number >= number of options othrw.

Notice that separators (options == "=") are never the result of this method, i.e., their indexes are never returned.

Definition at line 236 of file ZXDialogsCommon.h.

◆ listOptions()

const LabelList & zxeco::gui::MenuDialog::listOptions ( void ) const

inlinenoexcept

Return a reference to the list of options.

Definition at line 240 of file ZXDialogsCommon.h.

Description

Namespaces

Classes

Class Documentation

◆ zxeco::gui::MessageDialog

Public Types

Static Public Attributes

Public Member Functions

Additional Inherited Members

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ MessageDialog()

Member Function Documentation

◆ show()

Member Data Documentation

◆ kOnlyClose

◆ kOnlyOk

◆ kYesNo

◆ kOkCancel

◆ zxeco::gui::ExplanationDialog

Static Public Attributes

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ ExplanationDialog()

Member Function Documentation

◆ show()

Member Data Documentation

◆ kAreaNotMessage

◆ zxeco::gui::FileDialog

Public Types

Public Member Functions

Additional Inherited Members

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ FileDialog()

Member Function Documentation

◆ show()

◆ lastFile()

◆ zxeco::gui::MenuDialog

Public Member Functions

Additional Inherited Members

Member Function Documentation

◆ show() [1/2]

◆ show() [2/2]

◆ lastOption()

◆ listOptions()