Detailed Description

v2.00 (30 Jun 2023)
The GUI module includes the GUI Manager for handling all operations with panels, consoles and debug windows.

Console and DebugWindow are automatically rendered on top of everything and Panel objects are ,by default, also rendered automatically but if you want to have a better control of the rendering order, you can override this setting with autoRender() and manually render your Panel objects on the desired order.

Todo:: Complete the documentation for GUIMgr widgets (excepto baseWidget) tienen una referencia a su panel. panel,debug y consola siguen I+D #0005 explicar los eventos de retorno con sus valores explicar estado de cada boton que grafico contiene poner tabla excel con los tipos y caracteristicas (en develnotes) usar en el hilo principal consolas son como un textbox, capturan el foco de input text pero dejan el resto funcionar panel is shared, debugw y consola no progressbar sin imagen/sprite necesita un setsize para saber con el rango como de grande es el widget y como dividir cada value. Con imagen y sprite, lo calcula automaticamente. El tamano para cada state debe ser igual. Al menos necesita WS_PRESSED y WS_HOVERED

Only a single instance of the GUI Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::IGUIMgr() method.

Note: The GUI Manager is automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding a resource leak.

Classes
class	CRM64Pro::Panel
	Panel Object class. More...

class	CRM64Pro::Console
	Console Object class. More...

class	CRM64Pro::DebugWindow
	DebugWindow Object class. More...

class	CRM64Pro::GUIMgr
	GUI Manager class. More...

Macros
#define	GUI_PANEL 0x42000000

#define	GUI_CONSOLE 0x44000000

#define	GUI_DEBUGWINDOW 0x48000000

Enumerations
enum	CRM64Pro::ePanelType { CRM64Pro::PT_RETRIEVE = -1 , CRM64Pro::PT_MODELESS = 0 , CRM64Pro::PT_MODAL = 1 , CRM64Pro::PT_EPHEMERAL = 2 }
	Panel Type. More...

Functions
Sint32	CRM64Pro::GUIMgr::info (Sint32 idGUI=0)
	Request GUI Manager information.

Sint32	CRM64Pro::GUIMgr::create (const string &sName, Uint32 iType=GUI_PANEL)
	Creates a new GUI object.

Sint32	CRM64Pro::GUIMgr::close (Sint32 idGUI)
	Close and destroy a GUI object.

Sint32	CRM64Pro::GUIMgr::getNum ()
	Get number of loaded objects.

Sint32	CRM64Pro::GUIMgr::setName (Sint32 idGUI, const string &sName)
	Change the object name.

Panel *	CRM64Pro::GUIMgr::getPanel (Sint32 idGUI=0)
	Get a pointer to a Panel using its handler.

Sint32	CRM64Pro::GUIMgr::getPanelFocus ()
	Get the GUI Panel id with the focus.

Sint32	CRM64Pro::GUIMgr::setPanelFocus (Sint32 idGUI)
	Set the focus on the given GUI Panel id.

Console *	CRM64Pro::GUIMgr::getConsole (Sint32 idGUI=GUI_CONSOLE)
	Get a pointer to a Console using its handler.

DebugWindow *	CRM64Pro::GUIMgr::getDebugWindow (Sint32 idGUI=0)
	Get a pointer to a DebugWindow using its handler.

Sint32	CRM64Pro::GUIMgr::load (const string &sFileCDC, const string &sName)
	Load a panel and its widgets stored in a CDC file.

Sint32	CRM64Pro::GUIMgr::load (Sint32 idCDC, const string &sName)
	Load a panel and its widgets stored in a CDC file.

Sint32	CRM64Pro::GUIMgr::getFontWhiteAA ()
	Get the built-in white font.

Sint32	CRM64Pro::GUIMgr::getFontBlack ()
	Get the built-in black font.

Sint32	CRM64Pro::GUIMgr::getIconInfo ()
	Get the built-in info icon.

Sint32	CRM64Pro::GUIMgr::getIconWarning ()
	Get the built-in warning icon.

Sint32	CRM64Pro::GUIMgr::getIconError ()
	Get the built-in error icon.

Sint32	CRM64Pro::Console::info (Sint32 iMode=0)
	Request Console information.

Sint32	CRM64Pro::Console::getName (string &sName)
	Get the name.

Uint32	CRM64Pro::Console::getID ()
	Get the ID.

Widget &	CRM64Pro::Console::baseWidget ()
	Get the reference to base Widget for this object.

Sint32	CRM64Pro::Console::attachTo (Sint32 idScreen)
	Attach this console to a screen.

Sint32	CRM64Pro::Console::print (const char *format,...)
	Print a formatted message to the console.

Sint32	CRM64Pro::Console::vPrint (const char *format, va_list args)
	Print a formatted message to the console.

Sint32	CRM64Pro::Console::addCmdHandler (const string &sCommandName, const string &sCommandHelp, Sint32(cmdFunc)(vector< string > , Console *pCon))
	Add a new command handler to the console.

Sint32	CRM64Pro::Console::executeCmd (const string &)
	Execute a command on this console.

Sint32	CRM64Pro::DebugWindow::info (Sint32 iMode=0)
	Request DebugWindow information.

Sint32	CRM64Pro::DebugWindow::getName (string &sName)
	Get the name.

Uint32	CRM64Pro::DebugWindow::getID ()
	Get the ID.

Widget &	CRM64Pro::DebugWindow::baseWidget ()
	Get the reference to base Widget for this object.

Sint32	CRM64Pro::DebugWindow::addWatch (const string &sName, Sint32 iIntegerVar, double dDoubleVar=nullptr)
	Add a watch.

Sint32	CRM64Pro::DebugWindow::removeWatch (const string &sName)
	Remove a watch.

Sint32	CRM64Pro::DebugWindow::attachTo (Sint32 idScreen)
	Attach this debugwindow to a screen.

Sint32	CRM64Pro::DebugWindow::setRefreshInterval (Sint32)
	Set the refresh interval.

Sint32	CRM64Pro::DebugWindow::getRefreshInterval ()
	Get the refresh interval.

Sint32	CRM64Pro::Panel::info (Sint32 iMode=0)
	Request Panel information.

Sint32	CRM64Pro::Panel::getName (string &sName)
	Get the name.

Uint32	CRM64Pro::Panel::getID ()
	Get the ID.

Widget &	CRM64Pro::Panel::baseWidget ()
	Get the reference to base Widget for this object.

Sint32	CRM64Pro::Panel::attachTo (Sint32 idScreen)
	Attach this panel to a screen.

Sint32	CRM64Pro::Panel::getScreen ()
	Return the screen id where this panel is attached to.

Sint32	CRM64Pro::Panel::createWidget (const string &sName, eWidgetType eWT, Sint32 iWID)
	Create a widget.

Widget *	CRM64Pro::Panel::getWidget (Sint32 iWID)
	Get a pointer to a Widget using its handler.

Sint32	CRM64Pro::Panel::closeWidget (Sint32 iWID)
	Close and destroy a Widget.

Sint32	CRM64Pro::Panel::type (ePanelType ePT=PT_RETRIEVE, Sint32 iTime=0)
	Set or get panel type.

Sint32	CRM64Pro::Panel::save (const string &sFileCDC)
	Save the panel and all its widgets to a CDC file.

Sint32	CRM64Pro::Panel::save (Sint32 idCDC)
	Save the panel and all its widgets to a CDC file.

Macro Definition Documentation

◆ GUI_PANEL

#define GUI_PANEL 0x42000000

GUI Object: Panel.

◆ GUI_CONSOLE

#define GUI_CONSOLE 0x44000000

GUI Object: Console.

◆ GUI_DEBUGWINDOW

#define GUI_DEBUGWINDOW 0x48000000

GUI Object: DebugWindow.

Enumeration Type Documentation

◆ ePanelType

enum CRM64Pro::ePanelType

Panel Type.

Enumerator
PT_RETRIEVE	Used for getting current panel type.
PT_MODELESS	Modeless panel. When it gets the focus, it does not block the input for others panels.
PT_MODAL	Modal panel. When it gets the focus, it blocks the input for others panels on the same screen.
PT_EPHEMERAL	Ephemeral and modeless panel. It lasts the given time duration.

Function Documentation

◆ info() [1/4]

Sint32 CRM64Pro::GUIMgr::info ( Sint32 iMode = 0 )

Request GUI Manager information.

For displaying the information, it uses the default log.

Parameters

iMode -1 for displaying only Manager information.
0 for displaying Manager and all Objects information. This is the default value.
idGUI for displaying Manager and given Object id information.

Returns: 0 on success or a negative error code on failure.

◆ create()

Sint32 CRM64Pro::GUIMgr::create	(	const string &	sName,
		Uint32	iType = `GUI_PANEL`
	)

Creates a new GUI object.

Parameters

sName	The name for the GUI object (e.g. 'myPanel' or 'myDebugWindow'). The object name must be unique and with a maximum size of 64 characters or will be truncated.
iType	GUI Object type (GUI_PANEL, GUI_CONSOLE or GUI_DEBUGWINDOW) OR'ed with the version: 10 means 1.0 which is the only version supported (as of now). GUI_PANEL is the default value and if no version is set, it uses v1.0.

Returns: greater than 0 on success(the GUI id) or a negative error code on failure.

Note: By default, all GUI Objects are attached to the default screen but it can be changed anytime using Panel::attachTo(), Console::attachTo() and DebugWindow::attachTo() methods.
Created objects have the baseWidget status set to enabled but hidden (C64_STATUS_HIDDEN).

◆ close()

Sint32 CRM64Pro::GUIMgr::close ( Sint32 idGUI )

Close and destroy a GUI object.

Parameters

idGUI 0 for closing all GUI objects or the GUI id.
The default console is automatically created and can not be removed with this method.
As the GUI Manager has the ability of sharing a Panel id, if the panel is shared, it will not be removed till the last owner call this method.

Returns: 0 on success or a negative error code on failure.

Note: If you forget to close an object, it will be automatically closed once the GDK is terminated.

◆ getNum()

Sint32 CRM64Pro::GUIMgr::getNum ( )

Get number of loaded objects.

Returns: the number of log objects.

◆ setName()

Sint32 CRM64Pro::GUIMgr::setName	(	Sint32	idGUI,
		const string &	sName
	)

Change the object name.

Parameters

idGUI	GUI id. It can be a Panel, Console or DebugWindow
sName	The name to give to the Panel object (e.g. 'myPanel'). The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns: 0 on success or a negative error code on failure.

◆ getPanel()

Panel * CRM64Pro::GUIMgr::getPanel ( Sint32 idGUI = 0 )

Get a pointer to a Panel using its handler.

Parameters

idGUI GUI id.

Returns: nullptr the Panel was not found.; A pointer to the Panel object.

◆ getPanelFocus()

Sint32 CRM64Pro::GUIMgr::getPanelFocus ( )

Get the GUI Panel id with the focus.

Returns: greater than 0 on success(the GUI Panel id) or a negative error code on failure.

◆ setPanelFocus()

Sint32 CRM64Pro::GUIMgr::setPanelFocus ( Sint32 idGUI )

Set the focus on the given GUI Panel id.

Parameters

idGUI the GUI Panel id. In order to get the focus, the panel must be shown.

Returns: 0 on success or a negative error code on failure.

◆ getConsole()

Console * CRM64Pro::GUIMgr::getConsole ( Sint32 idGUI = GUI_CONSOLE )

Get a pointer to a Console using its handler.

By default it returns the default console.

Parameters

idGUI GUI id.

Returns: nullptr the Console was not found.; A pointer to the Console object.

◆ getDebugWindow()

DebugWindow * CRM64Pro::GUIMgr::getDebugWindow ( Sint32 idGUI = 0 )

Get a pointer to a DebugWindow using its handler.

Parameters

idGUI GUI id. With GUI_CONSOLE (default value), it returns the default console.

Returns: nullptr the DebugWindow was not found.; A pointer to the DebugWindow object.

◆ load() [1/2]

Sint32 CRM64Pro::GUIMgr::load	(	const string &	sFileCDC,
		const string &	sName
	)

Load a panel and its widgets stored in a CDC file.

The GUI Manager has the ability of sharing Panel ids based on the name as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.

Parameters

sFileCDC	string containing the [directory]+filename. Directory separators '\' and '/' are supported.
sName	string with the panel name (maximum size of 64 characters).

Returns: 0 or greater on success(the Panel id) or a negative error code on failure.

◆ load() [2/2]

Sint32 CRM64Pro::GUIMgr::load	(	Sint32	idCDC,
		const string &	sName
	)

Load a panel and its widgets stored in a CDC file.

The GUI Manager has the ability of sharing Panel ids based on the name as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.

Parameters

idCDC	CDC id.
sName	string with the panel name (maximum size of 64 characters).

Returns: 0 or greater on success(the Panel id) or a negative error code on failure.

◆ getFontWhiteAA()

Sint32 CRM64Pro::GUIMgr::getFontWhiteAA ( )

Get the built-in white font.

Internally, it is used by default for all GUI systems.
It is created from a CourierNew 10 with antialiasing.

Returns: greater than 0 on success(the Font id) or a negative error code on failure.

◆ getFontBlack()

Sint32 CRM64Pro::GUIMgr::getFontBlack ( )

Get the built-in black font.

It is created from an Arial 12 without antialising.

Returns: greater than 0 on success(the Font id) or a negative error code on failure.

◆ getIconInfo()

Sint32 CRM64Pro::GUIMgr::getIconInfo ( )

Get the built-in info icon.

Returns: greater than 0 on success(the image id) or a negative error code on failure.

◆ getIconWarning()

Sint32 CRM64Pro::GUIMgr::getIconWarning ( )

Get the built-in warning icon.

Returns: greater than 0 on success(the image id) or a negative error code on failure.

◆ getIconError()

Sint32 CRM64Pro::GUIMgr::getIconError ( )

Get the built-in error icon.

Returns: greater than 0 on success(the image id) or a negative error code on failure.

◆ info() [2/4]

Sint32 CRM64Pro::Console::info ( Sint32 iMode = 0 )

Request Console information.

For displaying the information, it uses the default log.

Parameters

iMode unused for the time being.

Returns: 0 on success or a negative error code on failure.

◆ getName() [1/3]

Sint32 CRM64Pro::Console::getName ( string & sName )

Get the name.

Parameters

sName a string containing the object name.

Returns: 0 on success or a negative error code on failure.

◆ getID() [1/3]

Uint32 CRM64Pro::Console::getID ( )

Get the ID.

Returns: the object ID.

◆ baseWidget() [1/3]

Widget & CRM64Pro::Console::baseWidget ( )

Get the reference to base Widget for this object.

Returns: a reference to the base Widget.

◆ attachTo() [1/3]

Sint32 CRM64Pro::Console::attachTo ( Sint32 idScreen )

Attach this console to a screen.

Parameters

idScreen a valid screen handle.
By default, the console is attached to the default screen(0).

Returns: 0 on success or a negative error code on failure.

◆ print()

Sint32 CRM64Pro::Console::print	(	const char *	format,
			...
	)

Print a formatted message to the console.

Parameters

format	format control, same as printf() function.
...	optional arguments, same as printf() function.

Returns: 0 on success or a negative error code on failure.

Note: If the baseWidget is disabled (C64_STATUS_DISABLED), this method does nothing.

◆ vPrint()

Sint32 CRM64Pro::Console::vPrint	(	const char *	format,
		va_list	args
	)

Print a formatted message to the console.

Parameters

format	format control, same as printf() function.
args	pointer to list of arguments, same as vprintf() function.

Returns: 0 on success or a negative error code on failure.

Note: If the baseWidget is disabled (C64_STATUS_DISABLED), this method does nothing.

◆ addCmdHandler()

Sint32 CRM64Pro::Console::addCmdHandler	(	const string &	sCommandName,
		const string &	sCommandHelp,
		Sint32()(vector< string > , Console *pCon)	cmdFunc
	)

Add a new command handler to the console.

Parameters

sCommandName	string with the command name (must be unique). There are some internal and reserved commands: 'con' - Console control. 'dw' - Debug Window control. 'help' - List all commands.
sCommandHelp	string with a brief command description.
cmdFunc	pointer to the function handler. The vector<string> parameter contains the full tokenized command and Console, a pointer to the console that called it. Must return 0 when succeed or a negative value on error.

Returns: 0 on success or a negative error code on failure.

◆ executeCmd()

Sint32 CRM64Pro::Console::executeCmd ( const string & sCmd )

Execute a command on this console.

Parameters

sCmd	string with the command plus arguments to be executed by this console.

Returns: 0 on success or a negative error code on failure.

Note: If the baseWidget is disabled (C64_STATUS_DISABLED), this method does nothing.

◆ info() [3/4]

Sint32 CRM64Pro::DebugWindow::info ( Sint32 iMode = 0 )

Request DebugWindow information.

For displaying the information, it uses the default log.

Parameters

iMode unused for the time being.

Returns: 0 on success or a negative error code on failure.

◆ getName() [2/3]

Sint32 CRM64Pro::DebugWindow::getName ( string & sName )

Get the name.

Parameters

sName a string containing the object name.

Returns: 0 on success or a negative error code on failure.

◆ getID() [2/3]

Uint32 CRM64Pro::DebugWindow::getID ( )

Get the ID.

Returns: the object ID.

◆ baseWidget() [2/3]

Widget & CRM64Pro::DebugWindow::baseWidget ( )

Get the reference to base Widget for this object.

Returns: a reference to the base Widget.

◆ addWatch()

Sint32 CRM64Pro::DebugWindow::addWatch	(	const string &	sName,
		Sint32 *	iIntegerVar,
		double *	dDoubleVar = `nullptr`
	)

Add a watch.

Parameters

sName	watch name. Must be unique.
iIntegerVar	a pointer to an integer variable to be associated to this watch. nullptr for doing nothing.
dDoubleVar	a pointer to a double variable to be associated to this watch. nullptr for doing nothing.

Returns: 0 on sucess or a negative error code on failure.

Note: If the baseWidget is disabled (C64_STATUS_DISABLED), this method does nothing.

◆ removeWatch()

Sint32 CRM64Pro::DebugWindow::removeWatch ( const string & sName )

Remove a watch.

Parameters

sName watch name.

Returns: 0 on success or a negative error code on failure.

Note: If the baseWidget is disabled (C64_STATUS_DISABLED), this method does nothing.

◆ attachTo() [2/3]

Sint32 CRM64Pro::DebugWindow::attachTo ( Sint32 idScreen )

Attach this debugwindow to a screen.

Parameters

idScreen a valid screen handle.
By default, the debugwindow is attached to the default screen(0).

Returns: 0 on success or a negative error code on failure.

◆ setRefreshInterval()

Sint32 CRM64Pro::DebugWindow::setRefreshInterval ( Sint32 iRefresh )

Set the refresh interval.

Parameters

iRefresh time interval in milliseconds for refreshing the value of the watches. By default it is set to 500ms.

Returns: 0 on success or a negative error code on failure.

◆ getRefreshInterval()

Sint32 CRM64Pro::DebugWindow::getRefreshInterval ( )

Get the refresh interval.

Returns: 0 or greater on success(the refresh interval) or a negative error code on failure.

◆ info() [4/4]

Sint32 CRM64Pro::Panel::info ( Sint32 iMode = 0 )

Request Panel information.

For displaying the information, it uses the default log.

Parameters

iMode unused for the time being.

Returns: 0 on success or a negative error code on failure.

◆ getName() [3/3]

Sint32 CRM64Pro::Panel::getName ( string & sName )

Get the name.

Parameters

sName a string containing the object name.

Returns: 0 on success or a negative error code on failure.

◆ getID() [3/3]

Uint32 CRM64Pro::Panel::getID ( )

Get the ID.

Returns: the object ID.

◆ baseWidget() [3/3]

Widget & CRM64Pro::Panel::baseWidget ( )

Get the reference to base Widget for this object.

Returns: a reference to the base Widget.

◆ attachTo() [3/3]

Sint32 CRM64Pro::Panel::attachTo ( Sint32 idScreen )

Attach this panel to a screen.

Parameters

idScreen a valid screen handle.
By default, the panel is attached to the default screen(0).

Returns: 0 on success or a negative error code on failure.

◆ getScreen()

Sint32 CRM64Pro::Panel::getScreen ( )

Return the screen id where this panel is attached to.

Returns: the screen id.

◆ createWidget()

Sint32 CRM64Pro::Panel::createWidget	(	const string &	sName,
		eWidgetType	eWT,
		Sint32	iWID
	)

Create a widget.

Parameters

sName	The name for the widget. The object name must be unique and with a maximum size of 64 characters or will be truncated.
eWT	Widget type. Check eWidgetType for further information.
iWID	unsigned integer with the unique Widget ID.

Returns: 0 on success or a negative error code on failure.

Note: Different widget versions could be present but at creation time, we always use the newer one available although older ones can still be loaded.
Created widgets have the status set to enabled but hidden (C64_STATUS_HIDDEN).

◆ getWidget()

Widget * CRM64Pro::Panel::getWidget ( Sint32 iWID )

Get a pointer to a Widget using its handler.

Parameters

iWID	Widget id.

Returns: nullptr the Widget was not found.; A pointer to the Widget object.

◆ closeWidget()

Sint32 CRM64Pro::Panel::closeWidget ( Sint32 iWID )

Close and destroy a Widget.

Parameters

iWID	0 for closing all Widgets or the Widget id.

Returns: 0 on success or a negative error code on failure.

Note: If you forget to close a widget, it will be automatically closed once the panel is closed.

◆ type()

Sint32 CRM64Pro::Panel::type	(	ePanelType	ePT = `PT_RETRIEVE`,
		Sint32	iTime = `0`
	)

Set or get panel type.

Parameters

ePT	Panel type. Check ePanelType for further information.
iTime	Time to live (in milliseconds) for a panel type PT_EPHIMERAL. The minimum value is 1000ms.

Returns: 0 on success or a negative error code on failure.

◆ save() [1/2]

Sint32 CRM64Pro::Panel::save ( const string & sFileCDC )

Save the panel and all its widgets to a CDC file.

Widgets images/sprites will also be saved in to the same CDC file.

Parameters

sFileCDC string containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.

Returns: 0 or greater on success or a negative error code on failure.

Note: If the panel, widget or any associated image/sprite already exist, they will be overwritten.

◆ save() [2/2]

Sint32 CRM64Pro::Panel::save ( Sint32 idCDC )

Save the panel and all its widgets to a CDC file.

Widgets images/sprites will also be saved in to the same CDC file.

Parameters

idCDC CDC id.

Returns: 0 or greater on success or a negative error code on failure.

Note: If the panel, widget or any associated image/sprite already exist, they will be overwritten.

Detailed Description

Classes

Macros

Enumerations

Functions

Macro Definition Documentation

◆ GUI_PANEL

◆ GUI_CONSOLE

◆ GUI_DEBUGWINDOW

Enumeration Type Documentation

◆ ePanelType

Function Documentation

◆ info() [1/4]

◆ create()

◆ close()

◆ getNum()

◆ setName()

◆ getPanel()

◆ getPanelFocus()

◆ setPanelFocus()

◆ getConsole()

◆ getDebugWindow()

◆ load() [1/2]

◆ load() [2/2]

◆ getFontWhiteAA()

◆ getFontBlack()

◆ getIconInfo()

◆ getIconWarning()

◆ getIconError()

◆ info() [2/4]

◆ getName() [1/3]

◆ getID() [1/3]

◆ baseWidget() [1/3]

◆ attachTo() [1/3]

◆ print()

◆ vPrint()

◆ addCmdHandler()

◆ executeCmd()

◆ info() [3/4]

◆ getName() [2/3]

◆ getID() [2/3]

◆ baseWidget() [2/3]

◆ addWatch()

◆ removeWatch()

◆ attachTo() [2/3]

◆ setRefreshInterval()

◆ getRefreshInterval()

◆ info() [4/4]

◆ getName() [3/3]

◆ getID() [3/3]

◆ baseWidget() [3/3]

◆ attachTo() [3/3]

◆ getScreen()

◆ createWidget()

◆ getWidget()

◆ closeWidget()

◆ type()

◆ save() [1/2]

◆ save() [2/2]