CRM64Pro GDK v0.13.0
A free cross-platform game development kit built on top of SDL 3.0
Loading...
Searching...
No Matches

Description

GUI Manager for handling panels, consoles and debug windows [v25.12.0].

Overview

The GUI module provides a complete graphical user interface system through the GUI Manager. It handles three main object types: Panels (widget containers), Consoles (command-line interfaces) and Debug Windows (variable monitors). All GUI objects are attached to screens and support multi-screen configurations.

Key features

  • Panel system: Widget containers with time-to-live support and automatic/manual rendering
  • Console: In-game command-line interface with command registration and history
  • Debug window: Real-time variable monitoring for development and debugging
  • Multi-screen: GUI objects can be attached to any valid screen
  • CDC storage: Save and load GUI configurations using CDC v1.x specification

GUI object types

PanelContainer for widgets. Supports time-to-live (TTL) for ephemeral panels. Sharing manager behavior
ConsoleCommand-line interface with prompt, command history and custom command registration. Captures text input focus while allowing other interactions
DebugWindowVariable watch window for monitoring integer and double values with configurable refresh interval

Rendering order

ConsoleAlways rendered on top of DebugWindows and Panels
DebugWindowAlways rendered on top of Panels
PanelAutomatic rendering order by focus

Console features

Command registrationRegister custom commands with help text and callback functions
Built-in commands'help', 'con' and 'dw' commands available by default
Command historyNavigate through previously entered commands
Input focusCaptures text input while allowing other GUI interactions

DebugWindow features

Variable watchMonitor Sint32 (integer) and double variables in real-time
Refresh intervalConfigurable update frequency for watched variables
Named watchesEach watched variable has a display name for easy identification

Manager types

PanelSharing manager: returns shared ID for existing panels based on name
ConsoleStandard manager: objects must be unique by name
DebugWindowStandard manager: objects must be unique by name

Best practices

  • Use GUI objects from the main thread only for thread safety
  • Leverage panel TTL (time-to-live) for temporary notifications or tooltips
  • Register custom console commands during initialization for in-game debugging
  • Use DebugWindow during development to monitor critical game variables in real-time
  • Attach GUI objects to the appropriate screen in multi-screen configurations
  • Access the manager exclusively through Main::IGUIMgr()
Note
The GUI Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::IGUIMgr() method.
The GUI Manager is automatically released when Main::Terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.

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 iMode=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 () const
 Get number of loaded objects.
Sint32 CRM64Pro::GUIMgr::setName (Sint32 idGUI, const string &sName)
 Change the object name.
PanelCRM64Pro::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.
DebugWindowCRM64Pro::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::remove (Sint32 idCDC, const string &sName)
 Remove 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.
WidgetCRM64Pro::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.
WidgetCRM64Pro::DebugWindow::baseWidget ()
 Get the reference to base Widget for this object.
Sint32 CRM64Pro::DebugWindow::addWatch (const string &sName, Sint32 *iIntegerVar, float *fFloatVar=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.
Uint64 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.
WidgetCRM64Pro::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.
WidgetCRM64Pro::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

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.

Writes information to the default log.

Parameters
iMode-1 for Manager info only. 0 (default) for Manager and all Objects. A positive GUI id for Manager and that specific Object.
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
sNameThe name for the GUI object (e.g. 'myPanel'). Must be unique and max 64 characters (truncated if longer).
iTypeGUI Object type (GUI_PANEL, GUI_CONSOLE or GUI_DEBUGWINDOW) OR'ed with version (10 = v1.0, only version supported). Default is GUI_PANEL with v1.0.
Returns
greater than 0 on success (the GUI id) or a negative error code on failure.
Note
All GUI Objects are attached to the default screen by default but can be changed via attachTo() methods. Created objects have baseWidget enabled but hidden (C64_STATUS_HIDDEN).

◆ close()

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

Close and destroy a GUI object.

Parameters
idGUI0 for closing all GUI objects or a specific GUI id. The default console cannot be removed. Shared Panel ids are not removed until the last owner calls this method.
Returns
0 on success, or a negative error code on failure.
Note
Unclosed objects are automatically closed when the GDK terminates.

◆ getNum()

Sint32 CRM64Pro::GUIMgr::getNum ( ) const

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
idGUIGUI id. Can be a Panel, Console or DebugWindow.
sNameThe name to give to the object (e.g. 'myPanel'). Must be unique and max 64 characters (truncated if longer).
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
idGUIPanel 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
idGUIthe 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
idGUIConsole GUI id. With GUI_CONSOLE (default value), it returns the default console.
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
idGUIDebugWindow GUI id.
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 can share Panel ids based on name, checking if already loaded before creating new ones.

Parameters
sFileCDCstring containing [directory]+filename. Directory separators '\' and '/' are supported.
sNamestring with the panel name (max 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
idCDCCDC id.
sNamestring 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.

◆ remove()

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

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

Parameters
idCDCCDC id.
sNamestring with the panel name (max 64 characters).
Returns
0 on success, or a negative error code on failure.
Note
This permanently removes the panel block and all associated widget blocks from the archive.

◆ getFontWhiteAA()

Sint32 CRM64Pro::GUIMgr::getFontWhiteAA ( )

Get the built-in white font.

Used by default for all GUI systems. Created from 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.

Writes information to the default log.

Parameters
iModeunused 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
sNamea 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
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
idScreena valid screen handle. Default is 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
formatformat 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
formatformat control, same as printf() function.
argspointer 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(* cmdFunc )(vector< string > *, Console *pCon) )

Add a new command handler to the console.

Parameters
sCommandNamestring with the command name (must be unique). Reserved commands: 'con' (Console control), 'dw' (Debug Window control), 'help' (List all commands).
sCommandHelpstring with a brief command description.
cmdFuncpointer to the function handler. The vector<string*> parameter contains the tokenized command and Console* is the calling console. Must return 0 on success or negative 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
sCmdstring 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.

Writes information to the default log.

Parameters
iModeunused 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
sNamea 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
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,
float * fFloatVar = nullptr )

Add a watch.

Parameters
sNamewatch name. Must be unique.
iIntegerVara pointer to an integer variable to be associated to this watch. nullptr for doing nothing.
fFloatVara pointer to a float 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
sNamewatch 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
idScreena valid screen handle. Default is 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
iRefreshtime 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()

Uint64 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.

Writes information to the default log.

Parameters
iModeunused 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
sNamea 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
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
idScreena valid screen handle. Default is 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
sNameThe widget name. Must be unique and max 64 characters (truncated if longer).
eWTWidget type. Check ::eWidgetType for further information.
iWIDunsigned integer with the unique Widget ID.
Returns
0 on success, or a negative error code on failure.
Note
Different widget versions may exist but creation always uses the newest. Created widgets are enabled but hidden (C64_STATUS_HIDDEN).

◆ getWidget()

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

Get a pointer to a Widget using its handler.

Parameters
iWIDWidget 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
iWID0 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
ePTPanel type. Check ::ePanelType for further information.
iTimeTime to live (in milliseconds) for PT_EPHEMERAL panels. Minimum 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 to the same CDC file.

Parameters
sFileCDCstring containing [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
idCDCCDC 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.