Description

     Abstract interface with a desktop where
     windows can be opened to draw graphics on them,
     mouse can be read, keyboard can be read and simple
     sounds can be made. This interface must be instantiated with
     some library that provides concrete support for a given
     desktop, such as SDL2 (see the \ref DesktopSDL2 module).

NOTE:

     -Derived classes might be non-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 Desktop Interface:

Classes
class	DesktopInterface
	Interface with the functionality that a desktop must provide. More...

class	DesktopInterface::KeypressMap
	A map of the keyboard, as seen by the desktop. More...

struct	DesktopInterface::SoundPlayerParms
	Main parameters of the sound player. More...

class	PalettizedWindow
	A palettized window on the desktop. More...

struct	PalettizedWindow::Rectangle
	A rectangle on a palettized window. More...

struct	PalettizedWindow::Event
	Events that the window can receive from its desktop environment. More...

class	PalettizedWindow::Event::IDSet
	A compact set of IDs. More...

class	PalettizedWindow::ListOfEvents
	List of events that occurred in the window, in chronological order. More...

class	PalettizedWindow::Cursor
	To refer to pixels in the drawable area of the window. More...

class	PalettizedWindow::CursorCheck
	Cursor to refer to pixels that includes checking code. More...

Class Documentation

◆ DesktopInterface

class DesktopInterface

Interface with the functionality that a desktop must provide.

This interface specifies support for keyboard, reading graphical files, creating palettized windows, and playing sounds. Derived classes may provide different implementations for this, but all must have in common that they are singleton: only one desktop interface can exist in a given program.

Definition at line 61 of file DesktopInterface.h.

Inheritance diagram for DesktopInterface:

[legend]

Collaboration diagram for DesktopInterface:

[legend]

Public Types
enum	KeyID { K_ESC =0 , K_F1 , K_F2 , K_F3 , K_F4 , K_F5 , K_F6 , K_F7 , K_F8 , K_F9 , K_F10 , K_F11 , K_F12 , K_1 , K_2 , K_3 , K_4 , K_5 , K_6 , K_7 , K_8 , K_9 , K_0 , K_BACK , K_DEL , K_TAB , K_BEGIN , K_END , K_PGUP , K_PGDOWN , K_Q , K_W , K_E , K_R , K_T , K_Y , K_U , K_I , K_O , K_P , K_ENTER , K_CAPSLOCK , K_A , K_S , K_D , K_F , K_G , K_H , K_J , K_K , K_L , K_CAPSLEFT , K_Z , K_X , K_C , K_V , K_B , K_N , K_M , K_COMMA , K_PERIOD , K_CAPSRIGHT , K_CTRLLEFT , K_ALTLEFT , K_SPACE , K_ALTRIGHT , K_CTRLRIGHT , K_LEFT , K_DOWN , K_UP , K_RIGHT , K_MINUS , K_PLUS , K_DIV , K_MULT , K_BSLASH , K_UNDERS , K_SQUBRO , K_SQUBRC , K_CURBRO , K_CURBRC , K_EXCL , K_DQUOTE , K_AT , K_SHARP , K_DOLLAR , K_PERC , K_AMPER , K_PARO , K_PARC , K_EQUAL , K_QUEST , K_VERT , K_CIRC , K_APOST , K_LESS , K_GREAT , K_SEMIC , K_COLON , NUM_OF_KEY_IDS }
	IDs for the most common keys in a keyboard. More...

typedef std::function< double(double t, uint64_t i, unsigned l, unsigned pos)>	SoundMonoProducer
	A routine to produce a mono-channel sound wave. More...

Static Public Member Functions
static bool	keyIsNumber (KeyID kid) noexcept
	< Return TRUE if the given KEY is a number. More...

static bool	keyIsLetter (KeyID kid) noexcept
	< Return TRUE if the given KEY is a letter. More...

static bool	keyIsFunction (KeyID kid) noexcept
	< Return TRUE if the given KEY is a function key. More...

static bool	keyIsForMotion (KeyID kid) noexcept
	< Return TRUE if the key can be used for moving things on the screen. More...

Static Public Attributes
static const std::vector< std::string >	KeyNames
	Key names. More...

static const SoundMonoProducer	SilenceMonoProducer
	Pre-defined sound producing routine that generates silence all time. More...

Public Member Functions
----------------------— Constructors ---------------------—
A desktop interface cannot be constructed publicly, cause a program can only have one -singleton-. Cannot be copied/moved for the same reason. The sound must be initially paused after creation of the singleton
virtual	~DesktopInterface (void)=default

	DesktopInterface (const DesktopInterface &)=delete

DesktopInterface &	operator= (const DesktopInterface &)=delete

	DesktopInterface (const DesktopInterface &&)=delete

DesktopInterface &	operator= (const DesktopInterface &&)=delete

----------------------— Image files methods --------------—
virtual RGBImage	readPNGImageFile (const std::string &filepath)=0
	Must read the PNG image file with path FILEPATH and return an RGBImage. More...

virtual void	writePNGImageFile (const RGBImage &img, const std::string &filepath)=0
	Must write the data of IMG into the file FILEPATH in PNG format. More...

----------------------— Graphics methods ----------------—
virtual void	getDesktopResolution (unsigned &w, unsigned &h)=0
	Get the resolution of the display in pixels. More...

virtual PalettizedWindow *	createWindow (const std::string &title, unsigned dimw, unsigned dimh, unsigned scalex, unsigned scaley)=0
	Factory: create a new window that supports palettized pixels. More...

----------------------— Sound methods ----------------—
const SoundPlayerParms &	playerParms (void) const noexcept
	< Must return the current parameters of the sound player system. More...

virtual void	playSound (double secs, const SoundMonoProducer &waveprod, bool async)=0
	Play a sound. More...

virtual void	pausePlaying (void)=0
	Pause the current playing, if any, and play just silence. More...

virtual void	resumePlaying (void)=0
	Resume a previously paused playing. More...

virtual bool	playingPaused (void)=0
	Return whether there is a paused playing or not. More...

virtual bool	soundPlaying (void) const noexcept=0
	Whether there is a sound being played or not. More...

virtual void	nextSoundPlayingTime (double &t) noexcept=0
	Fill T with the next time the user's callback will be called. More...

virtual const SoundMonoProducer &	lastSoundProducer (void) const =0
	Get the routine that is currently producing sounds. More...

virtual double	lastSoundDuration (void) const noexcept=0
	Get the duration of the last sound being played. More...

-----------------— Keyboard methods ----------------------—
virtual void	enableTextEvents (void)=0
	Must enable K_TEXT events from now on to the active window in desktop. More...

virtual void	disableTextEvents (void)=0
	Must disable K_TEXT events from now on to the active window in desktop. More...

virtual bool	textEventsEnabled (void) const =0
	Must return the current enabled state of K_TEXT events. More...

-----------------— Clipboard methods ---------------------—
virtual std::string	copyFromClipboard (void) const =0
	Must return a copy of the text existing in the clipboard, if any. More...

virtual void	copyToClipboard (const std::string &txt) const =0
	Must copy TXT, if not empty, to the clipboard. More...

Protected Member Functions
	DesktopInterface (const SoundPlayerParms &spps)

Protected Attributes
SoundPlayerParms	playerparms_

Member Typedef Documentation

◆ SoundMonoProducer

typedef std::function<double (double t, uint64_t i, unsigned l, unsigned pos)> DesktopInterface::SoundMonoProducer

A routine to produce a mono-channel sound wave.

It must return a value in [-1.0,+1.0] that corresponds to the desired amplitude for the wave at time T (seconds). It will be called for a sequence of times until a given call to playSound() is finished.

Parameters

t	is the time index (seconds, from 0.0) of the requested value within the seq. corresponding to the whole sound.
i	is the sequence index (from 0) of the requested value within the whole sound.
l	is the number of requested values that will be buffered before sending them to the audio system (less than the number of values to cover the whole sound). This value will be 0 if no value is buffered.
pos	is the index (from 0) in the buffered values of the requested value. This value will always be 0 if no value is buffered.

Definition at line 133 of file DesktopInterface.h.

Member Enumeration Documentation

◆ KeyID

enum DesktopInterface::KeyID

IDs for the most common keys in a keyboard.

Some of them may not be recognized in a given keyboard layout and thus can be unusable; in particular, the desktop only recognizes those that have a direct physical key that has not to be combined with any other pressing key.

Definition at line 72 of file DesktopInterface.h.

Constructor & Destructor Documentation

◆ DesktopInterface()

DesktopInterface::DesktopInterface ( const SoundPlayerParms & spps )

inlineprotected

Definition at line 308 of file DesktopInterface.h.

Member Function Documentation

◆ keyIsNumber()

static bool DesktopInterface::keyIsNumber ( KeyID kid )

inlinestaticnoexcept

< Return TRUE if the given KEY is a number.

Definition at line 109 of file DesktopInterface.h.

◆ keyIsLetter()

static bool DesktopInterface::keyIsLetter ( KeyID kid )

inlinestaticnoexcept

< Return TRUE if the given KEY is a letter.

Definition at line 113 of file DesktopInterface.h.

◆ keyIsFunction()

static bool DesktopInterface::keyIsFunction ( KeyID kid )

inlinestaticnoexcept

< Return TRUE if the given KEY is a function key.

Definition at line 119 of file DesktopInterface.h.

◆ keyIsForMotion()

static bool DesktopInterface::keyIsForMotion ( KeyID kid )

inlinestaticnoexcept

< Return TRUE if the key can be used for moving things on the screen.

Definition at line 123 of file DesktopInterface.h.

◆ readPNGImageFile()

virtual RGBImage DesktopInterface::readPNGImageFile ( const std::string & filepath )

pure virtual

Must read the PNG image file with path FILEPATH and return an RGBImage.

May throw exceptions.

Implemented in DesktopSDL2.

◆ writePNGImageFile()

virtual void DesktopInterface::writePNGImageFile	(	const RGBImage &	img,
		const std::string &	filepath
	)

pure virtual

Must write the data of IMG into the file FILEPATH in PNG format.

May throw exceptions.

Implemented in DesktopSDL2.

◆ getDesktopResolution()

virtual void DesktopInterface::getDesktopResolution	(	unsigned &	w,
		unsigned &	h
	)

pure virtual

Get the resolution of the display in pixels.

Must fill W and H with the resolution in pixels of the current graphic mode of the desktop.

Implemented in DesktopSDL2.

◆ createWindow()

virtual PalettizedWindow * DesktopInterface::createWindow	(	const std::string &	title,
		unsigned	dimw,
		unsigned	dimh,
		unsigned	scalex,
		unsigned	scaley
	)

pure virtual

Factory: create a new window that supports palettized pixels.

Implemented in DesktopSDL2.

◆ playerParms()

const SoundPlayerParms & DesktopInterface::playerParms ( void ) const

inlinenoexcept

< Must return the current parameters of the sound player system.

Definition at line 221 of file DesktopInterface.h.

◆ playSound()

virtual void DesktopInterface::playSound	(	double	secs,
		const SoundMonoProducer &	waveprod,
		bool	async
	)

pure virtual

Play a sound.

Must dismiss the current production of sound and start producing a new one for a duration of SECS (forever if SECS == 0.0). During that duration, the routine WAVEPROD will be called several times to produce the value of the (mono-channel) wave at time T, being T==0.0 the beginning of the production time, and being T in seconds. If ASYNC == TRUE, set the audio system to callback WAVEPROD and then return. Otherwise, set the audio system but do not return until the last call to WAVEPROD is finished.

Implemented in DesktopSDL2.

◆ pausePlaying()

virtual void DesktopInterface::pausePlaying ( void )

pure virtual

Pause the current playing, if any, and play just silence.

Several calls to this method just pause once. If nothing is being played, this does nothing. After a call to playSound() in non-async mode, the playing is paused; this has sense only in async mode.

Implemented in DesktopSDL2.

◆ resumePlaying()

virtual void DesktopInterface::resumePlaying ( void )

pure virtual

Resume a previously paused playing.

Several calls to this method just resume once.

Implemented in DesktopSDL2.

◆ playingPaused()

virtual bool DesktopInterface::playingPaused ( void )

pure virtual

Return whether there is a paused playing or not.

Implemented in DesktopSDL2.

◆ soundPlaying()

virtual bool DesktopInterface::soundPlaying ( void ) const

pure virtualnoexcept

Whether there is a sound being played or not.

Must return TRUE if there is a sound commanded by the user being played now, or FALSE otherwise.

Implemented in DesktopSDL2.

◆ nextSoundPlayingTime()

virtual void DesktopInterface::nextSoundPlayingTime ( double & t )

pure virtualnoexcept

Fill T with the next time the user's callback will be called.

Must fill T with the next time (w.r.t. the current value of T) where a future playing of some sound will call the wave producer routine. This method can serve for pre-calculating sounds before playing them. If T<0.0, it will be filled with the first time, i.e., 0.0.

Implemented in DesktopSDL2.

◆ lastSoundProducer()

virtual const SoundMonoProducer & DesktopInterface::lastSoundProducer ( void ) const

pure virtual

Get the routine that is currently producing sounds.

Must return a reference to the routine that is producing sounds now, or raise an exception if there is none.

Implemented in DesktopSDL2.

◆ lastSoundDuration()

virtual double DesktopInterface::lastSoundDuration ( void ) const

pure virtualnoexcept

Get the duration of the last sound being played.

Must return the duration of the last sound being played. Undefined if nothing is playing yet.

Implemented in DesktopSDL2.

◆ enableTextEvents()

virtual void DesktopInterface::enableTextEvents ( void )

pure virtual

Must enable K_TEXT events from now on to the active window in desktop.

Implemented in DesktopSDL2.

◆ disableTextEvents()

virtual void DesktopInterface::disableTextEvents ( void )

pure virtual

Must disable K_TEXT events from now on to the active window in desktop.

Implemented in DesktopSDL2.

◆ textEventsEnabled()

virtual bool DesktopInterface::textEventsEnabled ( void ) const

pure virtual

Must return the current enabled state of K_TEXT events.

Implemented in DesktopSDL2.

◆ copyFromClipboard()

virtual std::string DesktopInterface::copyFromClipboard ( void ) const

pure virtual

Must return a copy of the text existing in the clipboard, if any.

Throw if no clipboard or any error.

Implemented in DesktopSDL2.

◆ copyToClipboard()

virtual void DesktopInterface::copyToClipboard ( const std::string & txt ) const

pure virtual

Must copy TXT, if not empty, to the clipboard.

If there was a previous text content in the clipboard, it is deleted. Throw if no clipboard or any error.

Implemented in DesktopSDL2.

Member Data Documentation

◆ KeyNames

const std::vector<std::string> DesktopInterface::KeyNames

static

Key names.

Definition at line 106 of file DesktopInterface.h.

◆ SilenceMonoProducer

const SoundMonoProducer DesktopInterface::SilenceMonoProducer

static

Pre-defined sound producing routine that generates silence all time.

Definition at line 149 of file DesktopInterface.h.

◆ playerparms_

SoundPlayerParms DesktopInterface::playerparms_

protected

Definition at line 306 of file DesktopInterface.h.

◆ DesktopInterface::KeypressMap

class DesktopInterface::KeypressMap

A map of the keyboard, as seen by the desktop.

Definition at line 89 of file DesktopInterface.h.

Inheritance diagram for DesktopInterface::KeypressMap:

[legend]

Collaboration diagram for DesktopInterface::KeypressMap:

[legend]

Public Member Functions
	KeypressMap (void)
	Default constructor: a map with one entry per KeyID, all unpressed.

virtual	~KeypressMap (void)=default
	Destructor.

bool	anyKeyPressed (void) const
	Return TRUE if any key appears pressed in the map.

◆ DesktopInterface::SoundPlayerParms

struct DesktopInterface::SoundPlayerParms

Main parameters of the sound player.

Definition at line 153 of file DesktopInterface.h.

Public Attributes
double	sampling_period
	In secs, between a sound value and the next. More...

unsigned	sample_size
	Number of samples that are buffered. More...

Public Member Functions
	SoundPlayerParms (void)
	Default constructor with default parameters. More...

	SoundPlayerParms (double sper, unsigned ss)
	Specific constructor. More...

void	check (void) const
	Throw if the parameters are invalid.

Constructor & Destructor Documentation

◆ SoundPlayerParms() [1/2]

DesktopInterface::SoundPlayerParms::SoundPlayerParms ( void )

inline

Default constructor with default parameters.

Definition at line 161 of file DesktopInterface.h.

◆ SoundPlayerParms() [2/2]

DesktopInterface::SoundPlayerParms::SoundPlayerParms	(	double	sper,
		unsigned	ss
	)

inline

Specific constructor.

Definition at line 164 of file DesktopInterface.h.

Member Data Documentation

◆ sampling_period

double DesktopInterface::SoundPlayerParms::sampling_period

In secs, between a sound value and the next.

Definition at line 155 of file DesktopInterface.h.

◆ sample_size

unsigned DesktopInterface::SoundPlayerParms::sample_size

Number of samples that are buffered.

Usually, this value coincides with the L parameter passed to the SoundMonoProducer.

Definition at line 156 of file DesktopInterface.h.

◆ PalettizedWindow

class PalettizedWindow

A palettized window on the desktop.

A window opened in a desktop to draw in its inner area, without any resize or maximize possibilities, i.e., with a fixed size, and with a drawable surface that has one byte per pixel holding the index, in a color palette, of the color of that pixel. The scaling of the window is intrinsic to it and it must be managed by the refreshing methods, not by the public methods, that will work as if no scaling exists.

Definition at line 327 of file DesktopInterface.h.

Inheritance diagram for PalettizedWindow:

[legend]

Public Types
typedef uint8_t	PaletteLevel
	Intensity of a color component (r, g, b). More...

typedef uint8_t	PaletteIndex
	Index of a color in the palette. More...

Static Public Attributes
static constexpr unsigned	NUMCOLSPAL = 256
	No. of colors in palette. More...

Public Member Functions
-----------------— Constructors -------------------------—
virtual	~PalettizedWindow (void)
	Destructor (derived classes must close the window).

	PalettizedWindow (const PalettizedWindow &)=delete
	Copies forbidden.

PalettizedWindow &	operator= (const PalettizedWindow &)=delete
	forb.

	PalettizedWindow (PalettizedWindow &&)=delete
	Moves forbidden.

PalettizedWindow &	operator= (PalettizedWindow &&)=delete
	forbidden.

------------------— General Methods ----------------------—
unsigned	width (void) const noexcept
	Return the width in (non-scaled) pixels of the window. More...

unsigned	height (void) const noexcept
	Return the height in (non-scaled) pixels of the window. More...

virtual void	refresh (const Rectangle &rect=Rectangle{})=0
	Render current screen content on the desktop with proper scaling. More...

virtual void	serveEvents (const PalettizedWindow::Event::IDSet &whichevents={true}, ListOfEvents *evs=nullptr)=0
	Serve all pending events for the window to the underlying desktop systm. More...

virtual void	setPaletteColors (const PaletteLevel *colors, PaletteIndex first, PaletteIndex count)=0
	Change the given color(s) in the window palette. More...

------------------— Drawing Methods ----------------------—
virtual Cursor	getCursor (unsigned x=0, unsigned y=0) noexcept=0
	Get a non-checking cursor that points to that pixel. More...

virtual CursorCheck	getCursorCheck (unsigned x=0, unsigned y=0)=0
	Get a checking cursor that points to that pixel. More...

virtual PaletteIndex	getPixel (const Cursor &cursor)=0
	Return the value of the pixel at CURSOR in the window, if all is valid. More...

virtual void	setPixel (const Cursor &cursor, PaletteIndex b)=0
	Set pixel at CURSOR to B, if all is valid. More...

virtual void	fillRect (const Rectangle &r, PaletteIndex c)=0
	Fill a rectangle in the window with the given color, efficiently. More...

------------------— Pointing Methods ---------------------—
virtual bool	getPointingInWindow (unsigned &x, unsigned &y, bool &leftbutton, bool &rightbutton)=0
	Must get the mouse status on the window. More...

------------------— Keyboard Methods ---------------------—
virtual bool	keyPressed (DesktopInterface::KeyID k)=0
	Must inform about whether the key K is pressed or not. More...

virtual void	updateKeypressMap (DesktopInterface::KeypressMap &map)=0
	Must update MAP with the current state of all keys. More...

Protected Member Functions
	PalettizedWindow (const std::string &tit, unsigned dimw, unsigned dimh, unsigned scalex, unsigned scaley)
	Constructor. More...

Protected Attributes
const std::string	title_
	Title of the window. More...

const size_t	size_
	Size in pixels of the window. More...


const unsigned	width_
	Unscaled dims of the bitmap drawable. More...

const unsigned	height_
	Unscaled dims of the bitmap drawable. More...


const unsigned	scx_
	Scale of the bitmap when rendered. More...

const unsigned	scy_
	Scale of the bitmap when rendered. More...


const unsigned	swidth_
	Scaled dim of bitmap (dim of window). More...

const unsigned	sheight_
	Scaled dim of bitmap (dim of window). More...

Member Typedef Documentation

◆ PaletteLevel

typedef uint8_t PalettizedWindow::PaletteLevel

Intensity of a color component (r, g, b).

Definition at line 333 of file DesktopInterface.h.

◆ PaletteIndex

typedef uint8_t PalettizedWindow::PaletteIndex

Index of a color in the palette.

Definition at line 334 of file DesktopInterface.h.

Constructor & Destructor Documentation

◆ PalettizedWindow()

PalettizedWindow::PalettizedWindow	(	const std::string &	tit,
		unsigned	dimw,
		unsigned	dimh,
		unsigned	scalex,
		unsigned	scaley
	)

protected

Constructor.

It is protected for derived classes to call it; not public for forcing the creation of PalettizedWindow through DesktopInterface derivatives.

Member Function Documentation

◆ width()

unsigned PalettizedWindow::width ( void ) const

inlinenoexcept

Return the width in (non-scaled) pixels of the window.

Definition at line 586 of file DesktopInterface.h.

◆ height()

unsigned PalettizedWindow::height ( void ) const

inlinenoexcept

Return the height in (non-scaled) pixels of the window.

Definition at line 589 of file DesktopInterface.h.

◆ refresh()

virtual void PalettizedWindow::refresh ( const Rectangle & rect = Rectangle{} )

pure virtual

Render current screen content on the desktop with proper scaling.

RECT indicates which portion of the internal displayable data has changed since the last refresh; the method may refresh only that or do a complete window refresh (or even use RECT as a hint to do less data processing but do a complete refresh after all). If RECT is empty, it is considered to cover the entire window. In any case, it is not scaled. Only after calling this method it is assured that the desktop shows the current displayable data of the window.

Note: - Depending on the implementation, the OS and the graphic drivers, this refresh may block until a vertical retrace occurs.; - Derived classes may require to call this method from the main thread of the program.

Implemented in PalWinSDL2.

◆ serveEvents()

virtual void PalettizedWindow::serveEvents	(	const PalettizedWindow::Event::IDSet &	whichevents = `{true}`,
		ListOfEvents *	evs = `nullptr`
	)

pure virtual

Serve all pending events for the window to the underlying desktop systm.

Process all pending events for the window and store those that are indicated in WHICHEVENTS into EVS if EVS!=nullptr, chronologically (EVS is NOT cleared first). The events that have some effect in the window (keyboard updates, etc.) have their effects but are also stored into EVS. This is usually needed periodically for the window not to freeze on the desktop, and for being responsive. It may be required to be called from the main thread.

Implemented in PalWinSDL2.

◆ setPaletteColors()

virtual void PalettizedWindow::setPaletteColors	(	const PaletteLevel *	colors,
		PaletteIndex	first,
		PaletteIndex	count
	)

pure virtual

Change the given color(s) in the window palette.

If that affects the shown image, a refresh is NOT required to see the changes.

Implemented in PalWinSDL2.

◆ getCursor()

virtual Cursor PalettizedWindow::getCursor	(	unsigned	x = `0`,
		unsigned	y = `0`
	)

pure virtualnoexcept

Get a non-checking cursor that points to that pixel.

Implemented in PalWinSDL2.

◆ getCursorCheck()

virtual CursorCheck PalettizedWindow::getCursorCheck	(	unsigned	x = `0`,
		unsigned	y = `0`
	)

pure virtual

Get a checking cursor that points to that pixel.

Implemented in PalWinSDL2.

◆ getPixel()

virtual PaletteIndex PalettizedWindow::getPixel ( const Cursor & cursor )

pure virtual

Return the value of the pixel at CURSOR in the window, if all is valid.

Otherwise, exception is raised.

Implemented in PalWinSDL2.

◆ setPixel()

virtual void PalettizedWindow::setPixel	(	const Cursor &	cursor,
		PaletteIndex	b
	)

pure virtual

Set pixel at CURSOR to B, if all is valid.

Otherwise, exception is raised.

Implemented in PalWinSDL2.

◆ fillRect()

virtual void PalettizedWindow::fillRect	(	const Rectangle &	r,
		PaletteIndex	c
	)

pure virtual

Fill a rectangle in the window with the given color, efficiently.

Exception if some part of the rectangle falls outside the window.

Implemented in PalWinSDL2.

◆ getPointingInWindow()

virtual bool PalettizedWindow::getPointingInWindow	(	unsigned &	x,
		unsigned &	y,
		bool &	leftbutton,
		bool &	rightbutton
	)

pure virtual

Must get the mouse status on the window.

Get the coordinates X,Y within this window of the mouse or equivalent pointing device, and the state of pressing two main buttons. If the window has a scale != 1, these coordinates will be scale-corrected, i.e., they will not reflect the scale. X,Y will be referenced to the top-left corner of the drawable area of the window. If the cursor is actually out of that area, FALSE must be returned.

Note: -A previous serve of events must be done in order to process all mouse movements and clicks by the underlying desltop system and thus having an updated pointing status.

Implemented in PalWinSDL2.

◆ keyPressed()

virtual bool PalettizedWindow::keyPressed ( DesktopInterface::KeyID k )

pure virtual

Must inform about whether the key K is pressed or not.

Return TRUE if the given key is currently pressed on the window, or FALSE if it is not. Raise an exception if K is invalid.

Note: -A previous serve of events must be done in order to process all keyboard changes by the underlying desktop system and thus having an updated state of the keys.

Implemented in PalWinSDL2.

◆ updateKeypressMap()

virtual void PalettizedWindow::updateKeypressMap ( DesktopInterface::KeypressMap & map )

pure virtual

Must update MAP with the current state of all keys.

May raise exceptions if MAP is not valid. All KeyID that are not recognized in the current desktop must appear here always as unpressed.

Note: -A previous serve of events must be done in order to process all keyboard changes by the underlying desktop system and thus having an updated state of the keys.

Implemented in PalWinSDL2.

Member Data Documentation

◆ NUMCOLSPAL

constexpr unsigned PalettizedWindow::NUMCOLSPAL = 256

staticconstexpr

No. of colors in palette.

Definition at line 364 of file DesktopInterface.h.

◆ title_

const std::string PalettizedWindow::title_

protected

Title of the window.

Definition at line 702 of file DesktopInterface.h.

◆ width_

const unsigned PalettizedWindow::width_

protected

Unscaled dims of the bitmap drawable.

Definition at line 704 of file DesktopInterface.h.

◆ height_

const unsigned PalettizedWindow::height_

protected

Unscaled dims of the bitmap drawable.

Definition at line 704 of file DesktopInterface.h.

◆ size_

const size_t PalettizedWindow::size_

protected

Size in pixels of the window.

Definition at line 706 of file DesktopInterface.h.

◆ scx_

const unsigned PalettizedWindow::scx_

protected

Scale of the bitmap when rendered.

Definition at line 708 of file DesktopInterface.h.

◆ scy_

const unsigned PalettizedWindow::scy_

protected

Scale of the bitmap when rendered.

Definition at line 708 of file DesktopInterface.h.

◆ swidth_

const unsigned PalettizedWindow::swidth_

protected

Scaled dim of bitmap (dim of window).

Definition at line 711 of file DesktopInterface.h.

◆ sheight_

const unsigned PalettizedWindow::sheight_

protected

Scaled dim of bitmap (dim of window).

Definition at line 711 of file DesktopInterface.h.

◆ PalettizedWindow::Rectangle

struct PalettizedWindow::Rectangle

A rectangle on a palettized window.

Definition at line 337 of file DesktopInterface.h.

Public Attributes

unsigned	x0
	x0,y0 are the pixel at the left-top corner. More...

unsigned	y0
	x0,y0 are the pixel at the left-top corner. More...


unsigned	w
	Dimensions of the rectangle in pixels. More...

unsigned	h
	Dimensions of the rectangle in pixels. More...

Public Member Functions
	Rectangle (void) noexcept
	Default constructor: empty rectangle. More...

	Rectangle (unsigned x, unsigned y, unsigned wi, unsigned he) noexcept
	Constructor. More...

bool	empty (void) const noexcept
	Return TRUE if the rectangle is empty. More...

std::string	to_string (void) const
	Return a text describing the rectangle. More...

Constructor & Destructor Documentation

◆ Rectangle() [1/2]

PalettizedWindow::Rectangle::Rectangle ( void )

inlinenoexcept

Default constructor: empty rectangle.

Definition at line 347 of file DesktopInterface.h.

◆ Rectangle() [2/2]

PalettizedWindow::Rectangle::Rectangle	(	unsigned	x,
		unsigned	y,
		unsigned	wi,
		unsigned	he
	)

inlinenoexcept

Constructor.

Definition at line 350 of file DesktopInterface.h.

Member Function Documentation

◆ empty()

bool PalettizedWindow::Rectangle::empty ( void ) const

inlinenoexcept

Return TRUE if the rectangle is empty.

Definition at line 354 of file DesktopInterface.h.

◆ to_string()

std::string PalettizedWindow::Rectangle::to_string ( void ) const

inline

Return a text describing the rectangle.

Definition at line 357 of file DesktopInterface.h.

Member Data Documentation

◆ x0

unsigned PalettizedWindow::Rectangle::x0

x0,y0 are the pixel at the left-top corner.

Definition at line 340 of file DesktopInterface.h.

◆ y0

unsigned PalettizedWindow::Rectangle::y0

x0,y0 are the pixel at the left-top corner.

Definition at line 340 of file DesktopInterface.h.

◆ w

unsigned PalettizedWindow::Rectangle::w

Dimensions of the rectangle in pixels.

Definition at line 343 of file DesktopInterface.h.

◆ h

unsigned PalettizedWindow::Rectangle::h

Dimensions of the rectangle in pixels.

Definition at line 343 of file DesktopInterface.h.

◆ PalettizedWindow::Event

struct PalettizedWindow::Event

Events that the window can receive from its desktop environment.

Note that some information is not stored in the event, but consolidated in the mouse pointing status or keyboard state, that can be consulted through the methods in this PalettizedWindow class.

Definition at line 370 of file DesktopInterface.h.

Public Types
enum class	ID { W_CLOSED = 0 , W_MINIMIZED , W_RESTORED , W_MOVED , W_EXPOSED , K_PRESSED , K_UNPRESSED , K_TEXT , M_MOVED , M_BUTTONCLICKED , M_BUTTONUNCLICKED , M_WHEEL }
	< IDs for the events that the desktop can send to a window. More...

Static Public Attributes
static const uint8_t	N_IDS = static_cast<uint8_t>(ID::M_WHEEL) + 1
	Number of event IDs More...

Public Attributes
ID	id
	ID of the event that occurred. More...

union {
struct {
DesktopInterface::KeyID key
	Key pressed or unpress. More...

} keyboard
	Data for a K_PRESSED / K_UNPRESSED evnt.

struct {
char utf8char [7]
	Recognized UTF-8 char (0-ended). More...

} textkey
	Data for a K_TEXT event.

struct {
int32_t incx
	Increment in X. More...

int32_t incy
	Increment in Y. More...

unsigned x

unsigned y
	Pos of the mouse after event. More...

bool buttons [2]
	0-> left, 1-> right; TRUE-> clickd More...

} motion
	Data for a M_MOVED event.

struct {
char which
	'L' (left) or 'R' (right) More...

unsigned x

unsigned y
	Pos of the mouse when clicked. More...

} button
	Data for a M_BUTTON* event.

struct {
int32_t incvert
	Increment in vertical. More...

} wheel
	Data for a M_WHEEL event.

}	data
	Data of the event.

Public Member Functions
std::string	to_string (void) const
	Return a text with the event info.

Member Enumeration Documentation

◆ ID

enum class PalettizedWindow::Event::ID

strong

< IDs for the events that the desktop can send to a window.

Enumerator
W_CLOSED	The close window event.
W_MINIMIZED	The minimize window event.
W_RESTORED	The restore (from min.) window event.
W_MOVED	The drag-and-drop window event.
W_EXPOSED	Window exposed & needed of a refresh.
K_PRESSED	Key pressed.
K_UNPRESSED	Key unpressed.
K_TEXT	Key or combination recognized as text. Use this event instead of the previous ones if you need text already interpreted for your keyboard layout (by the OS), e.g., when typing If enabled, it will be issued besides K_PRESSED and K_UNPRESSED events, as long as the desktop system has the K_TEXT events activated (see enableTextEvents() and disableTextEvents() methods). A K_TEXT event will be issued when some key (combination) is successfully recognized by the OS; this does not include special keys (shifts, ctrls, arrows, enter, tab, ...).
M_MOVED	Mouse movement.
M_BUTTONCLICKED	Mouse click.
M_BUTTONUNCLICKED	Mouse unclick.
M_WHEEL	Mouse wheel change.

Definition at line 373 of file DesktopInterface.h.

Member Data Documentation

◆ N_IDS

const uint8_t PalettizedWindow::Event::N_IDS = static_cast<uint8_t>(ID::M_WHEEL) + 1

static

Number of event IDs

Definition at line 412 of file DesktopInterface.h.

◆ id

ID PalettizedWindow::Event::id

ID of the event that occurred.

Definition at line 433 of file DesktopInterface.h.

◆ key

DesktopInterface::KeyID PalettizedWindow::Event::key

Key pressed or unpress.

Definition at line 436 of file DesktopInterface.h.

◆ utf8char

char PalettizedWindow::Event::utf8char[7]

Recognized UTF-8 char (0-ended).

Definition at line 439 of file DesktopInterface.h.

◆ incx

int32_t PalettizedWindow::Event::incx

Increment in X.

Definition at line 442 of file DesktopInterface.h.

◆ incy

int32_t PalettizedWindow::Event::incy

Increment in Y.

Definition at line 443 of file DesktopInterface.h.

◆ x

unsigned PalettizedWindow::Event::x

Definition at line 444 of file DesktopInterface.h.

◆ y

unsigned PalettizedWindow::Event::y

Pos of the mouse after event.

Pos of the mouse when clicked.

As in getPointingInWindow()

Definition at line 444 of file DesktopInterface.h.

◆ buttons

bool PalettizedWindow::Event::buttons[2]

0-> left, 1-> right; TRUE-> clickd

Definition at line 446 of file DesktopInterface.h.

◆ which

char PalettizedWindow::Event::which

'L' (left) or 'R' (right)

Definition at line 449 of file DesktopInterface.h.

◆ incvert

int32_t PalettizedWindow::Event::incvert

Increment in vertical.

The increment is in ticks of the wheel, not pixels on the screen. Down movement is negative; up is positive.

Definition at line 454 of file DesktopInterface.h.

◆ PalettizedWindow::Event::IDSet

class PalettizedWindow::Event::IDSet

A compact set of IDs.

Definition at line 416 of file DesktopInterface.h.

Inheritance diagram for PalettizedWindow::Event::IDSet:

[legend]

Collaboration diagram for PalettizedWindow::Event::IDSet:

[legend]

Public Member Functions
	IDSet (bool all=false) noexcept
	< Constructor of empty (ALL == FALSE) or full (ALL == TRUE) set. More...

	IDSet (const std::set< ID > &sids)

bool	contains (ID id) const noexcept
	< Convenience check of existence of ID in the set. More...

Constructor & Destructor Documentation

◆ IDSet() [1/2]

PalettizedWindow::Event::IDSet::IDSet ( bool all = false )

inlinenoexcept

< Constructor of empty (ALL == FALSE) or full (ALL == TRUE) set.

Definition at line 420 of file DesktopInterface.h.

◆ IDSet() [2/2]

PalettizedWindow::Event::IDSet::IDSet ( const std::set< ID > & sids )

inline

Parameters

sids	Constructor from an initializer list.

Definition at line 424 of file DesktopInterface.h.

Member Function Documentation

◆ contains()

bool PalettizedWindow::Event::IDSet::contains ( ID id ) const

inlinenoexcept

< Convenience check of existence of ID in the set.

Definition at line 428 of file DesktopInterface.h.

◆ PalettizedWindow::ListOfEvents

class PalettizedWindow::ListOfEvents

List of events that occurred in the window, in chronological order.

A list is used instead of vector for fast removing of front and back. Since we will not need random access to elements, but ordered sequential access, we do not use deque either.

Definition at line 471 of file DesktopInterface.h.

Inheritance diagram for PalettizedWindow::ListOfEvents:

[legend]

Collaboration diagram for PalettizedWindow::ListOfEvents:

[legend]

Public Types
using	Base = std::list< Event >
	A shortcut. More...

Public Member Functions
bool	contains (Event::ID eid) const noexcept
	< To inherit all constructors More...

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

Member Typedef Documentation

◆ Base

using PalettizedWindow::ListOfEvents::Base = std::list<Event>

A shortcut.

Definition at line 475 of file DesktopInterface.h.

Member Function Documentation

◆ contains()

bool PalettizedWindow::ListOfEvents::contains ( Event::ID eid ) const

inlinenoexcept

< To inherit all constructors

< Return TRUE if E appears at least once in the list.

Definition at line 478 of file DesktopInterface.h.

◆ PalettizedWindow::Cursor

class PalettizedWindow::Cursor

To refer to pixels in the drawable area of the window.

It is recommended to construct these cursors from the methods that do that in the PalettizedWindow (or derived classes). The iterator is considered to find pixels linearly, i.e., the first one will be at (0,0) and the rest of them will go on contiguously, from left to right, from top to bottom, with pitch == width ("pitch" is the number to add to a given offset in the drawable area to reach the pixel just below the pixel that is currently pointed by the offset). This base class has checking code included.

Definition at line 498 of file DesktopInterface.h.

Inheritance diagram for PalettizedWindow::Cursor:

[legend]

Public Member Functions
	Cursor (const PalettizedWindow &palwin, unsigned x=0, unsigned y=0, size_t bytesperpixel=1) noexcept
	Default constructor from the coords of a given pixel in PALWIN.

virtual	~Cursor (void)=default
	Destructor.

unsigned	x (void) const noexcept
	X coordinate of the cursor. More...

unsigned	y (void) const noexcept
	Y coordinate of the cursor. More...

bool	outside (void) const noexcept
	Whether the cursor is outside the drawable. FALSE for non-checking. More...

void	incX (void) noexcept
	Make the iterator point to the next pixel in x. More...

void	incY (void) noexcept
	Make the iterator point to the pixel right below the current one. More...

size_t	offset (void) const noexcept
	Return the linear offset within the drawable area of the cursor. More...

std::string	to_string (void) const noexcept
	Return a description of the cursor.

Protected Attributes
unsigned	x_

unsigned	y_
	Cursor position in coordinates. More...

size_t	pitch_
	Length of one row of pixels in memory. More...

size_t	o_
	Linear size of the window, in bytes. More...

Member Function Documentation

◆ x()

unsigned PalettizedWindow::Cursor::x ( void ) const

inlinenoexcept

X coordinate of the cursor.

Definition at line 510 of file DesktopInterface.h.

◆ y()

unsigned PalettizedWindow::Cursor::y ( void ) const

inlinenoexcept

Y coordinate of the cursor.

Definition at line 513 of file DesktopInterface.h.

◆ outside()

bool PalettizedWindow::Cursor::outside ( void ) const

inlinenoexcept

Whether the cursor is outside the drawable. FALSE for non-checking.

Definition at line 516 of file DesktopInterface.h.

◆ incX()

void PalettizedWindow::Cursor::incX ( void )

inlinenoexcept

Make the iterator point to the next pixel in x.

Definition at line 519 of file DesktopInterface.h.

◆ incY()

void PalettizedWindow::Cursor::incY ( void )

inlinenoexcept

Make the iterator point to the pixel right below the current one.

Definition at line 522 of file DesktopInterface.h.

◆ offset()

size_t PalettizedWindow::Cursor::offset ( void ) const

inlinenoexcept

Return the linear offset within the drawable area of the cursor.

Definition at line 525 of file DesktopInterface.h.

Member Data Documentation

◆ x_

unsigned PalettizedWindow::Cursor::x_

protected

Definition at line 533 of file DesktopInterface.h.

◆ y_

unsigned PalettizedWindow::Cursor::y_

protected

Cursor position in coordinates.

Definition at line 533 of file DesktopInterface.h.

◆ pitch_

size_t PalettizedWindow::Cursor::pitch_

protected

Length of one row of pixels in memory.

Definition at line 534 of file DesktopInterface.h.

◆ o_

size_t PalettizedWindow::Cursor::o_

protected

Linear size of the window, in bytes.

Definition at line 535 of file DesktopInterface.h.

◆ PalettizedWindow::CursorCheck

class PalettizedWindow::CursorCheck

Cursor to refer to pixels that includes checking code.

< This class does not produce exceptions; instead, return outside() == true whenever the cursor is outside the drawable area. This is checked by the methods that use the cursor for accessing the area in the PalettizedWindow or derived classes.

Definition at line 543 of file DesktopInterface.h.

Inheritance diagram for PalettizedWindow::CursorCheck:

[legend]

Collaboration diagram for PalettizedWindow::CursorCheck:

[legend]

Public Member Functions
	CursorCheck (const PalettizedWindow &palwin, unsigned x=0, unsigned y=0, size_t bytesperpixel=1) noexcept
	Constructor for the given window and with the given values.

bool	outside (void) const noexcept
	Whether the cursor is outside the drawable. FALSE for non-checking.

void	incX (void) noexcept
	Make the iterator point to the next pixel in x.

void	incY (void) noexcept
	Make the iterator point to the pixel right below the current one.

std::string	to_string (void) const noexcept
	Return a description of the cursor.

Public Member Functions inherited from PalettizedWindow::Cursor
	Cursor (const PalettizedWindow &palwin, unsigned x=0, unsigned y=0, size_t bytesperpixel=1) noexcept
	Default constructor from the coords of a given pixel in PALWIN.

virtual	~Cursor (void)=default
	Destructor.

unsigned	x (void) const noexcept
	X coordinate of the cursor. More...

unsigned	y (void) const noexcept
	Y coordinate of the cursor. More...

bool	outside (void) const noexcept
	Whether the cursor is outside the drawable. FALSE for non-checking. More...

void	incX (void) noexcept
	Make the iterator point to the next pixel in x. More...

void	incY (void) noexcept
	Make the iterator point to the pixel right below the current one. More...

size_t	offset (void) const noexcept
	Return the linear offset within the drawable area of the cursor. More...

std::string	to_string (void) const noexcept
	Return a description of the cursor.

Protected Attributes
size_t	n_
	Linear size of the window, in bytes. More...

Protected Attributes inherited from PalettizedWindow::Cursor
unsigned	x_

unsigned	y_
	Cursor position in coordinates. More...

size_t	pitch_
	Length of one row of pixels in memory. More...

size_t	o_
	Linear size of the window, in bytes. More...

Member Data Documentation

◆ n_

size_t PalettizedWindow::CursorCheck::n_

protected

Linear size of the window, in bytes.

Definition at line 566 of file DesktopInterface.h.

Description

Classes

Class Documentation

◆ DesktopInterface

Public Types

Static Public Member Functions

Static Public Attributes

Public Member Functions

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ SoundMonoProducer

Member Enumeration Documentation

◆ KeyID

Constructor & Destructor Documentation

◆ DesktopInterface()

Member Function Documentation

◆ keyIsNumber()

◆ keyIsLetter()

◆ keyIsFunction()

◆ keyIsForMotion()

◆ readPNGImageFile()

◆ writePNGImageFile()

◆ getDesktopResolution()

◆ createWindow()

◆ playerParms()

◆ playSound()

◆ pausePlaying()

◆ resumePlaying()

◆ playingPaused()

◆ soundPlaying()

◆ nextSoundPlayingTime()

◆ lastSoundProducer()

◆ lastSoundDuration()

◆ enableTextEvents()

◆ disableTextEvents()

◆ textEventsEnabled()

◆ copyFromClipboard()

◆ copyToClipboard()

Member Data Documentation

◆ KeyNames

◆ SilenceMonoProducer

◆ playerparms_

◆ DesktopInterface::KeypressMap

Public Member Functions

◆ DesktopInterface::SoundPlayerParms

Public Attributes

Public Member Functions

Constructor & Destructor Documentation

◆ SoundPlayerParms() [1/2]

◆ SoundPlayerParms() [2/2]

Member Data Documentation

◆ sampling_period

◆ sample_size

◆ PalettizedWindow

Public Types

Static Public Attributes

Public Member Functions

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ PaletteLevel

◆ PaletteIndex

Constructor & Destructor Documentation

◆ PalettizedWindow()

Member Function Documentation

◆ width()

◆ height()

◆ refresh()

◆ serveEvents()

◆ setPaletteColors()

◆ getCursor()

◆ getCursorCheck()

◆ getPixel()

◆ setPixel()

◆ fillRect()

◆ getPointingInWindow()

◆ keyPressed()

◆ updateKeypressMap()

Member Data Documentation