Description

Widget classes for building graphical user interfaces inside Panels [v25.12.0].

Overview

The Widget module provides all widget classes that can be used inside Panels. Widgets are the building blocks of the GUI system, ranging from simple display elements like labels and images to interactive controls like buttons, sliders and text boxes. Each widget supports multiple visual states with customizable skins.

Key features

State-based skinning: 5 visual states with independent appearance settings
Flexible backgrounds: Color, image or sprite backgrounds per state
Border customization: Configurable border width, color and corner radius
Font support: Per-state font assignment for text rendering
Keyboard activation: Assign keyboard shortcuts to interactive widgets
Fading effects: Built-in show/hide transitions
Drag and drop: Optional drag and drop support for widgets

Widget categories

Simple widgets

Label	Static text display
Image	Static image display
Button	Clickable button with keyboard shortcut support
CheckBox	Toggle control with optional grouping for radio-button behavior
ProgressBar	Progress indicator with value and range
HSlider	Horizontal slider control for value selection
VSlider	Vertical slider control for value selection

Advanced widgets

TextBox	Multi-line text input with cursor, scrolling and input focus handling
ListBox	Scrollable list with item selection support

Widget states

Each widget supports 5 visual states, each with independent skin properties:

WS_DEFAULT	Normal/idle state
WS_HOVERED	Mouse cursor is over the widget
WS_PRESSED	Widget is being pressed/clicked
WS_DISABLED	Widget is disabled and non-interactive
WS_FOCUSED	Widget has input focus

Skin properties

Each state can have the following appearance properties:

Background color	RGB color for solid background
Background image	Image ID for image background
Background sprite	Sprite ID and animation for animated background
Border	RGBA color, width and corner radius
Font	Font ID for text rendering

Common widget properties

Position and size	Body rectangle defining widget bounds (minimum 8×8 pixels)
Margins	Top, right, bottom, left margins for content
Alpha	Transparency level (0-255)
Text	Display text with positioning rectangle
Keyboard activation	SDL_Keycode for keyboard shortcut
Value and range	Current value and maximum range for sliders and progress bars

Update return codes

Widget update methods return codes indicating their current status:

WIDGET_UPDATE_HIDDEN (-1)	Widget is not shown
WIDGET_UPDATE_NOTHING (0)	Widget is idle (not selected, pressed or active)
WIDGET_UPDATE_ACTIVITY (1)	Widget is active (selected, pressed or performing action)
WIDGET_UPDATE_CLOSEME (2)	Widget requests panel closure (ephemeral panels)

Additional flags can be combined with return codes:

FLAG_NOEVENT (16)	Widget does not handle events
FLAG_DRAGDROP (32)	Widget is performing drag and drop
FLAG_INPUTFOCUS (64)	Widget has input focus
FLAG_LCLICK (128)	Widget received left mouse click
FLAG_CBGROUP (256)	Checkbox in a group was set (others in group reset)

ProgressBar notes

Without image/sprite	Requires setSize() to define widget dimensions and calculate value slices
With image/sprite	Size is calculated automatically from the background asset
State requirements	Requires at least WS_PRESSED and WS_HOVERED states defined with equal sizes

Best practices

Define all required widget states (especially WS_DEFAULT, WS_HOVERED, WS_PRESSED) for interactive widgets
Use consistent sizing for background images/sprites across all states
Group CheckBox widgets using setGroup() to create radio-button behavior
Set keyboard shortcuts on frequently used buttons for accessibility
Use margins to properly position text content within widgets
For ProgressBar without image/sprite, always call setSize() before setRange()
Handle update return codes and flags appropriately in your game loop
Use fading effects (show/hide) for smooth widget transitions

Classes
class	CRM64Pro::Widget
	Widget Object. More...

Macros
#define	WIDGET_FEATURE_FADE 0x00010000
#define	WIDGET_FEATURE_DRAGDROP 0x00020000
#define	WIDGET_FEATURE_ENCLOSE 0x00040000
#define	WIDGET_FEATURE_DETACH 0x00080000
#define	WIDGET_FEATURE_BGFIT 0x00100000
#define	WIDGET_FEATURE_BGDISABLE 0x00200000
#define	WIDGET_FEATURE_EVENTS 0x00400000
#define	WIDGET_FEATURE_MOUSEOVER 0x00800000
#define	WIDGET_FEATURE_LOSTFOCUS 0x01000000
#define	WIDGET_FEATURE_MULTILINE 0x02000000
#define	WIDGET_FEATURE_READONLY 0x04000000
#define	WIDGET_FEATURE_AUTOSORT 0x08000000

Enumerations
enum	CRM64Pro::eWidgetState { CRM64Pro::WS_DEFAULT = -1 , CRM64Pro::WS_NORMAL = 0 , CRM64Pro::WS_HOVERED = 1 , CRM64Pro::WS_PRESSED = 2 , CRM64Pro::WS_ACTION = 3 , CRM64Pro::WS_DEACTIVATED = 4 }
	Widget state. More...
enum	CRM64Pro::eWidgetType { CRM64Pro::WT_BASE = 0 , CRM64Pro::WT_LABEL = 1 , CRM64Pro::WT_IMAGE = 2 , CRM64Pro::WT_BUTTON = 4 , CRM64Pro::WT_CHECKBOX = 8 , CRM64Pro::WT_PROGRESSBAR = 16 , CRM64Pro::WT_HSLIDER = 32 , CRM64Pro::WT_VSLIDER = 64 , CRM64Pro::WT_TEXTBOX = 128 , CRM64Pro::WT_LISTBOX = 256 }
	Widget type. More...

Functions
virtual Sint32	CRM64Pro::Widget::info (Sint32 iMode=0)
	Request Widget object information.
Sint32	CRM64Pro::Widget::disable ()
	Disable a widget.
Sint32	CRM64Pro::Widget::show ()
	Show a widget.
Sint32	CRM64Pro::Widget::hide ()
	Hide a widget.
Sint32	CRM64Pro::Widget::status ()
	Get the widget status.
Sint32	CRM64Pro::Widget::features (Sint32 iFeatures)
	Set or get advanced features.
virtual Sint32	CRM64Pro::Widget::setSize (Sint32 iWidth, Sint32 iHeight)
	Set the size.
Sint32	CRM64Pro::Widget::getSize (Sint32 iWidth, Sint32 iHeight)
	Get the size.
Sint32	CRM64Pro::Widget::setPosition (const Position &posX=Position(PH_CENTER), const Position &posY=Position(PH_CENTER))
	Set the position.
Sint32	CRM64Pro::Widget::getPosition (Position posX, Position posY)
	Get the position.
virtual Sint32	CRM64Pro::Widget::setMargin (Sint32 iTop, Sint32 iRight, Sint32 iBottom, Sint32 iLeft)
	Set the margins.
Sint32	CRM64Pro::Widget::getMargin (Sint32 iTop, Sint32 iRight, Sint32 iBottom, Sint32 iLeft)
	Get the margins.
virtual Sint32	CRM64Pro::Widget::setThumbSize (Sint32 iSize)
	Set a fixed size for the slider thumb.
Sint32	CRM64Pro::Widget::setAlphaMod (Uint8 iAlpha)
	Set alpha modulation used for rendering this widget.
Uint8	CRM64Pro::Widget::getAlphaMod ()
	Get alpha modulation used for rendering this widget.
virtual Sint32	CRM64Pro::Widget::setText (const string &sText, const Position &posX=Position(PH_CENTER), const Position &posY=Position(PH_CENTER))
	Set the text (Global replace).
virtual Sint32	CRM64Pro::Widget::getText (string &sText, Sint32 iParam1=-1)
	Get the text.
virtual string	CRM64Pro::Widget::getLine (Sint32 iLineIndex)
	Get a specific line of text.
virtual Sint32	CRM64Pro::Widget::getLineCount ()
	Get the total number of lines.
virtual Sint32	CRM64Pro::Widget::appendText (const string &sText)
	Append text to the current stream/cursor position.
virtual Sint32	CRM64Pro::Widget::appendLine (const string &sText)
	Add a new line at the bottom.
virtual Sint32	CRM64Pro::Widget::setLine (Sint32 iLineIndex, const string &sText)
	Replace a specific line.
virtual Sint32	CRM64Pro::Widget::insertLine (Sint32 iLineIndex, const string &sText)
	Insert a new line at a specific index.
virtual Sint32	CRM64Pro::Widget::removeLine (Sint32 iLineIndex)
	Remove a specific line.
virtual Sint32	CRM64Pro::Widget::addItem (const string &sItem)
	Add an item to the list.
virtual Sint32	CRM64Pro::Widget::insertItem (Sint32 iIndex, const string &sItem)
	Insert an item at a specific index.
virtual Sint32	CRM64Pro::Widget::removeItem (Sint32 iIndex)
	Remove an item at a specific index.
virtual Sint32	CRM64Pro::Widget::clearItems ()
	Clear all items from the list.
virtual Sint32	CRM64Pro::Widget::selectItem (Sint32 iIndex)
	Select an item in the list.
virtual string	CRM64Pro::Widget::getSelectedItem ()
	Get the selected item text.
virtual Sint32	CRM64Pro::Widget::setKey (SDL_Keycode keycode)
	Set the assigned key.
SDL_Keycode	CRM64Pro::Widget::getKey ()
	Get the assigned key.
virtual Sint32	CRM64Pro::Widget::setValue (Sint32 iValue)
	Set a value.
virtual Sint32	CRM64Pro::Widget::getValue ()
	Get current value.
virtual Sint32	CRM64Pro::Widget::getValueGroup (Sint32 iGroup)
	Get enabled checkbox in a group.
virtual Sint32	CRM64Pro::Widget::setRange (Sint32 iRange)
	Set the range.
virtual Sint32	CRM64Pro::Widget::getRange ()
	Get current range.
Sint32	CRM64Pro::Widget::setState (eWidgetState eWS=WS_NORMAL)
	Set the widget state.
virtual Sint32	CRM64Pro::Widget::setScroll (Sint32 iUnitsX, Sint32 iUnitsY)
	Modify the widget scroll.
virtual Sint32	CRM64Pro::Widget::getScroll (Sint32 iUnitsX, Sint32 iUnitsY)
	Get the widget current scroll.
virtual Sint32	CRM64Pro::Widget::getVisibleItems (Sint32 iUnitsX, Sint32 iUnitsY)
	Get visible items.
virtual Sint32	CRM64Pro::Widget::setFont (Sint32 idFont, eWidgetState eWS=WS_DEFAULT)
	Set the font.
Sint32	CRM64Pro::Widget::getFont (eWidgetState eWS=WS_NORMAL)
	Get the font.
virtual Sint32	CRM64Pro::Widget::setGroup (Sint32 iGroup)
	Set the checkbox group.
virtual Sint32	CRM64Pro::Widget::getGroup ()
	Get the checkbox group.
Sint32	CRM64Pro::Widget::setBorderWidth (Sint32 iWidth, eWidgetState eWS=WS_DEFAULT)
	Set the border width.
Sint32	CRM64Pro::Widget::getBorderWidth (eWidgetState eWS=WS_NORMAL)
	Get the border width.
Sint32	CRM64Pro::Widget::setBorderCorner (Sint32 iRad, eWidgetState eWS=WS_DEFAULT)
	Set the border corner radius.
Sint32	CRM64Pro::Widget::getBorderCorner (eWidgetState eWS=WS_NORMAL)
	Get the border corner radius.
Sint32	CRM64Pro::Widget::setBorderColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA, eWidgetState eWS=WS_DEFAULT)
	Set the border color.
Sint32	CRM64Pro::Widget::getBorderColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA, eWidgetState eWS=WS_NORMAL)
	Get the border color.
Sint32	CRM64Pro::Widget::setBgColor (Uint8 iR, Uint8 iG, Uint8 iB, eWidgetState eWS=WS_DEFAULT)
	Set the background color.
Sint32	CRM64Pro::Widget::getBgColor (Uint8 iR, Uint8 iG, Uint8 *iB, eWidgetState eWS=WS_NORMAL)
	Get the background color.
Sint32	CRM64Pro::Widget::setBgImage (const string &sFileCDC, const string &sName, eWidgetState eWS=WS_NORMAL)
	Set the background image.
Sint32	CRM64Pro::Widget::setBgImage (Sint32 idCDC, const string &sName, eWidgetState eWS=WS_NORMAL)
	Set the background image.
Sint32	CRM64Pro::Widget::setBgImage (Sint32 idImage, eWidgetState eWS=WS_NORMAL)
	Set the background image.
Sint32	CRM64Pro::Widget::getBgImage (eWidgetState eWS=WS_NORMAL)
	Get the background image.
Sint32	CRM64Pro::Widget::setBgSprite (const string &sFileCDC, const string &sName, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
	Set the background sprite.
Sint32	CRM64Pro::Widget::setBgSprite (Sint32 idCDC, const string &sName, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
	Set the background sprite.
Sint32	CRM64Pro::Widget::setBgSprite (Sint32 idSprite, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
	Set the background sprite.
Sint32	CRM64Pro::Widget::getBgSprite (eWidgetState eWS=WS_NORMAL, Sint32 *iAnim=nullptr)
	Get the background sprite.
Sint32	CRM64Pro::Widget::setFunction (Sint32(stateFunc)(void , void ), void iParam1=nullptr, void *iParam2=nullptr, eWidgetState eWS=WS_ACTION)
	Set a function to be called on given state.

Macro Definition Documentation

◆ WIDGET_FEATURE_FADE

#define WIDGET_FEATURE_FADE 0x00010000

Widget feature: fading effect at showing and hiding time.

◆ WIDGET_FEATURE_DRAGDROP

#define WIDGET_FEATURE_DRAGDROP 0x00020000

Widget feature: allow to move the widget (drag&drop).

◆ WIDGET_FEATURE_ENCLOSE

#define WIDGET_FEATURE_ENCLOSE 0x00040000

Widget feature: enclose the widget inside its parent (default).

◆ WIDGET_FEATURE_DETACH

#define WIDGET_FEATURE_DETACH 0x00080000

Widget feature: the widget is detached from its parent.

◆ WIDGET_FEATURE_BGFIT

#define WIDGET_FEATURE_BGFIT 0x00100000

Widget feature: background image/sprite auto-fit to widget size.

◆ WIDGET_FEATURE_BGDISABLE

#define WIDGET_FEATURE_BGDISABLE 0x00200000

Widget feature: background rendering is disabled.

◆ WIDGET_FEATURE_EVENTS

#define WIDGET_FEATURE_EVENTS 0x00400000

Widget feature: allow the widget to process events and generate C64_EVENT_WIDGET event.

◆ WIDGET_FEATURE_MOUSEOVER

#define WIDGET_FEATURE_MOUSEOVER 0x00800000

Widget feature: allow the widget to generate C64_EVENT_WIDGET_MOUSEOVER events.

◆ WIDGET_FEATURE_LOSTFOCUS

#define WIDGET_FEATURE_LOSTFOCUS 0x01000000

Widget feature: allow the widget to generate C64_EVENT_WIDGET_LOSTFOCUS events.

◆ WIDGET_FEATURE_MULTILINE

#define WIDGET_FEATURE_MULTILINE 0x02000000

Widget feature: TextBox supports multiline text.

◆ WIDGET_FEATURE_READONLY

#define WIDGET_FEATURE_READONLY 0x04000000

Widget feature: TextBox on read-only mode.

◆ WIDGET_FEATURE_AUTOSORT

#define WIDGET_FEATURE_AUTOSORT 0x08000000

Widget feature: ListBox auto-sorting of items.

Enumeration Type Documentation

◆ eWidgetState

enum CRM64Pro::eWidgetState

Widget state.

Enumerator
WS_DEFAULT	Flag used for "setters" methods. Not a real state.
WS_NORMAL	Normal widget state.
WS_HOVERED	Mouse pointer is over the widget.
WS_PRESSED	Pressed widget state.
WS_ACTION	Action widget state.
WS_DEACTIVATED	Deactivated widget state.

◆ eWidgetType

enum CRM64Pro::eWidgetType

Widget type.

Enumerator
WT_BASE	Base widget.
WT_LABEL	Simple label widget.
WT_IMAGE	Simple image widget.
WT_BUTTON	Standard button widget.
WT_CHECKBOX	CheckBox widget.
WT_PROGRESSBAR	ProgressBar widget.
WT_HSLIDER	Horizontal slider widget.
WT_VSLIDER	Vertical slider widget.
WT_TEXTBOX	TextBox widget.
WT_LISTBOX	ListBox widget.

Function Documentation

◆ info()

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

virtual

Request Widget object information.

Writes information to the default log.

Parameters

iMode 0 (default) for stand-alone info call, or 1 when called from a nested info method.

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

◆ disable()

Sint32 CRM64Pro::Widget::disable ( )

Disable a widget.

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

◆ show()

Sint32 CRM64Pro::Widget::show ( )

Show a widget.

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

◆ hide()

Sint32 CRM64Pro::Widget::hide ( )

Hide a widget.

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

◆ status()

Sint32 CRM64Pro::Widget::status ( )

Get the widget status.

Returns: C64_STATUS_DISABLED (widget disabled), C64_STATUS_HIDDEN (enabled but hidden), or C64_STATUS_SHOWN (enabled and shown).

◆ features()

Sint32 CRM64Pro::Widget::features ( Sint32 iFeatures )

Set or get advanced features.

Check WIDGET_FEATURE_x defines for a list of supported features.

Parameters

iFeatures 32bits signed integer with desired flags. Enabling a currently enabled flag disables it. Use -1 to get current flags.

Returns: greater than 0 on success (current features) or a negative error code on failure.

◆ setSize()

Sint32 CRM64Pro::Widget::setSize	(	Sint32	iWidth,
		Sint32	iHeight )

virtual

Set the size.

Parameters

iWidth	widget width. Minimum width is 8.
iHeight	widget height. Minimum height is 8.

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

Note: The widget can be "resized" at any time but will never be greater than its parent.; Applicable to: All widgets.

◆ getSize()

Sint32 CRM64Pro::Widget::getSize	(	Sint32 *	iWidth,
		Sint32 *	iHeight )

Get the size.

Parameters

iWidth	pointer filled with widget width. If nullptr, value not retrieved.
iHeight	pointer filled with widget height. If nullptr, value not retrieved.

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

Note: Applicable to: All widgets.

◆ setPosition()

Sint32 CRM64Pro::Widget::setPosition	(	const Position &	posX = Position(PH_CENTER),
		const Position &	posY = Position(PH_CENTER) )

Set the position.

For "base" widgets, position is relative to the screen. For other widgets, position is relative to the "base" widget.

Parameters

posX	widget X position. Check ::ePositionHelpers enum for position helpers. Default ::PH_CENTER.
posY	widget Y position. Check ::ePositionHelpers enum for position helpers. Default ::PH_CENTER.

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

Note: The widget can be moved at any time.; Applicable to: All widgets.

◆ getPosition()

Sint32 CRM64Pro::Widget::getPosition	(	Position *	posX,
		Position *	posY )

Get the position.

For "base" widgets, position is relative to the screen. For other widgets, position is relative to the "base" widget.

Parameters

posX	pointer filled with widget X position. If nullptr, value not retrieved.
posY	pointer filled with widget Y position. If nullptr, value not retrieved.

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

Note: Applicable to: All widgets.

◆ setMargin()

Sint32 CRM64Pro::Widget::setMargin	(	Sint32	iTop,
		Sint32	iRight,
		Sint32	iBottom,
		Sint32	iLeft )

virtual

Set the margins.

By default, the margins are set to 3.

Parameters

iTop	top margin in pixels.
iRight	right margin in pixels.
iBottom	bottom margin in pixels.
iLeft	left margin in pixels.

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

Note: The widget margins can be modified at any time.; Applicable to: All widgets.

◆ getMargin()

Sint32 CRM64Pro::Widget::getMargin	(	Sint32 *	iTop,
		Sint32 *	iRight,
		Sint32 *	iBottom,
		Sint32 *	iLeft )

Get the margins.

Parameters

iTop	pointer filled with top margin in pixels. If nullptr, value not retrieved.
iRight	pointer filled with right margin in pixels. If nullptr, value not retrieved.
iBottom	pointer filled with bottom margin in pixels. If nullptr, value not retrieved.
iLeft	pointer filled with left margin in pixels. If nullptr, value not retrieved.

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

Note: Applicable to: All widgets.

◆ setThumbSize()

Sint32 CRM64Pro::Widget::setThumbSize ( Sint32 iSize )

virtual

Set a fixed size for the slider thumb.

This method overrides the automatic size calculation that works fine for native or Images. It is mandatory to use this when using Sprites as the background, otherwise prevent the slider from moving.

Parameters

iSize The specific width for a horizontal slider thumb or height for vertial slider thumb in pixels.

Returns: 0 on success, or error code.

Note: Applicable to: WT_HSLIDER, WT_VSLIDER only.

◆ setAlphaMod()

Sint32 CRM64Pro::Widget::setAlphaMod ( Uint8 iAlpha )

Set alpha modulation used for rendering this widget.

Parameters

iAlpha It ranges from 255 (opaque) to 0 (fully transparent).

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

◆ getAlphaMod()

Uint8 CRM64Pro::Widget::getAlphaMod ( )

Get alpha modulation used for rendering this widget.

Returns: It ranges from 255 (opaque) to 0 (fully transparent).

◆ setText()

Sint32 CRM64Pro::Widget::setText	(	const string &	sText,
		const Position &	posX = Position(PH_CENTER),
		const Position &	posY = Position(PH_CENTER) )

virtual

Set the text (Global replace).

Parameters

sText	Text string to set.
posX	For WT_LABEL/WT_BUTTON/WT_CHECKBOX: caption X position. Default PH_CENTER. (See ::Position struct).
posY	For WT_LABEL/WT_BUTTON/WT_CHECKBOX: caption X position. Default PH_CENTER. (See ::Position struct).

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

Note: Applicable to: WT_LABEL, WT_BUTTON, WT_CHECKBOX, WT_IMAGE and WT_TEXTBOX.; For WT_TEXTBOX (Single-line): Replaces the current text.; For WT_TEXTBOX (Multi-line): Clears all lines and sets this text as the first line.

◆ getText()

Sint32 CRM64Pro::Widget::getText	(	string &	sText,
		Sint32	iParam1 = -1 )

virtual

Get the text.

Parameters

sText	String reference to the text.
iParam1	Unused for most widgets.

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

Note: Applicable to : WT_LABEL, WT_BUTTON, WT_CHECKBOX, WT_IMAGE and WT_TEXBOX.; For WT_TEXTBOX(Single-line): Returns the text.; For WT_TEXTBOX(Multi-line): Returns a single string containing all lines joined by newlines.

◆ getLine()

string CRM64Pro::Widget::getLine ( Sint32 iLineIndex )

virtual

Get a specific line of text.

Parameters

iLineIndex Line index [1,n] to retrieve.

Returns: The text string of the specified line, or empty string on failure/invalid index.

Note: Applicable to: WT_TEXTBOX only.; For Single-line: Ignores iLineIndex and returns the current text.

◆ getLineCount()

Sint32 CRM64Pro::Widget::getLineCount ( )

virtual

Get the total number of lines.

Returns: The total number of lines.

Note: Applicable to: WT_TEXTBOX only.; For Single-line: Always returns 1.

◆ appendText()

Sint32 CRM64Pro::Widget::appendText ( const string & sText )

virtual

Append text to the current stream/cursor position.

Parameters

sText Text string to append.

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

Note: Applicable to: WT_TEXTBOX only.; For Single-line: Appends to the end of the text.; For Multi-line: Appends to the end of the current cursor line (or last line if no cursor logic).

◆ appendLine()

Sint32 CRM64Pro::Widget::appendLine ( const string & sText )

virtual

Add a new line at the bottom.

Parameters

sText Text string for the new line.

Returns: The index of the new line (1-based), or a negative error code.

Note: Applicable to: WT_TEXTBOX only.; For Single-line: Returns -1 (Operation not supported).; For Multi-line: Pushes a new line to the end of the list.

◆ setLine()

Sint32 CRM64Pro::Widget::setLine	(	Sint32	iLineIndex,
		const string &	sText )

virtual

Replace a specific line.

Parameters

iLineIndex	Line index [1,n] to replace.
sText	New text string.

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

Note: Applicable to: WT_TEXTBOX only.; For Single-line: Ignores iLineIndex and replaces current text.

◆ insertLine()

Sint32 CRM64Pro::Widget::insertLine	(	Sint32	iLineIndex,
		const string &	sText )

virtual

Insert a new line at a specific index.

Parameters

iLineIndex	Line index [1,n] where the new line will be inserted.
sText	Text string for the new line.

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

Note: Applicable to: WT_TEXTBOX only.; For Single-line: Returns -1 (Operation not supported).; For Multi-line: Inserts at specified index, shifting subsequent lines down.

◆ removeLine()

Sint32 CRM64Pro::Widget::removeLine ( Sint32 iLineIndex )

virtual

Remove a specific line.

Parameters

iLineIndex Line index [1,n] to remove.

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

Note: Applicable to: WT_TEXTBOX only.; For Single-line: Clears the text (sets to empty string).; For Multi-line: Removes the line. If it was the last line, resets it to empty.

◆ addItem()

Sint32 CRM64Pro::Widget::addItem ( const string & sItem )

virtual

Add an item to the list.

Parameters

sItem Item text string to add.

Returns: The item index of the new item (1-based), or a negative error code on failure.

Note: Applicable to: WT_LISTBOX only.; If WIDGET_FEATURE_AUTOSORT is enabled, the index depends on the alphabetical position.

◆ insertItem()

Sint32 CRM64Pro::Widget::insertItem	(	Sint32	iIndex,
		const string &	sItem )

virtual

Insert an item at a specific index.

Parameters

iIndex	Item index [1,n] where the new item will be inserted.
sItem	Item text string to insert.

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

Note: Applicable to: WT_LISTBOX only.; If WIDGET_FEATURE_AUTOSORT is enabled, iIndex is ignored and the item is sorted automatically.

◆ removeItem()

Sint32 CRM64Pro::Widget::removeItem ( Sint32 iIndex )

virtual

Remove an item at a specific index.

Parameters

iIndex Item index [1,n] to remove.

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

Note: Applicable to: WT_LISTBOX only.

◆ clearItems()

Sint32 CRM64Pro::Widget::clearItems ( )

virtual

Clear all items from the list.

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

Note: Applicable to: WT_LISTBOX only.

◆ selectItem()

Sint32 CRM64Pro::Widget::selectItem ( Sint32 iIndex )

virtual

Select an item in the list.

Parameters

iIndex Item index [1,n] to select, or <1 to deselect.

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

Note: Applicable to: WT_LISTBOX only.

◆ getSelectedItem()

string CRM64Pro::Widget::getSelectedItem ( )

virtual

Get the selected item text.

Returns: The text string of the selected item, or empty string if no item is selected.

Note: Applicable to: WT_LISTBOX only.

◆ setKey()

Sint32 CRM64Pro::Widget::setKey ( SDL_Keycode keycode )

virtual

Set the assigned key.

Parameters

keycode SDL_Keycode to be assigned for enabling the ::WS_ACTION state.

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

Note: Applicable to: WT_BUTTON, WT_CHECKBOX only.

◆ getKey()

SDL_Keycode CRM64Pro::Widget::getKey ( )

Get the assigned key.

Returns: SDL_Keycode assigned for enabling the ::WS_ACTION state.

Note: Applicable to: WT_BUTTON, WT_CHECKBOX only.

◆ setValue()

Sint32 CRM64Pro::Widget::setValue ( Sint32 iValue )

virtual

Set a value.

Behavior varies by widget type.

Parameters

iValue value to set. WT_LISTBOX: select item [1,n] or <1 to deselect. WT_CHECKBOX: 0 disables, 1 enables (grouped checkboxes allow only one enabled). Other widgets: value in [0,iRange].

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

Note: If widget is disabled (C64_STATUS_DISABLED), this method does nothing.; Applicable to: WT_CHECKBOX, WT_PROGRESSBAR, WT_HSLIDER, WT_VSLIDER, WT_LISTBOX.

◆ getValue()

Sint32 CRM64Pro::Widget::getValue ( )

virtual

Get current value.

Behavior varies by widget type.

Returns: WT_PROGRESSBAR/WT_HSLIDER/WT_VSLIDER: value in [0,iRange]. WT_CHECKBOX: value [0,1] (individual, use getValueGroup() for group). WT_TEXTBOX: current line [1,n] or 0. WT_LISTBOX: selected item [1,n] or 0.

Note: Applicable to: WT_CHECKBOX, WT_PROGRESSBAR, WT_HSLIDER, WT_VSLIDER, WT_TEXTBOX, WT_LISTBOX.

◆ getValueGroup()

Sint32 CRM64Pro::Widget::getValueGroup ( Sint32 iGroup )

virtual

Get enabled checkbox in a group.

Parameters

iGroup id of the group to retrieve the enabled widget id.

Returns: For WT_CHECKBOX: widget id of enabled checkbox in group.

Note: Applicable to: WT_CHECKBOX only.

◆ setRange()

Sint32 CRM64Pro::Widget::setRange ( Sint32 iRange )

virtual

Set the range.

Behavior depends on widget type.

Parameters

iRange range of possible values (minimum 1). Only used with WT_PROGRESSBAR (also calculates proper size when image/sprite is associated), WT_HSLIDER, and WT_VSLIDER.

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

Note: Applicable to: WT_PROGRESSBAR, WT_HSLIDER, WT_VSLIDER only.

◆ getRange()

Sint32 CRM64Pro::Widget::getRange ( )

virtual

Get current range.

Behavior varies by widget type.

Returns: WT_PROGRESSBAR/WT_HSLIDER/WT_VSLIDER: current range. WT_TEXTBOX: number of lines. WT_LISTBOX: number of items.

Note: Applicable to: WT_PROGRESSBAR, WT_HSLIDER, WT_VSLIDER, WT_TEXTBOX, WT_LISTBOX.

◆ setState()

Sint32 CRM64Pro::Widget::setState ( eWidgetState eWS = WS_NORMAL )

Set the widget state.

Parameters

eWS	Widget state. Check ::eWidgetState for further information. Default is WS_NORMAL.

Returns: current widget range.

Note: Normally used to set WS_DEACTIVATED state or return to WS_NORMAL. Wrong usage may cause unexpected GUI behavior.

◆ setScroll()

Sint32 CRM64Pro::Widget::setScroll	(	Sint32	iUnitsX,
		Sint32	iUnitsY )

virtual

Modify the widget scroll.

Behavior varies by widget type: WT_TEXTBOX supports X and Y axes (units are characters); WT_LISTBOX supports Y axis only (units are items).

Parameters

iUnitsX	units to move scroll horizontally. Negative moves left, 0 no change, positive moves right.
iUnitsY	units to move scroll vertically. Negative moves up, 0 no change, positive moves down.

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

Note: Applicable to: WT_TEXTBOX, WT_LISTBOX only.

◆ getScroll()

Sint32 CRM64Pro::Widget::getScroll	(	Sint32 *	iUnitsX,
		Sint32 *	iUnitsY )

virtual

Get the widget current scroll.

Behavior varies by widget type: WT_TEXTBOX supports both parameters; WT_LISTBOX supports iUnitsY only.

Parameters

iUnitsX	pointer filled with current scroll position on X axis (units are characters). If nullptr, value not retrieved.
iUnitsY	pointer filled with current scroll position on Y axis (units are items). If nullptr, value not retrieved.

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

Note: Applicable to: WT_TEXTBOX, WT_LISTBOX only.

◆ getVisibleItems()

Sint32 CRM64Pro::Widget::getVisibleItems	(	Sint32 *	iUnitsX,
		Sint32 *	iUnitsY )

virtual

Get visible items.

Behavior varies by widget type: WT_TEXTBOX supports both parameters; WT_LISTBOX supports iUnitsY only.

Parameters

iUnitsX	pointer filled with maximum visible text characters on X axis. If nullptr, value not retrieved.
iUnitsY	pointer filled with maximum visible lines on Y axis. If nullptr, value not retrieved.

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

Note: Applicable to: WT_TEXTBOX, WT_LISTBOX only.

◆ setFont()

Sint32 CRM64Pro::Widget::setFont	(	Sint32	idFont,
		eWidgetState	eWS = WS_DEFAULT )

virtual

Set the font.

Parameters

idFont	Font id.
eWS	Widget state. Check ::eWidgetState for further information. Default is WS_DEFAULT (affects all states).

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

Note: Applicable to: WT_LABEL, WT_BUTTON, WT_CHECKBOX, WT_TEXTBOX, WT_LISTBOX.

◆ getFont()

Sint32 CRM64Pro::Widget::getFont ( eWidgetState eWS = WS_NORMAL )

Get the font.

Parameters

eWS	Widget state. Check ::eWidgetState for further information. Default is WS_NORMAL.

Returns: greater than 0 on success (the Font id) or a negative value when using the default font.

Note: Applicable to: WT_LABEL, WT_BUTTON, WT_CHECKBOX, WT_TEXTBOX, WT_LISTBOX.

◆ setGroup()

Sint32 CRM64Pro::Widget::setGroup ( Sint32 iGroup )

virtual

Set the checkbox group.

For WT_CHECKBOX: assigns the checkbox to a group (iGroup > 1). Checkboxes in the same group can only have one selected at a time.

Parameters

iGroup id of the group that this widget belongs to.

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

Note: Applicable to: WT_CHECKBOX only.

◆ getGroup()

Sint32 CRM64Pro::Widget::getGroup ( )

virtual

Get the checkbox group.

Returns: 0 when no group is assigned, greater than 0 with the group id or a negative error code on failure.

Note: Applicable to: WT_CHECKBOX only.

◆ setBorderWidth()

Sint32 CRM64Pro::Widget::setBorderWidth	(	Sint32	iWidth,
		eWidgetState	eWS = WS_DEFAULT )

Set the border width.

Parameters

iWidth	border width in pixels.
eWS	Widget state. Check ::eWidgetState for further information. Default is WS_DEFAULT (affects all states).

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

◆ getBorderWidth()

Sint32 CRM64Pro::Widget::getBorderWidth ( eWidgetState eWS = WS_NORMAL )

Get the border width.

Parameters

eWS	Widget state. Check ::eWidgetState for further information. Default is WS_NORMAL.

Returns: Border width in pixels

◆ setBorderCorner()

Sint32 CRM64Pro::Widget::setBorderCorner	(	Sint32	iRad,
		eWidgetState	eWS = WS_DEFAULT )

Set the border corner radius.

Parameters

iRad	border corner radius in pixels.
eWS	Widget state. Check ::eWidgetState for further information. Default is WS_DEFAULT (affects all states).

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

◆ getBorderCorner()

Sint32 CRM64Pro::Widget::getBorderCorner ( eWidgetState eWS = WS_NORMAL )

Get the border corner radius.

Parameters

eWS	Widget state. Check ::eWidgetState for further information. Default is WS_NORMAL.

Returns: Border radius in pixels

◆ setBorderColor()

Sint32 CRM64Pro::Widget::setBorderColor	(	Uint8	iR,
		Uint8	iG,
		Uint8	iB,
		Uint8	iA,
		eWidgetState	eWS = WS_DEFAULT )

Set the border color.

Parameters

iR	The red color value.
iG	The green color value.
iB	The blue color value.
iA	The alpha value ranging from 0 (fully transparent) to 255 (opaque).
eWS	Widget state. Check ::eWidgetState for further information. Default is WS_DEFAULT (affects all states).

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

◆ getBorderColor()

Sint32 CRM64Pro::Widget::getBorderColor	(	Uint8 *	iR,
		Uint8 *	iG,
		Uint8 *	iB,
		Uint8 *	iA,
		eWidgetState	eWS = WS_NORMAL )

Get the border color.

Parameters

iR	pointer filled with the Red component. If nullptr, value not retrieved.
iG	pointer filled with the Green component. If nullptr, value not retrieved.
iB	pointer filled with the Blue component. If nullptr, value not retrieved.
iA	pointer filled with the alpha component. If nullptr, value not retrieved.
eWS	Widget state. Check ::eWidgetState for further information. Default is WS_NORMAL.

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

◆ setBgColor()

Sint32 CRM64Pro::Widget::setBgColor	(	Uint8	iR,
		Uint8	iG,
		Uint8	iB,
		eWidgetState	eWS = WS_DEFAULT )

Set the background color.

Parameters

iR	The red color value.
iG	The green color value.
iB	The blue color value.
eWS	Widget state. Check ::eWidgetState for further information. Default is WS_DEFAULT (affects all states).

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

Note: This method will overwrite any previous background. For WT_LISTBOX, WS_ACTION is used for rendering the selected item (font and background color).

◆ getBgColor()

Sint32 CRM64Pro::Widget::getBgColor	(	Uint8 *	iR,
		Uint8 *	iG,
		Uint8 *	iB,
		eWidgetState	eWS = WS_NORMAL )

Get the background color.

Parameters

iR	pointer filled with the Red component. If nullptr, value not retrieved.
iG	pointer filled with the Green component. If nullptr, value not retrieved.
iB	pointer filled with the Blue component. If nullptr, value not retrieved.
eWS	Widget state. Check ::eWidgetState for further information. Default is WS_NORMAL.

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

◆ setBgImage() [1/3]

Sint32 CRM64Pro::Widget::setBgImage	(	const string &	sFileCDC,
		const string &	sName,
		eWidgetState	eWS = WS_NORMAL )

Set the background image.

Parameters

sFileCDC	string containing the [directory]+filename.
sName	string with the image name (max 64 characters). If already loaded, a new child is created.
eWS	Widget state (WS_DEFAULT not supported). With WS_NORMAL, if no other background is set on WS_HOVERED/WS_DEACTIVATED, they use this. With WS_PRESSED, if no other background is set on WS_ACTION, it uses this. Modified states also disable border (alpha 0) and without WIDGET_FEATURE_BGFIT, widget size matches image size.

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

Note: Overwrites any previous background. Alpha modulation inherited from image.

◆ setBgImage() [2/3]

Sint32 CRM64Pro::Widget::setBgImage	(	Sint32	idCDC,
		const string &	sName,
		eWidgetState	eWS = WS_NORMAL )

Set the background image.

Parameters

idCDC	CDC id.
sName	string with the image name (max 64 characters). If already loaded, a new child is created.
eWS	Widget state (WS_DEFAULT not supported). With WS_NORMAL, if no other background is set on WS_HOVERED/WS_DEACTIVATED, they use this. With WS_PRESSED, if no other background is set on WS_ACTION, it uses this. Modified states also disable border (alpha 0) and without WIDGET_FEATURE_BGFIT, widget size matches image size.

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

Note: Overwrites any previous background. Alpha modulation inherited from image.

◆ setBgImage() [3/3]

Sint32 CRM64Pro::Widget::setBgImage	(	Sint32	idImage,
		eWidgetState	eWS = WS_NORMAL )

Set the background image.

Parameters

idImage	Image id. The image ownership will be taken by this widget.
eWS	Widget state (WS_DEFAULT not supported). With WS_NORMAL, if no other background is set on WS_HOVERED/WS_DEACTIVATED, they use this. With WS_PRESSED, if no other background is set on WS_ACTION, it uses this. Modified states also disable border (alpha 0) and without WIDGET_FEATURE_BGFIT, widget size matches image size.

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

Note: Overwrites any previous background. Alpha modulation inherited from image.

◆ getBgImage()

Sint32 CRM64Pro::Widget::getBgImage ( eWidgetState eWS = WS_NORMAL )

Get the background image.

Parameters

eWS	Widget state. Check ::eWidgetState for further information. Default is WS_NORMAL.

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

◆ setBgSprite() [1/3]

Sint32 CRM64Pro::Widget::setBgSprite	(	const string &	sFileCDC,
		const string &	sName,
		eWidgetState	eWS = WS_DEFAULT,
		Sint32	iAnim = 0 )

Set the background sprite.

Parameters

sFileCDC	string containing the [directory]+filename.
sName	string with the sprite name (max 64 characters). If already loaded, a new child is created.
eWS	Widget state. With WS_DEFAULT, assigns animations per state: iAnim for WS_NORMAL, iAnim+1 for WS_HOVERED, iAnim+2 for WS_PRESSED, iAnim+3 for WS_ACTION, iAnim+4 for WS_DEACTIVATED. Modified states also disable border (alpha 0) and without WIDGET_FEATURE_BGFIT, widget size matches sprite size.
iAnim	starting animation state (high-state + low-state) or animation number. At least one animation must exist. Default is 0.

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

Note: Overwrites any previous background. Alpha modulation inherited from sprite.; When using eWidgetType::WT_HSLIDER or eWidgetType::WT_VSLIDER, the thumb size is not automatically detected. The user must explicitly call setThumbSize().

◆ setBgSprite() [2/3]

Sint32 CRM64Pro::Widget::setBgSprite	(	Sint32	idCDC,
		const string &	sName,
		eWidgetState	eWS = WS_DEFAULT,
		Sint32	iAnim = 0 )

Set the background sprite.

Parameters

idCDC	CDC id.
sName	string with the sprite name (max 64 characters). If already loaded, a new child is created.
eWS	Widget state. With WS_DEFAULT, assigns animations per state: iAnim for WS_NORMAL, iAnim+1 for WS_HOVERED, iAnim+2 for WS_PRESSED, iAnim+3 for WS_ACTION, iAnim+4 for WS_DEACTIVATED. Modified states also disable border (alpha 0) and without WIDGET_FEATURE_BGFIT, widget size matches sprite size.
iAnim	starting animation state (high-state + low-state) or animation number. At least one animation must exist. Default is 0.

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

Note: Overwrites any previous background. Alpha modulation inherited from sprite.; When using eWidgetType::WT_HSLIDER or eWidgetType::WT_VSLIDER, the thumb size is not automatically detected. The user must explicitly call setThumbSize().

◆ setBgSprite() [3/3]

Sint32 CRM64Pro::Widget::setBgSprite	(	Sint32	idSprite,
		eWidgetState	eWS = WS_DEFAULT,
		Sint32	iAnim = 0 )

Set the background sprite.

Parameters

idSprite	Sprite id.
eWS	Widget state. With WS_DEFAULT, assigns animations per state: iAnim for WS_NORMAL, iAnim+1 for WS_HOVERED, iAnim+2 for WS_PRESSED, iAnim+3 for WS_ACTION, iAnim+4 for WS_DEACTIVATED. Modified states also disable border (alpha 0) and without WIDGET_FEATURE_BGFIT, widget size matches sprite size.
iAnim	starting animation state (high-state + low-state) or animation number. At least one animation must exist. Default is 0.

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

Note: Overwrites any previous background. Alpha modulation inherited from sprite.; When using eWidgetType::WT_HSLIDER or eWidgetType::WT_VSLIDER, the thumb size is not automatically detected. The user must explicitly call setThumbSize().

◆ getBgSprite()

Sint32 CRM64Pro::Widget::getBgSprite	(	eWidgetState	eWS = WS_NORMAL,
		Sint32 *	iAnim = nullptr )

Get the background sprite.

Parameters

eWS	Widget state. Check ::eWidgetState for further information. Default is WS_NORMAL.
iAnim	pointer to get the animation number, or nullptr to skip. Default is nullptr.

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

◆ setFunction()

Sint32 CRM64Pro::Widget::setFunction	(	Sint32(*	stateFunc )(void , void ),
		void *	iParam1 = nullptr,
		void *	iParam2 = nullptr,
		eWidgetState	eWS = WS_ACTION )

Set a function to be called on given state.

Parameters

stateFunc	pointer to a function "Sint32 myFunc(void,void)" to be called on the given state. Set to nullptr to remove a previous function.
iParam1	Optional void pointer passed to myFunc.
iParam2	Optional void pointer passed to myFunc.
eWS	Widget state (WS_DEFAULT and WS_DEACTIVATED not supported). Default is WS_ACTION.

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

Description

Overview

Key features

Widget categories

Widget states

Skin properties

Common widget properties

Update return codes

ProgressBar notes

Best practices

Classes

Macros

Enumerations

Functions

Macro Definition Documentation

◆ WIDGET_FEATURE_FADE

◆ WIDGET_FEATURE_DRAGDROP

◆ WIDGET_FEATURE_ENCLOSE

◆ WIDGET_FEATURE_DETACH

◆ WIDGET_FEATURE_BGFIT

◆ WIDGET_FEATURE_BGDISABLE

◆ WIDGET_FEATURE_EVENTS

◆ WIDGET_FEATURE_MOUSEOVER

◆ WIDGET_FEATURE_LOSTFOCUS

◆ WIDGET_FEATURE_MULTILINE

◆ WIDGET_FEATURE_READONLY

◆ WIDGET_FEATURE_AUTOSORT

Enumeration Type Documentation

◆ eWidgetState

◆ eWidgetType

Function Documentation

◆ info()

◆ disable()

◆ show()

◆ hide()

◆ status()

◆ features()

◆ setSize()

◆ getSize()

◆ setPosition()

◆ getPosition()

◆ setMargin()

◆ getMargin()

◆ setThumbSize()

◆ setAlphaMod()

◆ getAlphaMod()

◆ setText()

◆ getText()

◆ getLine()

◆ getLineCount()

◆ appendText()

◆ appendLine()

◆ setLine()

◆ insertLine()

◆ removeLine()

◆ addItem()

◆ insertItem()

◆ removeItem()

◆ clearItems()

◆ selectItem()

◆ getSelectedItem()

◆ setKey()

◆ getKey()

◆ setValue()

◆ getValue()

◆ getValueGroup()

◆ setRange()

◆ getRange()

◆ setState()

◆ setScroll()

◆ getScroll()

◆ getVisibleItems()

◆ setFont()

◆ getFont()

◆ setGroup()

◆ getGroup()

◆ setBorderWidth()

◆ getBorderWidth()

◆ setBorderCorner()

◆ getBorderCorner()