Description

Main module that manages the rest of modules in order to provide a
ZX Spectrum-like ecosystem, i.e., a graphical window, pointing device
and keyboard, to general C++ programs, through the zxeco::ZXEco class.

**You should start in this module**.

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 The ZX Ecosystem:

Namespaces
namespace	zxeco
	The main namespace of the library, that spans across all the zx modules.

Classes
class	zxeco::ZXEco
	Class that provides access to the entire ecosystem: graphics, keyboard, etc. More...

class	zxeco::ZXEco::RawGeometry
	Raw geometrical information about the window geometry of ZXEco objects. More...

Class Documentation

◆ zxeco::ZXEco

class zxeco::ZXEco

Class that provides access to the entire ecosystem: graphics, keyboard, etc.

There can only be one such an ecosystem in a given executable program (singleton class).

This class is thread-safe.

Definition at line 58 of file ZXEcosystem.h.

Static Public Member Functions
----------------— Class methods ----------------—
static ZXEco &	theZXEco (DesktopInterface *desktop=nullptr)
	Return the singleton ZXEco object for the application. More...

Public Member Functions
----------------— Constructors ----------------—
(The constructor is private, cause this is a singleton)
	ZXEco (const ZXEco &)=delete

ZXEco &	operator= (const ZXEco &)=delete

	ZXEco (ZXEco &&disptomove)=delete

ZXEco &	operator= (ZXEco &&disptomove)=delete

virtual	~ZXEco (void)

----------------— General methods ----------------—
DesktopInterface &	myDesktopInterface (void) noexcept
	Return the associated DesktopInterface. More...

void	activate (const std::string &title, PixelDist borderwidth, PixelDist borderheight, unsigned scalex=1, unsigned scaley=1, const PixArea &size={SCREENW, SCREENH}, const Screen::ExpandToken &exptok=Screen::kInvExpandToken, uint8_t bitmap=nullptr, uint8_t attrmap=nullptr)
	Activate the zx ecosystem, opening its window. More...

void	close (void)
	Deactivate the zx ecosystem. More...

bool	valid (void)
	Whether the zx ecosystem is valid or not. More...

const std::string &	windowTitle (void) const
	Return a reference to the title of the last activation. More...

std::chrono::time_point< std::chrono::steady_clock >	startTime (void) noexcept
	Return the start-up time of the zx ecosystem. More...

const RawGeometry &	rawGeometry (void) const
	Return a const reference to the raw geometry of the window. More...

-------------— Managed Display methods ----------------—
All these methods provide a ZX display that is managed automatically by the ZXEco object, thus they are recommeded if you do not have special speed or color requirements. Also, the management of events (keyboard, mouse...) is implemented in these methods.
Screen &	screen (void) const
	If the ecosystem has been activated, return a reference to the screen.

void	refreshCode (const UserCode &codetorun, RefreshMode rm=RefreshMode::PERIODIC, RefreshType rt=RefreshType::BOTH, unsigned period=20, const PalettizedWindow::Event::IDSet &whichevents={{PalettizedWindow::Event::ID::W_CLOSED}}, const UserCode &periodiccode=kNullUserCode)
	Execute user code once with some refresh mode, type and parameters. More...

bool	isInRefreshingCode (void) const noexcept
	Return TRUE if the caller is in the context of a previous refresh(). More...

void	refresh (RefreshType rt=RefreshType::BOTH, const PalettizedWindow::Event::IDSet &whichevents={true})
	Do a refresh of the screen, the window events, or both, manually. More...

bool	extractEvent (PalettizedWindow::Event &ev, const PalettizedWindow::Event::IDSet &which={true}, const PalettizedWindow::Event::IDSet &equalstoskip={false}) noexcept
	Extract into EV the oldest event in the system, or return FALSE if none. More...

void	clearEvents (void) noexcept
	Dismiss all still recorded events in the ZXEco window from the desktop. More...

RefreshType	refreshType (void) const noexcept
	Return the current refresh type (not thread-safe). More...

RefreshMode	refreshMode (void) const noexcept
	Return the current refresh mode (not thread-safe). More...

const PalettizedWindow::Event::IDSet &	refreshWhichEvents (void) const noexcept
	< Return a reference to the current set of events that are being recorded More...

const LongTimeStat &	refreshStats (void)
	Consult the statistics of refresh. More...

void	resetRefreshStats (void)
	Reset the statistics of refresh. More...

bool	refreshingScreen (void) const noexcept
	Return whether there is a refresh in course or not, right now. More...

bool	inkAndPaperSwappedByFlash (void) const noexcept
	Return whether a swapping of paper and ink colors is happening. More...

void	activateDecolourMode (const CharRect &rect={})
	Activate the decolour mode, where all attrs are turned into a gray grid. More...

void	deactivateDecolourMode (void)
	Deactivate the decolour mode and all attrs return to their colours. More...

bool	decolourModeActive (void) const noexcept
	Return TRUE if the decolour mode is currently active. More...

void	windowUpdate (const PixRect &rect=PixRect{})
	Commit the given region of the ZX Screen to the desktop window. More...

void	windowRefresh (const PixRect &rect=PixRect{})
	Command the desktop window to show on the desktop its current content. More...

void	windowBorderUpdate (const BorderRect &rect=BorderRect{})
	Commit the given region of the border to the desktop window. More...

void	windowBorderRefresh (const BorderRect &rect=BorderRect{})
	Command the desktop window to show on the desktop the border content. More...

----------------— Direct display methods ----------------—
With these methods you can access the ZX display directly and at maximum speed (with the implementation of the desktop code that you use). Care must be taken, however, since: The accesses to the window are not thread-safe, unlike in the managed methods. The refresh() method should be called anyway in the EVENTS mode in order to update the keyboard/mouse events in the ZXEco object. The ZX Screen object attached to the desktop window gets detached when you use this direct access, thus it is your responsibility to keep the display coherent in both kinds of accesses.
PalettizedWindow &	desktopWindow (void)
	Return the desktop window used by the managed display methods.

----------------— Pointing methods ----------------—
This method throws if the ZXEco object is not activated. The desktop window has a palette that goes from 0 to 15, covering the ZX colours in the same order as in the original machine, from BLACK to WHITE, first without bright and then with bright.
bool	pointingStatus (PointingStatus &ps) noexcept
	Get the status of the mouse within the drawable zone of the ZX window. More...

----------------— Keyboard methods ----------------—
bool	desktopKeyPressed (DesktopInterface::KeyID k)
	Update the internal image of PC keyboard and return TRUE if K pressed. More...

Membrane	membrane (void)
	Get a copy of the internal membrane after updating PC keyboard. More...

Keyboard	keyboard (std::string *lastprstr=nullptr)
	Update internal membrane and PC/ZX keyboards, returning the latter. More...

bool	waitForKey (Keyboard &kb, unsigned millis=20, bool zxandpc=false)
	Wait for any key to be pressed, sampling the keyboard every MILLIS. More...

void	waitForNoKey (unsigned millis=20, bool zxandpc=false)
	Wait for no key pressed, sampling the keyboard every MILLIS. More...

Keyboard	waitOneKey (unsigned ms=20)
	Wait for only one ZX key or combination of keys to be pressed. More...

Keyboard	waitForKeyChange (const Keyboard &oldkb, std::string *lastprstr=nullptr, unsigned millis=20)
	Wait for a change in the ZX keyboard that makes it different from OLDKB. More...

void	forceCapsLock (bool state=true)
	Forces a new state for the caps lock by simulating pressing CAPS+2. More...

----------------— Sound methods ----------------—
void	setVolume (double v)
	Change sound volume (from 0.0 to 1.0) for future sounds. More...

double	volume (void) const noexcept
	Get the current volume of sound. More...

void	play (const Beep &b, bool async=false)
	Play a beep. More...

----------------— Miscellaneous methods ---------------—
Screen::InputCallbacks	flatInputCallbacks (void)
	Construct and return the callbacks needed for input in the flat model. More...

----------------— Types and consts ----------------—
enum class	RefreshType { SCREEN = 1 , EVENTS = 2 , BOTH = 3 }
	Types of refreshes that can be done while executing user code. More...

enum class	RefreshMode { NEVER , PERIODIC }
	Modes of refreshing while executing user code. More...

typedef SimpleStats< double, SSOvPol_IgnoreMoreData< double > >	LongTimeStat
	Simple statistics about durations, gathered for a long time. More...

typedef std::function< void(ZXEco &)>	UserCode
	Prototype for user routines that can be executed while refreshing. More...

static const UserCode	kNullUserCode
	A user code that does nothing. More...

Member Typedef Documentation

◆ LongTimeStat

typedef SimpleStats<double,SSOvPol_IgnoreMoreData<double> > zxeco::ZXEco::LongTimeStat

Simple statistics about durations, gathered for a long time.

Definition at line 80 of file ZXEcosystem.h.

◆ UserCode

typedef std::function<void (ZXEco &)> zxeco::ZXEco::UserCode

Prototype for user routines that can be executed while refreshing.

Definition at line 83 of file ZXEcosystem.h.

Member Enumeration Documentation

◆ RefreshType

enum class zxeco::ZXEco::RefreshType

strong

Types of refreshes that can be done while executing user code.

Enumerator
SCREEN	Only refreshes screen on display.
EVENTS	Only refreshes events received.
BOTH	Refreshes both things.

Definition at line 66 of file ZXEcosystem.h.

◆ RefreshMode

enum class zxeco::ZXEco::RefreshMode

strong

Modes of refreshing while executing user code.

Enumerator
NEVER	Don't refresh anything automatically.
PERIODIC	Refresh periodical & automatically.

Definition at line 74 of file ZXEcosystem.h.

Member Function Documentation

◆ theZXEco()

static ZXEco & zxeco::ZXEco::theZXEco ( DesktopInterface * desktop = nullptr )

static

Return the singleton ZXEco object for the application.

Return a reference to the singleton ZXEco object for the program. In the first call to this method, DESKTOP must point to a desktop interface that must outlive the ZXEco object; in further calls, that pointer will be ignored. Initially, the returned ZXEco object is invalid.

◆ myDesktopInterface()

DesktopInterface & zxeco::ZXEco::myDesktopInterface ( void )

inlinenoexcept

Return the associated DesktopInterface.

Return the desktop interface used for creating this singleton. Recall that the singleton does not own the desktop.

Definition at line 208 of file ZXEcosystem.h.

◆ activate()

void zxeco::ZXEco::activate	(	const std::string &	title,
		PixelDist	borderwidth,
		PixelDist	borderheight,
		unsigned	scalex = `1`,
		unsigned	scaley = `1`,
		const PixArea &	size = `{SCREENW, SCREENH}`,
		const Screen::ExpandToken &	exptok = `Screen::kInvExpandToken`,
		uint8_t *	bitmap = `nullptr`,
		uint8_t *	attrmap = `nullptr`
	)

Activate the zx ecosystem, opening its window.

This method must be called from the main thread. TITLE is the title of the window. The other args define the size of the ZX screen, not restricted to the original ZX size (WIDTH and HEIGHT must be multiple of 8). SCALEX and SCALEY are the zoom factor in x and y of the ZX screen. BITMAP and ATTRMAP, if !nullptr, will be used as the (external) storage of the display instead of creating one anew. If this ZXEco object was already activated, this method closes it & then reactivates it with the given dimensions. Initially, the refresh mode is NEVER, but an initial refresh of type SCREEN is done nevertheless. The refresh type is then set to BOTH. Thus, pending events in the window (key, mouse, window) are not dealt with yet.

◆ close()

void zxeco::ZXEco::close ( void )

Deactivate the zx ecosystem.

Just close the ZXEco object and leave it in invalid state. Do nothing if the ZXEco object is already invalid.

◆ valid()

bool zxeco::ZXEco::valid ( void )

Whether the zx ecosystem is valid or not.

Return TRUE if the ZXEco has been created and activated OK, or false if it is in an invalid state.

◆ windowTitle()

const std::string & zxeco::ZXEco::windowTitle ( void ) const

Return a reference to the title of the last activation.

Throw if not activated.

◆ startTime()

std::chrono::time_point< std::chrono::steady_clock > zxeco::ZXEco::startTime ( void )

inlinenoexcept

Return the start-up time of the zx ecosystem.

Return a copy of the time point when the last activation occurred (undefined if the ZXEco object is still invalid).

Definition at line 247 of file ZXEcosystem.h.

◆ rawGeometry()

const RawGeometry & zxeco::ZXEco::rawGeometry ( void ) const

Return a const reference to the raw geometry of the window.

If the ZXEco object is not activated, throw.

◆ refreshCode()

void zxeco::ZXEco::refreshCode	(	const UserCode &	codetorun,
		RefreshMode	rm = `RefreshMode::PERIODIC`,
		RefreshType	rt = `RefreshType::BOTH`,
		unsigned	period = `20`,
		const PalettizedWindow::Event::IDSet &	whichevents = `{{PalettizedWindow::Event::ID::W_CLOSED}}`,
		const UserCode &	periodiccode = `kNullUserCode`
	)

Execute user code once with some refresh mode, type and parameters.

All screen methods can be used directly on the returned object, but note that any refresh of the screen done by the ZXEco class will access that Screen data and no thread coordination is implemented for that, thus your code may be modifying the Screen while the ZXEco is refreshing it (reading it) to dump it into the desktop window. If the system is not active, this method throws. If the refresh mode is SCREEN or BOTH, the entire screen is refreshed each time. This method cannot be called from a code that is currently being executed by it. The refresh mode will be set to NEVER, the type to BOTH and the events to be refreshed to 'all' after the method is finished.

In NEVER refresh mode, execute CODETORUN once (passing this object as an argument) in the same thread as the caller.

In PERIODIC mode, CODETORUN will run once in a thread different from the caller, while automatic (periodic) refreshes and/or updates of pending events will be performed in the same thread as the caller, with a time precision (not counting preemptions of other tasks of the operating system) up to a millisec. This permits to do the refreshes from the main thread while doing operations (CODETORUN) in another one, something that is needed in graphic desktops that require screen updates and event management in the main thread. PERIODICCODE will be called after the window refreshes are done at each period, in the same thread that does the refreshes (concurrent access to data shared by both PERIODICCODE and CODETORUN are not risky, since these data are accessed from the same thread). PERIODICCODE can be used as a hook for timing, keyboard updates, etc.

If the ZXEco object is invalid, this method does nothing.

Note: -In PERIODIC mode, manual calls to refresh() will not refresh. Any automatic refresh will access the Screen data and no thread coordination is implemented for that, thus your code may be modifying the Screen while the ZXEco is refreshing it (reading it).; -In PERIODIC mode with EVENTS refreshing, the events indicated in the WHICHEVENTS set will accumulate as they occur in the ZXEco object event list; you should clear that list once they have been consulted, using clearEvents(). An approximate number of mouse/key/win events that can accumulate in 20 milliseconds is about 50 when the mouse is moved quickly.; -PERIOD is unsigned -> C++11 standard assure unsigned is 16+ bits.; -Alternatively to using this method, you can call any method of ZXEco directly without encapsulating your code in CODETORUN, e.g. to modify the ZX screen, and you can call refresh() at your convenience to manually update the desktop image and/or the received events when you want. Still, doing all of that through this method instead is recommended for the sake of uniformity with the PERIODIC refresh mode.; -Many graphics desktops need that the refresh operation run in the main thread, having undefined effect otherwise. Take that into account when you call refresh() manually.; -Flash attributes will show correctly iff calls to refresh() are done with enough frequency (more often than or equal to every 320 millis as it is explained in the refresh() method). If you need a simple way to assure that flash animation is visible, use PERIODIC refresh mode.

◆ isInRefreshingCode()

bool zxeco::ZXEco::isInRefreshingCode ( void ) const

inlinenoexcept

Return TRUE if the caller is in the context of a previous refresh().

Definition at line 340 of file ZXEcosystem.h.

◆ refresh()

void zxeco::ZXEco::refresh	(	RefreshType	rt = `RefreshType::BOTH`,
		const PalettizedWindow::Event::IDSet &	whichevents = `{true}`
	)

Do a refresh of the screen, the window events, or both, manually.

If SCREEN refresh, passes the ZX Screen data into the desktop window (as in windowUpdate()) and then refreshes the desktop window (as in windowRefresh()). The entire ZX screen and desktop window are refreshed. In the case of EVENTS refresh, get pending events for the window, send them to be processed by the underlying desktop system, and finally store those of the type indicated in WHICHEVENTS into the ZXEco object (see getEvents() method). If the ZXEco is invalid, do nothing.

Note: -The refresh type is only temporary: after this call, the ZXEco object keep the same refresh type that it had before.; -Initially, the ZXEco object is in NEVER refresh mode, and manual refreshes calling this method are required (flash attrs will not appear in the desktop unless enough refreshes are done).; -If events are refreshed, this accumulates the new ones to old ones, thus it is convenient to clearEvents() from time to time to free unused (already consulted) events.; -If called while in PERIODIC refresh mode, does nothing.

◆ extractEvent()

bool zxeco::ZXEco::extractEvent	(	PalettizedWindow::Event &	ev,
		const PalettizedWindow::Event::IDSet &	which = `{true}`,
		const PalettizedWindow::Event::IDSet &	equalstoskip = `{false}`
	)

noexcept

Extract into EV the oldest event in the system, or return FALSE if none.

All the events that are not in WHICH will be popped and dropped before reaching the first one that is in WHICH. Then, skip as many contiguous events as there are in the system from that one as long as they have the same ID as that one and belong to EQUALSTOSKIP, returning the latest one skipped (if EQUALSTOSKIP == empty, no one will ever be skipped and the one found in the first place will be returned). This method is thread-safe and can be called from user's code run by refreshCode().

◆ clearEvents()

void zxeco::ZXEco::clearEvents ( void )

noexcept

Dismiss all still recorded events in the ZXEco window from the desktop.

This method is thread-safe and can be called from user's code run by refreshCode().

◆ refreshType()

RefreshType zxeco::ZXEco::refreshType ( void ) const

inlinenoexcept

Return the current refresh type (not thread-safe).

Definition at line 388 of file ZXEcosystem.h.

◆ refreshMode()

RefreshMode zxeco::ZXEco::refreshMode ( void ) const

inlinenoexcept

Return the current refresh mode (not thread-safe).

Definition at line 391 of file ZXEcosystem.h.

◆ refreshWhichEvents()

const PalettizedWindow::Event::IDSet & zxeco::ZXEco::refreshWhichEvents ( void ) const

inlinenoexcept

< Return a reference to the current set of events that are being recorded

< Not thread-safe.

Definition at line 394 of file ZXEcosystem.h.

◆ refreshStats()

const LongTimeStat & zxeco::ZXEco::refreshStats ( void )

Consult the statistics of refresh.

Return a read-only reference to the internal statistics gathered so far about the time incurred when doing a refresh (in microseconds). These times include both screen and event refreshes if they are done.

◆ resetRefreshStats()

void zxeco::ZXEco::resetRefreshStats ( void )

Reset the statistics of refresh.

Reset gathered statistic data about refreshes of the desktop, losing them.

◆ refreshingScreen()

bool zxeco::ZXEco::refreshingScreen ( void ) const

inlinenoexcept

Return whether there is a refresh in course or not, right now.

Return TRUE if the ZX screen is being refreshed currently, either manually (by you) or periodically. You can consider the result of this function as a digital signal that goes high (TRUE) while the refreshing process is running, and low (FALSE) otherwise (undefined if the ZXEco object is invalid). This method can be called anytime, but it is specially interesting when running code in PERIODIC refreshing mode (see refreshCode()): your code can wait for the falling edge of the mentioned signal and then do its work, being then in sync with the desktop display updates.

Definition at line 411 of file ZXEcosystem.h.

◆ inkAndPaperSwappedByFlash()

bool zxeco::ZXEco::inkAndPaperSwappedByFlash ( void ) const

noexcept

Return whether a swapping of paper and ink colors is happening.

Return TRUE if the current clock indicates that ink and paper of flash-on attributes are swapped at this time. The result of this method can be considered as a signal that is high whenever flash attrs show their ink and paper swapped and low otherwise.

◆ activateDecolourMode()

void zxeco::ZXEco::activateDecolourMode ( const CharRect & rect = {} )

Activate the decolour mode, where all attrs are turned into a gray grid.

RECT is the region where the decolouring occurs; the entire screen if empty. Only after the next refresh() is guaranteed that the window shows the decolouring requested by this method. If the decolour mode is already active, does nothing (to change the rectangle, you must first deactivate the decolour mode).

Note: -Decolour mode does not affect the ZX screen content, that still contains all the colours. It is just a visual effect on the desktop window.

◆ deactivateDecolourMode()

void zxeco::ZXEco::deactivateDecolourMode ( void )

Deactivate the decolour mode and all attrs return to their colours.

Only after the next refresh() is guaranteed that the window shows the colouring. If the mode is already inactive, does nothing.

◆ decolourModeActive()

bool zxeco::ZXEco::decolourModeActive ( void ) const

inlinenoexcept

Return TRUE if the decolour mode is currently active.

Definition at line 447 of file ZXEcosystem.h.

◆ windowUpdate()

void zxeco::ZXEco::windowUpdate ( const PixRect & rect = PixRect{} )

Commit the given region of the ZX Screen to the desktop window.

The desktop window is not rendered onto the desktop; only those data are updated in its internal buffers, leaving them ready to be rendered. If RECT is empty, passes the entire screen.

Note: - If the ZXEco object is not activated, do nothing.; - This method will access the Screen data and no thread coordination is implemented for that, thus other threads in your code may be modifying the Screen while the ZXEco is refreshing it (reading it).; - The data is passed with correct appearance of ink and paper in those attributes that have the flash component on, considering the current time: the first half-period of flash animation after display activation has no color inversion; after that, every 320 milliseconds the inversion takes place (see below). Thus, depending on the time after activation when this method is called, colors will be swapped or not in those attributes with flash on.; - Take care of regions that affect only a pixel area not aligned with complete char cells; if there is flash in those cells, only the given area is passed to the desktop window; therefore, this method allows to violate the attribute restrictions of the ZX Screen (but only inside the desktop window; the ZX screen data is unmodified).; -In the original ZX, every 16 TV frames the ULA swapped colors of ink and paper in flash-on attribute cells, producing a complete flashing period -2 such inversions- of 32 TV cycles, or 640 milliseconds -1 TV cycle was 20 milliseconds-.

◆ windowRefresh()

void zxeco::ZXEco::windowRefresh ( const PixRect & rect = PixRect{} )

Command the desktop window to show on the desktop its current content.

The given rectangle indicates which portion of the window internal buffers has been updated with windowUpdate() after the last call to this method; depending on the window implementation, it can render the entire window (including the border) or only RECT, or even use RECT just to do less data processing but still render the entire window (see DesktopInterface.h). If RECT is empty, it indicates the entire window, including the border. If the ZXEco is not activated, do nothing.

◆ windowBorderUpdate()

void zxeco::ZXEco::windowBorderUpdate ( const BorderRect & rect = BorderRect{} )

Commit the given region of the border to the desktop window.

Only border pixels are passed. If RECT is empty, passes the entire border.

Note: - If the ZXEco object is not activated, do nothing.; - This method will access the Screen data and no thread coordination is implemented for that, thus other threads in your code may be modifying the Screen while the ZXEco is refreshing it (reading it).

◆ windowBorderRefresh()

void zxeco::ZXEco::windowBorderRefresh ( const BorderRect & rect = BorderRect{} )

Command the desktop window to show on the desktop the border content.

The given rectangle indicates the portion of the border internal buffer that has been updated with windowBorderUpdate() after the last call to this method; depending on the window implementation, it can render the entire window (including the drawable area) or only RECT, or even use RECT just to do less data processing but still render the entire window (see DesktopInterface.h). If RECT is empty, it indicates the entire border. If the ZXEco is not activated, do nothing.

◆ pointingStatus()

bool zxeco::ZXEco::pointingStatus ( PointingStatus & ps )

noexcept

Get the status of the mouse within the drawable zone of the ZX window.

Fill the fields of PS with the current state of the pointing device on the ZX window, as long as that window has the focus. If the pointer is on the drawable zone, the values are correct and the method return TRUE; if it is on the border area, or outside the window, or the ZXEco object is invalid, this method returns FALSE and does not fill anything.

Note: -For this method to work correctly, previous refreshes of events must be done, either manually or automatically.

◆ desktopKeyPressed()

bool zxeco::ZXEco::desktopKeyPressed ( DesktopInterface::KeyID k )

Update the internal image of PC keyboard and return TRUE if K pressed.

Unlike the rest of the methods concerning the keyboard, this one works for any desktop key, not only for the ZX keys. If the ecosystem is not activated (i.e., window opened), always return FALSE. Like the rest of the methods, they need refreshes to have the desktop keyboard state correctly updated.

◆ membrane()

Membrane zxeco::ZXEco::membrane ( void )

Get a copy of the internal membrane after updating PC keyboard.

Update the internal state of the keyboard membrane and return a copy. The internal membrane has an up-to-date state iff enough refreshes have been done (more frequently than the user typing speed, in general). A copy is returned to protect the internal membrane against concurrent accesses (accessing it through this method is safe). The membrane is in an undefined state if ZXEco is invalid.

Note: -This method updates the membrane but not the keyboard, for the sake of speed if you only use the former to access key pressings.

◆ keyboard()

Keyboard zxeco::ZXEco::keyboard ( std::string * lastprstr = nullptr )

Update internal membrane and PC/ZX keyboards, returning the latter.

The same (update + return copy) as membrane() for the view of the keyboard as a typing one, but accumulating all the history so far. If LASTPRSTR != nullptr, fill it in with the string corresponding to the last key(s) pressed, according to the keyboard mode when they were pressed.

Note: -This method updates both the internal membrane and the typing keyboard.; -A copy and not a reference is returned to protect against concurrent accesses. This method is a safe way of accessing the keyboard.; -This method is not called by the refresh() methods, that only deal with screen / window events. Therefore, this method must be called frequently enough to keep a consistent state of the internal keyboard if you use it. The input() method DOES exactly that (while it is executing).; -Another way of automatically calling this method periodically is by using the hook installed by refresh() in PERIODIC mode.

◆ waitForKey()

bool zxeco::ZXEco::waitForKey	(	Keyboard &	kb,
		unsigned	millis = `20`,
		bool	zxandpc = `false`
	)

Wait for any key to be pressed, sampling the keyboard every MILLIS.

Use the keyboard() method internally for sampling, thus it updates the PC keyboard, the ZX membrane and the ZX keyboard. If MILLIS == 0, sample continuously. If ZXANDPC == FALSE, only waits for ZX keys; otherwise it waits for PC and ZX keys. Put a COPY of the ZX keyboard at the moment the key was detected into KB. Return TRUE if the key was a ZX key and FALSE if it was a PC (non-ZX) key. If the ZXEco is invalid, do nothing.

Note: -Other methods can use the keyboard concurrently; no mutual exclusive use is done while sampling.; -An average typing speed recorded by a human is about 100 5-character words per minute (https://en.wikipedia.org/wiki/Words_per_minute), which amounts to around 500 characters per second, which is 120 millis per character, which can be assumed to be 60 ms for pressing and 60 ms for releasing the key. Having MILLIS == 20 is a correct use of Nyquist sampling theorem.

◆ waitForNoKey()

void zxeco::ZXEco::waitForNoKey	(	unsigned	millis = `20`,
		bool	zxandpc = `false`
	)

Wait for no key pressed, sampling the keyboard every MILLIS.

Use the keyboard() method internally for sampling, thus it updates the PC keyboard, the ZX membrane and the ZX keyboard. If MILLIS == 0, sample continuously. If ZXANDPC == FALSE, only waits for no ZX key; otherwise it waits for no PC nor ZX key. If the ZXEco is invalid, do nothing.

◆ waitOneKey()

Keyboard zxeco::ZXEco::waitOneKey ( unsigned ms = 20 )

inline

Wait for only one ZX key or combination of keys to be pressed.

Return the pressed ZX keyboard. Update the PC keyboard, the ZX membrane and the ZX keyboard.

Definition at line 636 of file ZXEcosystem.h.

◆ waitForKeyChange()

Keyboard zxeco::ZXEco::waitForKeyChange	(	const Keyboard &	oldkb,
		std::string *	lastprstr = `nullptr`,
		unsigned	millis = `20`
	)

Wait for a change in the ZX keyboard that makes it different from OLDKB.

While waiting, the keyboard is sampled every MILLIS (continously if MILLIS == 0), thus it updates the PC keyboard, the ZX membrane and the ZX keyboard. Once a change is detected, a COPY of the ZX keyboard at that moment is returned and LASTPRSTR filled as in the keyboard() method.

Note: -Other methods can use the keyboard concurrently; no mutual exclusive use is done while sampling.

◆ forceCapsLock()

void zxeco::ZXEco::forceCapsLock ( bool state = true )

Forces a new state for the caps lock by simulating pressing CAPS+2.

Only updates ZX keyboard.

◆ setVolume()

void zxeco::ZXEco::setVolume ( double v )

Change sound volume (from 0.0 to 1.0) for future sounds.

0.0 is silence, while 1.0 is the maximum volume of the system.

Note: -Right after the construction of the ZXEco object, the volume is 0.0.

◆ volume()

double zxeco::ZXEco::volume ( void ) const

inlinenoexcept

Get the current volume of sound.

Definition at line 671 of file ZXEcosystem.h.

◆ play()

void zxeco::ZXEco::play	(	const Beep &	b,
		bool	async = `false`
	)

Play a beep.

Play the sound B and, if AYNC == FALSE and the current volume is > 0, wait to its completion. The sound will have a square wave, like in the ZX.

Note: -If B is created from a note or from some pitch, the behavior is the same as the BEEP command in the ZX, but you can also produce any portion of a square wave through the use of other constructors for the Beep class.

◆ flatInputCallbacks()

Screen::InputCallbacks zxeco::ZXEco::flatInputCallbacks ( void )

Construct and return the callbacks needed for input in the flat model.

Note: -The get keyboard callback routine does not flush the keyboard after changing, thus it maybe that there are remains of pressing keys after finishing the input.

See also: Screen::input.

Member Data Documentation

◆ kNullUserCode

const UserCode zxeco::ZXEco::kNullUserCode

static

A user code that does nothing.

Definition at line 85 of file ZXEcosystem.h.

◆ zxeco::ZXEco::RawGeometry

class zxeco::ZXEco::RawGeometry

Raw geometrical information about the window geometry of ZXEco objects.

Definition at line 89 of file ZXEcosystem.h.

Public Member Functions
	RawGeometry (void)=default
	Default constructor: invalid data.

	RawGeometry (const DoubleArea &sizes, unsigned bw, unsigned bh, unsigned sx, unsigned sy)
	Constructor from the information provided at ZXEco activation.

const DoubleArea &	basics (void) const noexcept
	Return a reference to the drawable area within the window. More...

const BorderRect &	topBorder (void) const noexcept
	Return a reference to the unscaled top border rectangle. More...

const BorderRect &	leftBorder (void) const noexcept
	Return a reference to the unscaled left border rectangle. More...

const BorderRect &	rightBorder (void) const noexcept
	Return a reference to the unscaled right border rectangle. More...

const BorderRect &	bottomBorder (void) const noexcept
	Return a reference to the unscaled bottom border rectangle. More...

unsigned	borderH (void) const noexcept
	Return the unscaled height of the top border zone in pixels. More...

unsigned	borderW (void) const noexcept
	Return the unscaled width of the left border zone in pixels. More...

unsigned	firstH (void) const noexcept
	Return the unscaled y-coord of the top-left pixel of the drawable. More...

unsigned	firstW (void) const noexcept
	Return the unscaled x-coord of the top-left pixel of the drawable. More...

unsigned	lastH (void) const noexcept
	Return the unscaled y-coord of the bottom-right pixel of drawable. More...

unsigned	lastW (void) const noexcept
	Return the unscaled w-coord of the bottom-right pixel of drawable. More...

unsigned	totH (void) const noexcept
	Return the unscaled height in pixels of border + drawable. More...

unsigned	totW (void) const noexcept
	Return the unscaled width in pixels of border + drawable. More...

unsigned	winH (void) const noexcept
	Scaled height in pixels of the desktop window of border + drawable. More...

unsigned	winW (void) const noexcept
	Scaled width in pixels of the desktop window of border + drawable. More...

unsigned	scaleX (void) const noexcept
	Scale factor in X. More...

unsigned	scaleY (void) const noexcept
	Scale factor in Y. More...

std::string	to_string (void) const
	Return a textual representation of the object.

Member Function Documentation

◆ basics()

const DoubleArea & zxeco::ZXEco::RawGeometry::basics ( void ) const

inlinenoexcept

Return a reference to the drawable area within the window.

Definition at line 102 of file ZXEcosystem.h.

◆ topBorder()

const BorderRect & zxeco::ZXEco::RawGeometry::topBorder ( void ) const

inlinenoexcept

Return a reference to the unscaled top border rectangle.

That rectangle covers the entire stripe of the top border.

Definition at line 105 of file ZXEcosystem.h.

◆ leftBorder()

const BorderRect & zxeco::ZXEco::RawGeometry::leftBorder ( void ) const

inlinenoexcept

Return a reference to the unscaled left border rectangle.

That rectangle covers the stripe of left border comprised by the drawable area.

Definition at line 108 of file ZXEcosystem.h.

◆ rightBorder()

const BorderRect & zxeco::ZXEco::RawGeometry::rightBorder ( void ) const

inlinenoexcept

Return a reference to the unscaled right border rectangle.

That rectangle covers the stripe of right border comprised by the drawable area.

Definition at line 112 of file ZXEcosystem.h.

◆ bottomBorder()

const BorderRect & zxeco::ZXEco::RawGeometry::bottomBorder ( void ) const

inlinenoexcept

Return a reference to the unscaled bottom border rectangle.

That rectangle covers the entire stripe of the bottom border.

Definition at line 116 of file ZXEcosystem.h.

◆ borderH()

unsigned zxeco::ZXEco::RawGeometry::borderH ( void ) const

inlinenoexcept

Return the unscaled height of the top border zone in pixels.

Definition at line 119 of file ZXEcosystem.h.

◆ borderW()

unsigned zxeco::ZXEco::RawGeometry::borderW ( void ) const

inlinenoexcept

Return the unscaled width of the left border zone in pixels.

Definition at line 122 of file ZXEcosystem.h.

◆ firstH()

unsigned zxeco::ZXEco::RawGeometry::firstH ( void ) const

inlinenoexcept

Return the unscaled y-coord of the top-left pixel of the drawable.

Definition at line 125 of file ZXEcosystem.h.

◆ firstW()

unsigned zxeco::ZXEco::RawGeometry::firstW ( void ) const

inlinenoexcept

Return the unscaled x-coord of the top-left pixel of the drawable.

Definition at line 128 of file ZXEcosystem.h.

◆ lastH()

unsigned zxeco::ZXEco::RawGeometry::lastH ( void ) const

inlinenoexcept

Return the unscaled y-coord of the bottom-right pixel of drawable.

Definition at line 131 of file ZXEcosystem.h.

◆ lastW()

unsigned zxeco::ZXEco::RawGeometry::lastW ( void ) const

inlinenoexcept

Return the unscaled w-coord of the bottom-right pixel of drawable.

Definition at line 134 of file ZXEcosystem.h.

◆ totH()

unsigned zxeco::ZXEco::RawGeometry::totH ( void ) const

inlinenoexcept

Return the unscaled height in pixels of border + drawable.

Definition at line 137 of file ZXEcosystem.h.

◆ totW()

unsigned zxeco::ZXEco::RawGeometry::totW ( void ) const

inlinenoexcept

Return the unscaled width in pixels of border + drawable.

Definition at line 140 of file ZXEcosystem.h.

◆ winH()

unsigned zxeco::ZXEco::RawGeometry::winH ( void ) const

inlinenoexcept

Scaled height in pixels of the desktop window of border + drawable.

Definition at line 143 of file ZXEcosystem.h.

◆ winW()

unsigned zxeco::ZXEco::RawGeometry::winW ( void ) const

inlinenoexcept

Scaled width in pixels of the desktop window of border + drawable.

Definition at line 146 of file ZXEcosystem.h.

◆ scaleX()

unsigned zxeco::ZXEco::RawGeometry::scaleX ( void ) const

inlinenoexcept

Scale factor in X.

Definition at line 149 of file ZXEcosystem.h.

◆ scaleY()

unsigned zxeco::ZXEco::RawGeometry::scaleY ( void ) const

inlinenoexcept

Scale factor in Y.

Definition at line 152 of file ZXEcosystem.h.

Description

Namespaces

Classes

Class Documentation

◆ zxeco::ZXEco

Static Public Member Functions

Public Member Functions

----------------— Types and consts ----------------—

Member Typedef Documentation

◆ LongTimeStat

◆ UserCode

Member Enumeration Documentation

◆ RefreshType

◆ RefreshMode

Member Function Documentation

◆ theZXEco()

◆ myDesktopInterface()

◆ activate()

◆ close()

◆ valid()

◆ windowTitle()

◆ startTime()

◆ rawGeometry()

◆ refreshCode()

◆ isInRefreshingCode()

◆ refresh()

◆ extractEvent()

◆ clearEvents()

◆ refreshType()

◆ refreshMode()

◆ refreshWhichEvents()

◆ refreshStats()

◆ resetRefreshStats()

◆ refreshingScreen()

◆ inkAndPaperSwappedByFlash()

◆ activateDecolourMode()

◆ deactivateDecolourMode()

◆ decolourModeActive()

◆ windowUpdate()

◆ windowRefresh()

◆ windowBorderUpdate()

◆ windowBorderRefresh()

◆ pointingStatus()

◆ desktopKeyPressed()

◆ membrane()

◆ keyboard()

◆ waitForKey()

◆ waitForNoKey()

◆ waitOneKey()

◆ waitForKeyChange()

◆ forceCapsLock()

◆ setVolume()

◆ volume()

◆ play()

◆ flatInputCallbacks()

Member Data Documentation

◆ kNullUserCode

◆ zxeco::ZXEco::RawGeometry

Public Member Functions

Member Function Documentation

◆ basics()

◆ topBorder()

◆ leftBorder()

◆ rightBorder()

◆ bottomBorder()

◆ borderH()

◆ borderW()

◆ firstH()

◆ firstW()

◆ lastH()

◆ lastW()

◆ totH()

◆ totW()

◆ winH()

◆ winW()

◆ scaleX()

◆ scaleY()