Description

Provides the ZX keyboard behavior.

NOTE:

-The classes in this module are not thread-safe.

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 Keyboard:

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

Classes
class	zxeco::KeyComb
	A combination of 2 keys. More...

class	zxeco::SetOfKeys
	A set of several keys, not repeated. More...

class	zxeco::Membrane
	The zx keyboard as a membrane. Useful for games and those sort of things. More...

class	zxeco::Membrane::KeyInRow
	Complete definition of a key in the membrane. More...

class	zxeco::Keyboard
	The ZX keyboard as it behaves (for typing) under the ZX operating system. More...

Class Documentation

◆ zxeco::KeyComb

class zxeco::KeyComb

A combination of 2 keys.

This represents 2 keys pressed simultaneously, one of them being a shift. It can be invalid (not all such combinations have sense).

Definition at line 130 of file ZXKeyboard.h.

Public Member Functions
	KeyComb (void) noexcept
	Default constructor: an invalid combination. More...

	KeyComb (Key shift, Key other)
	Constructor of a combination with the given SHIFT and OTHER keys. More...

virtual	~KeyComb (void)=default
	Destructor.

bool	valid (void) const noexcept
	Return TRUE if the combination is a valid one. More...

bool	is (Key shift, Key other) const
	Whether this combination is composed concretely of SHIFT + OTHER. More...

Key	shift (void) const
	Return the shift key if valid; raise an exception otherwise.

Key	other (void) const
	Return the other key if valid; raise an exception otherwise.

std::string	to_string (void) const noexcept
	Convert the combination to a string.

Constructor & Destructor Documentation

◆ KeyComb() [1/2]

zxeco::KeyComb::KeyComb ( void )

inlinenoexcept

Default constructor: an invalid combination.

Definition at line 134 of file ZXKeyboard.h.

◆ KeyComb() [2/2]

zxeco::KeyComb::KeyComb	(	Key	shift,
		Key	other
	)

Constructor of a combination with the given SHIFT and OTHER keys.

If the combination is invalid, this is set to invalid.

NOTE:

-If the combination is symbol (the shift) + caps (the other), it will
be transformed into caps (the shift) + symbol (the other).

Member Function Documentation

◆ valid()

bool zxeco::KeyComb::valid ( void ) const

inlinenoexcept

Return TRUE if the combination is a valid one.

Definition at line 149 of file ZXKeyboard.h.

◆ is()

bool zxeco::KeyComb::is	(	Key	shift,
		Key	other
	)		const

Whether this combination is composed concretely of SHIFT + OTHER.

If this object is valid and has that combination, return TRUE; if it is valid but represents another combination, return FALSE; otherwise, raise an exception.

◆ zxeco::SetOfKeys

class zxeco::SetOfKeys

A set of several keys, not repeated.

Definition at line 182 of file ZXKeyboard.h.

Inheritance diagram for zxeco::SetOfKeys:

[legend]

Collaboration diagram for zxeco::SetOfKeys:

[legend]

Public Types
typedef std::set< Key >	Base
	Just syntactic sugar. More...

Public Member Functions
	SetOfKeys (void)=default
	Default constructor: an empty set of keys.

	SetOfKeys (const KeyComb &kc)
	Constructor from a given combination, or empty if KC is invalid.

	SetOfKeys (const Base &b)
	Constructor from an initialized set of keys. More...

KeyComb	toKeyComb (void) const noexcept
	Conversion to a combination of keys. More...

std::string	to_string (void) const noexcept
	Return a string describing the set of keys.

Member Typedef Documentation

◆ Base

typedef std::set<Key> zxeco::SetOfKeys::Base

Just syntactic sugar.

Definition at line 186 of file ZXKeyboard.h.

Constructor & Destructor Documentation

◆ SetOfKeys()

zxeco::SetOfKeys::SetOfKeys ( const Base & b )

inline

Constructor from an initialized set of keys.

This allows us to use initializer lists for SetOfKeys, as long as they are a Base.

Definition at line 194 of file ZXKeyboard.h.

Member Function Documentation

◆ toKeyComb()

KeyComb zxeco::SetOfKeys::toKeyComb ( void ) const

noexcept

Conversion to a combination of keys.

Convert this set of keys into a KeyComb if they correspond to a valid one and no additional keys are present; otherwise, convert it to an invalid combination.

◆ zxeco::Membrane

class zxeco::Membrane

The zx keyboard as a membrane. Useful for games and those sort of things.

Definition at line 218 of file ZXKeyboard.h.

Public Types
enum	HalfRow { CAPS_V = 0 , A_G , Q_T , ONE_FIVE , ZERO_SIX , P_Y , ENTER_H , SPC_B , NUMHALFROWS }
	Half-rows that form the membrane of the zx, in the same order as ZX port. More...

enum	RowMask : unsigned char { MK1 = 1 , MK2 = 1 << 1 , MK3 = 1 << 2 , MK4 = 1 << 3 , MK5 = 1 << 4 }
	Constants that are useful to select a key within a half row. More...

Static Public Attributes
static constexpr unsigned char	KEYSPERROW = 5
	Number of keys per half row. More...

static constexpr uint8_t	MASKKEYS = 0x1F
	Constant that serves to mask out non-keys bits from a half row status. More...

Public Attributes
unsigned char	krows [NUMHALFROWS]
	The membrane status. More...

Public Member Functions
-------------— Constructors ----------------—
	Membrane (void) noexcept
	Default constructor: the entire membrane is set to 0. More...

virtual	~Membrane (void)=default
	Destructor.

-------------— Membrane methods ---------------—
void	clear (void) noexcept
	Clear all keys pressed. More...

unsigned char	numKeysPressed (void) const noexcept
	Get number of keys pressed. More...

bool	someKeyUnpressed (const Membrane &oth) const noexcept
	Check if this has keys of OTH unpressed. More...

bool	someKeyPressed (const Membrane &oth) const noexcept
	Check if this has keys additionaly pressed to the ones of OTH. More...

bool	someNewKeyPressed (const Membrane &oth) const noexcept
	Check if OTH keys pressed that are not pressed in this. More...

-------------— Key-based methods ---------------—
void	setKeyState (Key k, bool pressed=true)
	Change the press state of K to PRESSED. Exception if K is invalid.

void	setKeyState (const SetOfKeys &soks, bool pressed=true)
	Change the press state of the entire set SOKS to PRESSED.

void	setKeyState (const KeyComb &kc, bool pressed=true)
	Change the press state of the combination KC to PRESSED.

bool	keyState (Key k) const noexcept
	Return the state of key K in the membrane. FALSE if K is invalid.

SetOfKeys	keysPressed (void) const noexcept
	Return the set of keys that are pressed currently in the membrane.

KeyComb	combinationPressed (void) const noexcept
	Get the combination that is currently pressed in the membrane, if any. More...

-------------— Logical comparisons -------------—
Return TRUE(FALSE) if krows are not in the same (different) state in OTH and in THIS.
bool	operator!= (const Membrane &oth) const noexcept

bool	operator== (const Membrane &oth) const noexcept

-------------— Logical operations -------------—
(Unused bits will be set to 0 in the results)
Membrane &	operator^= (const Membrane &oth) noexcept
	XOR + assignment.

Membrane &	operator&= (const Membrane &oth) noexcept
	< XOR. More...

Membrane &	operator\|= (const Membrane &oth) noexcept
	OR + assignment.

Membrane	operator~ (void) noexcept
	NOT.

std::string	to_string (void) const noexcept
	Return a string representing the Membrane.

Membrane	operator^ (Membrane lhs, const Membrane &rhs) noexcept
	XOR + assignment. More...

Membrane	operator& (Membrane lhs, const Membrane &rhs) noexcept
	AND. More...

Membrane	operator\| (Membrane lhs, const Membrane &rhs) noexcept
	OR. More...

Member Enumeration Documentation

◆ HalfRow

enum zxeco::Membrane::HalfRow

Half-rows that form the membrane of the zx, in the same order as ZX port.

Enumerator
CAPS_V	Keys (outer to inner): CAPSSHIFT, Z, X, C, V.
A_G	Keys: A, S, D, F, G.
Q_T	Keys: Q, W, E, R, T.
ONE_FIVE	Keys: 1, 2, 3, 4, 5.
ZERO_SIX	Keys: 0, 9, 8, 7, 6.
P_Y	Keys: P, O, I, U, Y.
ENTER_H	Keys: ENTER, L, K, J, H.
SPC_B	Keys: SPACE, SYMBOLSHIFT, M, N, B.

Definition at line 226 of file ZXKeyboard.h.

◆ RowMask

enum zxeco::Membrane::RowMask : unsigned char

Constants that are useful to select a key within a half row.

Enumerator
MK1	First key (outer) in a HalfRow.
MK2	Second key.
MK3	Third key.
MK4	Fourth key.
MK5	Fifth key (inner).

Definition at line 242 of file ZXKeyboard.h.

Constructor & Destructor Documentation

◆ Membrane()

zxeco::Membrane::Membrane ( void )

inlinenoexcept

Default constructor: the entire membrane is set to 0.

Definition at line 297 of file ZXKeyboard.h.

Member Function Documentation

◆ clear()

void zxeco::Membrane::clear ( void )

inlinenoexcept

Clear all keys pressed.

Definition at line 309 of file ZXKeyboard.h.

◆ numKeysPressed()

unsigned char zxeco::Membrane::numKeysPressed ( void ) const

noexcept

Get number of keys pressed.

Scan the krows attribute to calculate the number of keys currently pressed in the membrane.

◆ someKeyUnpressed()

bool zxeco::Membrane::someKeyUnpressed ( const Membrane & oth ) const

noexcept

Check if this has keys of OTH unpressed.

Return TRUE if OTH's krows is the same as this' but with some key(s) additionally unpressed.

◆ someKeyPressed()

bool zxeco::Membrane::someKeyPressed ( const Membrane & oth ) const

noexcept

Check if this has keys additionaly pressed to the ones of OTH.

Return TRUE if OTH's krows is the same as this' but with some key(s) additionally pressed.

◆ someNewKeyPressed()

bool zxeco::Membrane::someNewKeyPressed ( const Membrane & oth ) const

noexcept

Check if OTH keys pressed that are not pressed in this.

Return TRUE if OTH's krows has some key pressed that is not pressed in this' krows. Notice that OTH's krows may have keys unpressed that are pressed in this.

◆ combinationPressed()

KeyComb zxeco::Membrane::combinationPressed ( void ) const

noexcept

Get the combination that is currently pressed in the membrane, if any.

Scan the krows attribute to detect the combination currently pressed in the map (or an invalid one if none is found or some is found but with additional keys pressed).

◆ operator==()

bool zxeco::Membrane::operator== ( const Membrane & oth ) const

inlinenoexcept

Definition at line 366 of file ZXKeyboard.h.

◆ operator&=()

Membrane & zxeco::Membrane::operator&= ( const Membrane & oth )

noexcept

< XOR.

AND + assignment.

Friends And Related Function Documentation

◆ operator^

Membrane operator^	(	Membrane	lhs,
		const Membrane &	rhs
	)

friend

XOR + assignment.

Definition at line 380 of file ZXKeyboard.h.

◆ operator&

Membrane operator&	(	Membrane	lhs,
		const Membrane &	rhs
	)

friend

AND.

Definition at line 392 of file ZXKeyboard.h.

◆ operator|

Membrane operator\|	(	Membrane	lhs,
		const Membrane &	rhs
	)

friend

OR.

Definition at line 399 of file ZXKeyboard.h.

Member Data Documentation

◆ KEYSPERROW

constexpr unsigned char zxeco::Membrane::KEYSPERROW = 5

staticconstexpr

Number of keys per half row.

Definition at line 238 of file ZXKeyboard.h.

◆ MASKKEYS

constexpr uint8_t zxeco::Membrane::MASKKEYS = 0x1F

staticconstexpr

Constant that serves to mask out non-keys bits from a half row status.

Apply this and-mask to the status of a half row to clean unused bits.

Definition at line 252 of file ZXKeyboard.h.

◆ krows

unsigned char zxeco::Membrane::krows[NUMHALFROWS]

The membrane status.

One byte per half-row and per key (0->unpressed, 1->pressed). This must be externally filled/updated. Its layout is exactly the same as in the original ZX but with the pressed/unpressed state inverted.

Definition at line 290 of file ZXKeyboard.h.

◆ zxeco::Membrane::KeyInRow

class zxeco::Membrane::KeyInRow

Complete definition of a key in the membrane.

It consists of a half row plus the mask to get the key state. You can reach the two elements of the pair through .first and .second vars.

Definition at line 258 of file ZXKeyboard.h.

Inheritance diagram for zxeco::Membrane::KeyInRow:

[legend]

Collaboration diagram for zxeco::Membrane::KeyInRow:

[legend]

Public Types
typedef std::pair< HalfRow, RowMask >	Base
	Just sugar. More...

Static Public Member Functions
static void	checkPair (const Base &b)
	Throw an exception if B contains an invalid half row or mask.

Public Member Functions
	KeyInRow (HalfRow h=CAPS_V, RowMask m=MK1)
	Default constructor, and from row and mask. Exception if invalid.

	KeyInRow (Key k)
	Constructor from a key id. Exception if K is invalid.

	KeyInRow (const Base &b)
	Constructor from base object. Exception if invalid. More...

virtual	~KeyInRow (void)=default
	Destructor.

	operator Key (void) const
	Convert this pair to a key identifier. Exception if invalid.

Member Typedef Documentation

◆ Base

typedef std::pair<HalfRow,RowMask> zxeco::Membrane::KeyInRow::Base

Just sugar.

Definition at line 262 of file ZXKeyboard.h.

Constructor & Destructor Documentation

◆ KeyInRow()

zxeco::Membrane::KeyInRow::KeyInRow ( const Base & b )

inline

Constructor from base object. Exception if invalid.

Definition at line 271 of file ZXKeyboard.h.

◆ zxeco::Keyboard

class zxeco::Keyboard

The ZX keyboard as it behaves (for typing) under the ZX operating system.

It is a view built upon Membrane, but this keyboard, unlike the Membrane, has history. Its current state depends on successive instantaneous Membranes that are fed into it at the pace the user of this class sets (for instance, changing current state (E,C,K,...) depends on the previous state, not only on the keys pressed now).

Definition at line 426 of file ZXKeyboard.h.

Collaboration diagram for zxeco::Keyboard:

[legend]

Public Types
enum class	Mode { NORMAL = 0 , EXTENDED , GRAPHICS , NUMMODES }
	The keyboard modes recognized by the zx operating system. More...

Static Public Member Functions
static uint8_t	keyToASCII (Mode km, bool capslock, Key shift, Key k)
	Return the ASCII code correponding to the given key pressing SHIFT + K. More...

Public Member Functions
-------------— Constructors --------------—
(Leave other constructors by default)
	Keyboard (const Membrane &mem0=Membrane{})
	Default constructor. No key pressed, no capslock, NORMAL mode. More...

virtual	~Keyboard (void)=default
	Destructor.

-------------— Setter methods --------------—
void	reset (void)
	Reset the keyboard to its initial state: key pressed, NO_KEY.

void	setKeyRepetitions (std::chrono::steady_clock::duration repdel=std::chrono::milliseconds{700}, std::chrono::steady_clock::duration repper=std::chrono::milliseconds{100}) noexcept
	Set key repetition parameters. More...

bool	newMembrane (const Membrane &newmembrane, std::string *lastprstr=nullptr)
	Update state of the keyboard from the given Membrane. More...

-------------— Getter methods --------------—
void	keyRepetitions (std::chrono::steady_clock::duration &repdel, std::chrono::steady_clock::duration &repper) const noexcept
	Fill both arguments with the current repetition parameters. More...

Mode	mode (void) const noexcept
	Return the current keyboard mode. More...

bool	capsLock (void) const noexcept
	Return the current capslock state. More...

std::chrono::steady_clock::time_point	lastEffectiveChange (void) const noexcept
	Get the time of the last change that was recognized by the keyboard. More...

const Membrane &	lastMembrane (void) const noexcept
	Return the last membrane that this Keyboard is aware of. More...

Key	lastKey (void) const noexcept
	Get the key pressed in the last membrane fed into this keyboard. More...

KeyComb	lastKeyComb (void) const noexcept
	Get the combination of keys pressed in the last membrane fed into this. More...

bool	anyKey (void) const noexcept
	Return TRUE if a key or combination of keys were pressed in last membr. More...

-------------— Miscellaneous methods --------------—
std::string	to_string (void) const noexcept
	Return a string representing the whole keyboard state.

Member Enumeration Documentation

◆ Mode

enum class zxeco::Keyboard::Mode

strong

The keyboard modes recognized by the zx operating system.

Enumerator
NORMAL	Normal mode (C or L).
EXTENDED	Extended mode (E).
GRAPHICS	Graphics mode (G).

Definition at line 434 of file ZXKeyboard.h.

Constructor & Destructor Documentation

◆ Keyboard()

zxeco::Keyboard::Keyboard ( const Membrane & mem0 = Membrane{} )

inline

Default constructor. No key pressed, no capslock, NORMAL mode.

MEM0 becomes the initial state of the keys.

Definition at line 451 of file ZXKeyboard.h.

Member Function Documentation

◆ keyToASCII()

static uint8_t zxeco::Keyboard::keyToASCII	(	Mode	km,
		bool	capslock,
		Key	shift,
		Key	k
	)

static

Return the ASCII code correponding to the given key pressing SHIFT + K.

Assume keyboard state is mode = KM, capslock = CAPSLOCK. Return 0 if there is no ascii code for that pressing.

◆ setKeyRepetitions()

void zxeco::Keyboard::setKeyRepetitions	(	std::chrono::steady_clock::duration	repdel = `std::chrono::milliseconds{700}`,
		std::chrono::steady_clock::duration	repper = `std::chrono::milliseconds{100}`
	)

inlinenoexcept

Set key repetition parameters.

Change repetition times. REPDEL is the delay from the time when a key is first pressed to the time when it should begin to repeat automatically; REPPER is the period of those repetitions. Their default values are the ones of the original ZX after start-up.

Definition at line 466 of file ZXKeyboard.h.

◆ newMembrane()

bool zxeco::Keyboard::newMembrane	(	const Membrane &	newmembrane,
		std::string *	lastprstr = `nullptr`
	)

Update state of the keyboard from the given Membrane.

Update state of the keyboard (mode, capslock, etc.) based on the new membrane state given by NEWMEMBRANE, that is assumed to have been read right now (i.e., there have been no changes in the membrane since the last call to this method). If more than two simultaneous changes (i.e., more than two keys simultaneously pressed) are detected in the membrane, return FALSE and do not update the state, since a too slow sampling of the keyboard is assumed. The lastKey() and lastKeyComb() are updated with the key pressed in this new membrane. If LASTPRSTR != nullptr, fill it in with the string that corresponds to the last pressed key or keycomb, according to the mode in which the keyboard was when they were pressed.

◆ keyRepetitions()

void zxeco::Keyboard::keyRepetitions	(	std::chrono::steady_clock::duration &	repdel,
		std::chrono::steady_clock::duration &	repper
	)		const

inlinenoexcept

Fill both arguments with the current repetition parameters.

Definition at line 499 of file ZXKeyboard.h.

◆ mode()

Mode zxeco::Keyboard::mode ( void ) const

inlinenoexcept

Return the current keyboard mode.

Definition at line 505 of file ZXKeyboard.h.

◆ capsLock()

bool zxeco::Keyboard::capsLock ( void ) const

inlinenoexcept

Return the current capslock state.

Definition at line 508 of file ZXKeyboard.h.

◆ lastEffectiveChange()

std::chrono::steady_clock::time_point zxeco::Keyboard::lastEffectiveChange ( void ) const

inlinenoexcept

Get the time of the last change that was recognized by the keyboard.

Return a copy of the last time were an effective change in the state of some key or of the keyboard state/capslock was recorded, or an undefined value if no change has occurred yet.

Definition at line 511 of file ZXKeyboard.h.

◆ lastMembrane()

const Membrane & zxeco::Keyboard::lastMembrane ( void ) const

inlinenoexcept

Return the last membrane that this Keyboard is aware of.

Definition at line 518 of file ZXKeyboard.h.

◆ lastKey()

Key zxeco::Keyboard::lastKey ( void ) const

inlinenoexcept

Get the key pressed in the last membrane fed into this keyboard.

If the latest event was pressing a single key, return it; otherwise, return Key::NO_KEY. This and the next methods are exclusive: if one of them provides a positive answer, the other one does not.

Definition at line 522 of file ZXKeyboard.h.

◆ lastKeyComb()

KeyComb zxeco::Keyboard::lastKeyComb ( void ) const

inlinenoexcept

Get the combination of keys pressed in the last membrane fed into this.

If the last event was pressing a key combination, return it; otherwise, return an invalid one. This and the previous methods are exclusive: if one of them provides a positive answer, the other one does not.

Definition at line 528 of file ZXKeyboard.h.

◆ anyKey()

bool zxeco::Keyboard::anyKey ( void ) const

inlinenoexcept

Return TRUE if a key or combination of keys were pressed in last membr.

Definition at line 535 of file ZXKeyboard.h.

Member Data Documentation

◆ keyorkeycomb

bool zxeco::Keyboard::keyorkeycomb

Definition at line 553 of file ZXKeyboard.h.

◆ key

Key zxeco::Keyboard::key

Definition at line 554 of file ZXKeyboard.h.

◆ keycomb

KeyComb zxeco::Keyboard::keycomb

Definition at line 555 of file ZXKeyboard.h.

Description

Namespaces

Classes

Class Documentation

◆ zxeco::KeyComb

Public Member Functions

Constructor & Destructor Documentation

◆ KeyComb() [1/2]

◆ KeyComb() [2/2]

Member Function Documentation

◆ valid()

◆ is()

◆ zxeco::SetOfKeys

Public Types

Public Member Functions

Member Typedef Documentation

◆ Base

Constructor & Destructor Documentation

◆ SetOfKeys()

Member Function Documentation

◆ toKeyComb()

◆ zxeco::Membrane

Public Types

Static Public Attributes

Public Attributes

Public Member Functions

-------------— Logical operations -------------—

Member Enumeration Documentation

◆ HalfRow

◆ RowMask

Constructor & Destructor Documentation

◆ Membrane()

Member Function Documentation

◆ clear()

◆ numKeysPressed()

◆ someKeyUnpressed()

◆ someKeyPressed()

◆ someNewKeyPressed()

◆ combinationPressed()

◆ operator==()

◆ operator&=()

Friends And Related Function Documentation

◆ operator^

◆ operator&

◆ operator|

Member Data Documentation

◆ KEYSPERROW

◆ MASKKEYS

◆ krows

◆ zxeco::Membrane::KeyInRow

Public Types

Static Public Member Functions

Public Member Functions

Member Typedef Documentation

◆ Base

Constructor & Destructor Documentation

◆ KeyInRow()

◆ zxeco::Keyboard

Public Types

Static Public Member Functions

Public Member Functions

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ Keyboard()

Member Function Documentation

◆ keyToASCII()

◆ setKeyRepetitions()

◆ newMembrane()

◆ keyRepetitions()

◆ mode()

◆ capsLock()

◆ lastEffectiveChange()

◆ lastMembrane()

◆ lastKey()

◆ lastKeyComb()

◆ anyKey()

Member Data Documentation

◆ keyorkeycomb

◆ key