Description

Widget classes for building graphical user interfaces inside Panels [v26.05.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, text editors and combo boxes. Each widget supports five visual states with independently configurable skins. Theme-driven styling is applied automatically and can be overridden per widget per state.
See GUI Manager for panel management, console, debug window and tooltip documentation.

Key features

State-based skinning: 5 visual states with independent skin properties per state
Theme integration: Automatic theme-driven styling with per-widget per-state override masks
Flexible backgrounds: Solid color, image or animated sprite backgrounds per state
Border customization: Configurable border width, RGBA color and corner radius per state
Font support: Per-state font assignment; resolved through theme when not explicitly set
Tooltip support: Optional hover tooltips with CDC-persisted text, per-widget TTL, optional cursor-follow, shared theme tooltip visuals and optional widget-local overrides
Keyboard activation: Button and CheckBox widgets can expose keyboard shortcuts via setKey()
Unified numeric API: Progress, Slider and NumberEdit expose value/range state through setValue(), getValue(), setRange(min,max) and getRange(&min,&max)
Unified selection API: List and ComboBox expose selection through setSelectedIndex(), getSelectedIndex(), setSelectedText() and getSelectedText()
Direct callbacks: State-edge and semantic std::function callbacks complement the SDL queue event path
Fading effects: Built-in show/hide transitions (WIDGET_FADING_TIME = 500 ms)
Drag and drop: Optional widget drag/drop movement within the parent panel
Layout participation: Widgets placed under a panel flow layout are reflowed automatically on creation, resize or visibility change

Text encoding note

TextEdit and Console editing preserve valid UTF-8 byte boundaries for insertion, deletion, cursor movement and selection. Widget text rendering still depends on the current bitmap Font module, which only renders the supported printable ASCII character set. Non-ASCII UTF-8 content can be stored and retrieved safely, but glyph rendering and visual cursor metrics for multi-byte characters are not yet supported.

Widget categories

Simple widgets

Label	Static text display. Size auto-fits to text. Background disabled by default.
Image	Static image display. No text. Size taken from image asset when WF_BGFIT is not set.
Frame	Line or box widget for visual grouping. Renders filled (rectFilled) or outline (rect) based on setFilled(). Frame rendering uses the background RGB color as the line/fill/outline color; border width controls thin-line thickness, and border alpha can override outline alpha, but border RGB is not used by Frame rendering. Correctly handles thin (1D) sizing for horizontal and vertical dividers.
Button	Clickable button. Supports keyboard shortcut via setKey(). Fires setOnAction callback and EC_WIDGET_ACTION event on click or key activation.
CheckBox	Toggle control. Optional radio-button grouping via setGroup(). Group members can only be enabled, never self-disabled. Emits EC_WIDGET_TOGGLED when user interaction changes the checked value.
Progress	Value indicator rendered as discrete slices. Uses the standard numeric API: setValue(), getValue(), setRange(min,max) and getRange(&min,&max). Ranges may include negative values; the filled amount is measured from the configured minimum to the current value. Uses WS_PRESSED (filled) and WS_HOVERED (empty) skin states. See Progress Notes below.
Slider	Value slider with configurable horizontal or vertical axis. Uses the standard numeric API: setValue(), getValue(), setRange(min,max) and getRange(&min,&max). Ranges may include negative values. Thumb size can be fixed via setThumbSize(). Emits EC_WIDGET_VALUECHANGED for each distinct value reached during user interaction, including live dragging.

Advanced widgets

TextEdit	Single or multi-line text editor. UTF-8 cursor, selection (mouse drag and Shift-click), cut/copy/paste, 128-step undo/redo stack, mouse click-to-caret, keyboard navigation (Home/End/PgUp/PgDn/arrows), read-only mode. Fires EC_WIDGET_VALUECOMMITTED on Enter or focus exit when text changed, and EC_WIDGET_LOSTFOCUS on focus exit. CDC persistence stores only semantic editor configuration (multiline/read-only); runtime text content, caret, selection, scroll position, blink state and cached layout metrics are not saved.
NumberEdit	Inherits TextEdit. Numeric input with min/max/step validation, integer or float mode. Input is sanitized on each keystroke and committed on Enter or focus loss. Emits EC_WIDGET_VALUECOMMITTED when the committed value changes. Uses the standard numeric API: setValue(), getValue(), setRange(min,max) and getRange(&min,&max), alongside the base text API. CDC persistence stores the numeric value plus min/max/step/float-mode configuration, but not transient text-edit cursor, selection, or scroll state.
List	Scrollable item list. Single selection by default; multi-select (Ctrl+click toggle, Shift+click range from anchor) enabled via setMultiSelect(). Keyboard Up/Down moves by one item, Home/End moves to the first/last item, and PgUp/PgDn moves by one visible page while keeping the selection visible. Uses the standard selection API: setSelectedIndex(), getSelectedIndex(), setSelectedText() and getSelectedText(). setVisibleItems() resizes the list height to fit a requested row count. Emits EC_WIDGET_SELECTIONCHANGED when user interaction changes selection. Auto-sort mode available. getSelectedItems() returns all selected indices. CDC persistence stores widget configuration only; item contents and selection must be populated by the application at runtime.
ComboBox	Collapsed single-selection dropdown. Opens a popup list on click; ESC closes it. Uses the standard selection API: setSelectedIndex(), getSelectedIndex(), setSelectedText() and getSelectedText(). setVisibleItems() controls popup row capacity before scrolling. Emits EC_WIDGET_SELECTIONCHANGED when user interaction changes popup selection. Hover highlight during open. Popup is rendered in a second pass on top of all other panel widgets. Auto-sort mode available. When the first item is added, the current selection is initialized to item 1 automatically; applications may later clear the selection again with setSelectedIndex(0) or any negative value. Item contents and selection are runtime-owned and are not persisted in CDC widget blocks.

Widget state machine

Each widget transitions through 5 states driven by mouse and keyboard input. The base flow is:
WS_NORMAL → WS_HOVERED → WS_PRESSED → WS_ACTION → WS_NORMAL
ET_GUI_INTERNAL (the crafted focus-lost event) forces any non-deactivated widget back to WS_NORMAL immediately. Keyboard activation mirrors the mouse path through the auxiliary eAuxWS field without requiring mouse hover.

WS_DEFAULT	Special selector used only by skin setter methods to target all states at once. Not a runtime state and never stored as eWS.
WS_NORMAL	Idle state. Mouse is not over the widget and no key is pressed.
WS_HOVERED	Mouse cursor is over the widget body. Fires onHoverEnter on entry.
WS_PRESSED	Left mouse button is held down over the widget. Fires onPressed on entry.
WS_ACTION	Mouse button released over widget, or assigned key released. Command widgets emit EC_WIDGET_ACTION. Specialized widgets consume this state and emit semantic change events.
WS_DEACTIVATED	Widget is disabled. Does not handle events. Set via disable(); cleared via enable(). Drag and drop is reset on disable().

Skin properties

Each of the 5 states stores independent skin properties. When a widget-level setter is called, that property takes priority over the active theme for the selected state. When no widget-level override is present, the theme value is used. Theme entries themselves are defined on GUITheme objects and updated through the explicit GUITheme::setSkin...() methods. Background image and sprite assignments also suppress the primitive border color for that state.

Background color	RGB solid fill. Cleared when an image or sprite is assigned to the same state.
Background image	Image ID for static image background. Setting WS_NORMAL automatically propagates to WS_HOVERED and WS_DEACTIVATED if those states have no existing background. Setting WS_PRESSED propagates to WS_ACTION if unset.
Background sprite	Sprite ID and animation index for animated background. When WS_DEFAULT is used, each successive state receives the next animation index.
Border	RGBA color, width in pixels and corner radius in pixels. Set iBorderColorA=0 or iBorderWidth=0 to disable the border.
Font	Font ID for text rendering. When not overridden, the font is resolved from the active theme: first by built-in name (FontMgr::getBuiltin), then by loaded font name, then falls back to CourierNew10White.

Widget feature flags (eWidgetFeature / WF_*)

Feature flags are set via setFeatures() and control optional widget behaviors.

WF_FADE	Animated alpha show/hide transitions (WIDGET_FADING_TIME = 500 ms). Reversible mid-transition.
WF_DRAGDROP	Widget can be moved within its panel by mouse drag. Only one widget can be dragged at a time; drag is disabled on other widgets while this widget is being dragged.
WF_ENCLOSE	Prevents the widget body from leaving the parent panel bounds entirely. Applied by default to all widgets created through the Panel create* methods. Without this flag the widget is allowed to be mostly outside (minimum 4 pixels visible).
WF_DETACH	Uses the screen as the position/size reference instead of the parent panel. The widget can be positioned anywhere on the screen independently of the panel.
WF_BGFIT	Background image or sprite scales to the widget's current size rather than overriding the widget size when the asset is assigned.
WF_BGDISABLE	Suppresses background rendering entirely. Applied by default to Label and Frame widgets.
WF_EVENTS	Widget participates in the event routing protocol. Applied by default to Button, CheckBox, Slider, TextEdit, NumberEdit, List and ComboBox when created via Panel create* methods. Without this flag the widget may still render and update, but it reports WIDGET_UPDATE_FLAG_NOEVENT and is not treated as a normal event consumer by the parent panel.
WF_MOUSEOVER	Emits an EC_WIDGET_MOUSEHOVER event each frame while the widget is hovered, pressed or in action state.
WF_LOSTFOCUS	Emits an EC_WIDGET_LOSTFOCUS event on the transition from WS_HOVERED/WS_PRESSED/WS_ACTION to WS_NORMAL. TextEdit and NumberEdit use their keyboard-input focus lifecycle instead, so this event is emitted when text input focus is released.

Update return protocol

Widget update methods return exactly one base result ORed with zero or more flags. HIDDEN is terminal and must be tested first; it is never combined with flags.

WIDGET_UPDATE_HIDDEN (-1)	Widget is not shown (GS_HIDDEN or GS_HIDING reached end). Terminal.
WIDGET_UPDATE_NOTHING (0)	Widget is visible and idle.
WIDGET_UPDATE_ACTIVITY (1)	Widget consumed user attention (hovered, pressed, or in action). Blocks drag and drop for lower-priority widgets and lower GUI layers.
WIDGET_UPDATE_CLOSEME (2)	Ephemeral panel TTL has elapsed and the panel requests removal by GUIMgr.

Additional flags ORed into non-HIDDEN results:

WIDGET_UPDATE_FLAG_NOEVENT (16)	Widget is visible but not an event consumer (WF_EVENTS not set). Drag and drop side-channel flags may still be set.
WIDGET_UPDATE_FLAG_DRAGDROP (32)	Widget is currently being drag-dropped. Disables drag for other widgets this frame.
WIDGET_UPDATE_FLAG_INPUTFOCUS (64)	Widget holds text/keyboard input focus. Routes SDL_EVENT_TEXT_INPUT to this GUI branch.
WIDGET_UPDATE_FLAG_LCLICK (128)	Widget received a left mouse button press. Parent GUI layers can use this as a focus or activation side-channel.
WIDGET_UPDATE_FLAG_CBGROUP (256)	A grouped CheckBox changed to the active state. Parent GUI code can use this side-channel to enforce single-selection behavior inside the group.

Direct callbacks

Callbacks are set via std::function setters and are fired on widget state or semantic event edges. They are runtime-only and are not serialized when saving or loading a GUI definition. They complement the SDL queue event path: use callbacks for code-local reactions and the SDL queue for centralized event handling. Programmatic setters update widget state silently; when code needs user-event side effects, call the shared application logic explicitly after the setter.

setOnAction(fn)	Fired by command-style widgets such as Button when WS_ACTION is reached.
setOnHoverEnter(fn)	Fired on the WS_NORMAL → WS_HOVERED transition edge.
setOnHoverExit(fn)	Fired when transitioning from WS_HOVERED, WS_PRESSED or WS_ACTION to WS_NORMAL. Represents pointer/hover exit.
setOnPressed(fn)	Fired on the WS_HOVERED → WS_PRESSED transition edge (mouse button down over widget).
setOnFocusLost(fn)	For normal widgets, fired on the same edge as onHoverExit. For TextEdit and NumberEdit, fired when keyboard-input focus is released after any pending value commit. Use onHoverExit for pointer-visual feedback.
setOnValueCommitted(fn)	Fired when TextEdit or NumberEdit accepts a changed value, matching EC_WIDGET_VALUECOMMITTED.
setOnSelectionChanged(fn)	Fired when user interaction changes List or ComboBox selection, matching EC_WIDGET_SELECTIONCHANGED.
setOnValueChanged(fn)	Fired when user interaction changes a live numeric widget value, matching EC_WIDGET_VALUECHANGED.
setOnToggled(fn)	Fired when user interaction changes CheckBox checked state, matching EC_WIDGET_TOGGLED.

Tooltip notes

Widgets expose hover help through setTooltip(). The text is CDC-persisted in the typed widget CDC blocks, limited to WIDGET_TOOLTIP_MAXBYTES (63) bytes. The GUI manager renders the tooltip after GUI_TOOLTIP_DELAY_MS of stable hover, using the active theme's shared tooltip style unless the widget provides a local tooltip background/border/font override. Tooltip TTL is per-widget via setTooltipTTL(); the default is WIDGET_TOOLTIP_DEFAULT_TTL_MS = 0, which means the tooltip remains visible while the hover is valid (no auto-expiry). Set a positive value in milliseconds to have the tooltip hide automatically. After a tooltip expires, it will not show again for the same widget until the pointer leaves and re-hovers. Cursor-following can be enabled via setTooltipFollowCursor().

Progress notes

Range	Progress uses an inclusive minimum/maximum range through setRange(min,max). Values are clamped to that range. Negative ranges are valid; for example setRange(-100,100) with value 0 renders half-filled.
Without image/sprite	Call setSize() before setRange(min,max) to ensure correct slice pixel calculations.
With image/sprite	Size is calculated automatically from the asset and the range span. WS_PRESSED skin is sampled for the asset dimensions.
State usage	WS_PRESSED renders filled slices (value reached). WS_HOVERED renders empty slices. WS_DEACTIVATED renders using WS_DEACTIVATED (filled) and WS_ACTION (empty).

CDC persistence layout

Widget CDC persistence uses one explicit fixed struct per widget family. All blocks start with the same WIDGET_IO_Block header and then continue with a typed base block plus an optional typed extension block. Tooltip text and tooltip settings live in the common base block. Widget-specific persistence no longer relies on shared offset macros or a packed reserved pool.

Common base	`WIDGETv1_Base_Block` stores geometry, margins, alpha, key, stored label text, tooltip text/settings, tooltip override style, positions, and the 5 skin states.
Frame / CheckBox / Progress	Persist only meaningful widget state: frame filled flag, checkbox checked/group, progress value/min/max range/slice metrics.
Slider	Persists axis, value/min/max range and fixed thumb sizing. Derived thumb geometry is recomputed after load and is not stored.
TextEdit / NumberEdit	Persist only semantic editor configuration: TextEdit stores multiline/read-only, NumberEdit stores read-only plus numeric value/min/max/step/float-mode. Caret, selection, scroll and blink state are runtime-only.
List / ComboBox	Persist only configuration such as max visible items, autosort and multiselect. Runtime item contents, selection and popup/scroll state are not stored in CDC.

Best practices

Always define WS_NORMAL, WS_HOVERED, WS_PRESSED and WS_ACTION skins for interactive widgets that use image/sprite backgrounds; inconsistent sizes cause visual glitches
Group CheckBox widgets with setGroup() for radio-button behavior. Do not call setChecked(false) directly on a grouped CheckBox; the group enforces that only one member can be checked at a time
For Progress without an image/sprite, always call setSize() before setRange(min,max) to ensure the slice pixel value is computed correctly
Use direct callbacks for code-local reactions and keep the SDL queue path for centralized event dispatch
Widget show()/hide(), creation, removal and resize automatically invalidate parent flow layouts; use Panel::invalidateLayout() only for caller-controlled edge cases
Set keyboard shortcuts with setKey() on frequently used buttons to improve accessibility and in-game usability
Use setTooltipTTL(0) (the default) to keep tooltips visible for as long as the hover is active; set a positive millisecond value for tooltips that should auto-expire
Use setFeatures(WF_FADE, true) and show()/hide() for smooth transitions instead of instant visibility changes

Classes
struct	CRM64Pro::GUITooltipStyle
	Shared tooltip style for one GUI theme or one widget override. More...
struct	CRM64Pro::GUIThemeSkin
	Theme skin definition for one widget type and one widget state. More...
class	CRM64Pro::GUITheme
	GUI theme object. More...
class	CRM64Pro::Widget
	Widget Object. More...
class	CRM64Pro::WidgetList
	List widget with single-selection or interactive multi-selection support. More...

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_FRAME = 4 , CRM64Pro::WT_BUTTON = 8 , CRM64Pro::WT_CHECKBOX = 16 , CRM64Pro::WT_PROGRESS = 32 , CRM64Pro::WT_SLIDER = 64 , CRM64Pro::WT_TEXTEDIT = 256 , CRM64Pro::WT_NUMBEREDIT = 512 , CRM64Pro::WT_LIST = 1024 , CRM64Pro::WT_COMBOBOX = 2048 }
	Widget type. More...
enum	CRM64Pro::eSliderAxis { CRM64Pro::SA_HORIZONTAL = 0 , CRM64Pro::SA_VERTICAL = 1 }
	Slider axis. More...
enum	CRM64Pro::eWidgetFeature : Uint32 { CRM64Pro::WF_DISABLE = 0 , CRM64Pro::WF_FADE = 0x00010000 , CRM64Pro::WF_DRAGDROP = 0x00020000 , CRM64Pro::WF_ENCLOSE = 0x00040000 , CRM64Pro::WF_DETACH = 0x00080000 , CRM64Pro::WF_BGFIT = 0x00100000 , CRM64Pro::WF_BGDISABLE = 0x00200000 , CRM64Pro::WF_EVENTS = 0x00400000 , CRM64Pro::WF_MOUSEOVER = 0x00800000 , CRM64Pro::WF_LOSTFOCUS = 0x01000000 }
	Widget feature flags. More...

Functions
virtual bool	CRM64Pro::Widget::info (Sint32 iMode=0)
	Request Widget object information.
const string &	CRM64Pro::Widget::getName () const
	Get the widget name.
Uint32	CRM64Pro::Widget::getID () const
	Get the widget ID.
eWidgetType	CRM64Pro::Widget::getType () const
	Get the widget type.
Sint32	CRM64Pro::Widget::disable ()
	Disable a widget.
Sint32	CRM64Pro::Widget::enable ()
	Enable a widget.
Sint32	CRM64Pro::Widget::show ()
	Show a widget.
Sint32	CRM64Pro::Widget::hide ()
	Hide a widget.
eGeneralStatus	CRM64Pro::Widget::status () const
	Get the widget status.
bool	CRM64Pro::Widget::setFeatures (eWidgetFeature eWF, bool bEnable)
	Set widget feature flags.
eWidgetFeature	CRM64Pro::Widget::getFeatures () const
	Get widget feature flags.
virtual Sint32	CRM64Pro::Widget::setSize (Sint32 iWidth, Sint32 iHeight)
	Set the size.
Sint32	CRM64Pro::Widget::getWidth () const
	Get the widget width.
Sint32	CRM64Pro::Widget::getHeight () const
	Get the widget height.
Sint32	CRM64Pro::Widget::setPosition (const Position &posX=Position(PH_CENTER), const Position &posY=Position(PH_CENTER))
	Set the position.
const Position &	CRM64Pro::Widget::getPositionX () const
	Get the widget X position.
const Position &	CRM64Pro::Widget::getPositionY () const
	Get the widget Y 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.
Sint32	CRM64Pro::Widget::setAlphaMod (Uint8 iAlpha)
	Set alpha modulation used for rendering this widget.
Uint8	CRM64Pro::Widget::getAlphaMod () const
	Get alpha modulation used for rendering this widget.
eWidgetState	CRM64Pro::Widget::getState () const
	Get the widget state.
virtual Sint32	CRM64Pro::Widget::setFont (Sint32 idFont, eWidgetState eWS=WS_DEFAULT)
	Set the font.
Sint32	CRM64Pro::Widget::getFont (eWidgetState eWS=WS_NORMAL) const
	Get the font.
Sint32	CRM64Pro::Widget::setBorderWidth (Sint32 iWidth, eWidgetState eWS=WS_DEFAULT)
	Set the border width.
Sint32	CRM64Pro::Widget::getBorderWidth (eWidgetState eWS=WS_NORMAL) const
	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) const
	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) const
	Get the effective border color.
Sint32	CRM64Pro::Widget::setBackgroundColor (Uint8 iR, Uint8 iG, Uint8 iB, eWidgetState eWS=WS_DEFAULT)
	Set the background color.
Sint32	CRM64Pro::Widget::getBackgroundColor (Uint8 iR, Uint8 iG, Uint8 *iB, eWidgetState eWS=WS_NORMAL) const
	Get the effective background color.
Sint32	CRM64Pro::Widget::setSelectionColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA, eWidgetState eWS=WS_DEFAULT)
	Set the selection highlight color.
Sint32	CRM64Pro::Widget::getSelectionColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA, eWidgetState eWS=WS_NORMAL) const
	Get the effective selection highlight color.
Sint32	CRM64Pro::Widget::resetSkin (eWidgetState eWS=WS_DEFAULT)
	Clear custom skin overrides and custom background resources.
Uint32	CRM64Pro::Widget::getSkinOverrideMask (eWidgetState eWS=WS_NORMAL) const
	Get the custom skin override mask for one state.
Sint32	CRM64Pro::Widget::clearBackground (eWidgetState eWS=WS_DEFAULT)
	Clear custom background resources for one state.
Sint32	CRM64Pro::Widget::setBackgroundImage (const string &sCDCFile, const string &sName, eWidgetState eWS=WS_NORMAL)
	Set the background image.
Sint32	CRM64Pro::Widget::setBackgroundImage (Sint32 idCDC, const string &sName, eWidgetState eWS=WS_NORMAL)
	Set the background image.
Sint32	CRM64Pro::Widget::setBackgroundImage (Sint32 idImage, eWidgetState eWS=WS_NORMAL)
	Set the background image.
Sint32	CRM64Pro::Widget::getBackgroundImage (eWidgetState eWS=WS_NORMAL) const
	Get the background image.
Sint32	CRM64Pro::Widget::setBackgroundSprite (const string &sCDCFile, const string &sName, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
	Set the background sprite.
Sint32	CRM64Pro::Widget::setBackgroundSprite (Sint32 idCDC, const string &sName, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
	Set the background sprite.
Sint32	CRM64Pro::Widget::setBackgroundSprite (Sint32 idSprite, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
	Set the background sprite.
Sint32	CRM64Pro::Widget::getBackgroundSprite (eWidgetState eWS=WS_NORMAL, Sint32 *iAnim=nullptr) const
	Get the background sprite.
Sint32	CRM64Pro::Widget::setOnAction (function< void(Widget &)> callback)
	Set a callback fired when the widget triggers an action.
Sint32	CRM64Pro::Widget::setOnHoverEnter (function< void(Widget &)> callback)
	Set a callback fired when the widget starts being hovered.
Sint32	CRM64Pro::Widget::setOnHoverExit (function< void(Widget &)> callback)
	Set a callback fired when the widget stops being hovered.
Sint32	CRM64Pro::Widget::setOnPressed (function< void(Widget &)> callback)
	Set a callback fired when the widget is pressed.
Sint32	CRM64Pro::Widget::setOnFocusLost (function< void(Widget &)> callback)
	Set a callback fired when the widget loses focus.
Sint32	CRM64Pro::Widget::setOnValueCommitted (function< void(Widget &)> callback)
	Set a callback fired when an edit widget commits a changed value.
Sint32	CRM64Pro::Widget::setOnSelectionChanged (function< void(Widget &)> callback)
	Set a callback fired when a selection widget changes selection.
Sint32	CRM64Pro::Widget::setOnValueChanged (function< void(Widget &)> callback)
	Set a callback fired when a live value widget changes value.
Sint32	CRM64Pro::Widget::setOnToggled (function< void(Widget &)> callback)
	Set a callback fired when a toggle widget changes state.
Sint32	CRM64Pro::Widget::setTooltip (const string &sText)
	Set the tooltip text.
const string &	CRM64Pro::Widget::getTooltip () const
	Get the tooltip text.
Sint32	CRM64Pro::Widget::setTooltipTTL (Sint32 iMS)
	Set the tooltip auto-hide time.
Sint32	CRM64Pro::Widget::getTooltipTTL () const
	Get the tooltip auto-hide time.
Sint32	CRM64Pro::Widget::setTooltipFollowCursor (bool bEnable=true)
	Set whether the tooltip follows the cursor.
bool	CRM64Pro::Widget::isTooltipFollowingCursor () const
	Check whether the tooltip follows the cursor.
Sint32	CRM64Pro::Widget::setTooltipBackgroundColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA)
	Set the widget-local tooltip background color override.
Sint32	CRM64Pro::Widget::getTooltipBackgroundColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA) const
	Get the effective tooltip background color.
Sint32	CRM64Pro::Widget::setTooltipBorderColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA)
	Set the widget-local tooltip border color override.
Sint32	CRM64Pro::Widget::getTooltipBorderColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA) const
	Get the effective tooltip border color.
Sint32	CRM64Pro::Widget::setTooltipFontName (const string &sFontName)
	Set the widget-local tooltip font name override.
Sint32	CRM64Pro::Widget::setTooltipFont (Sint32 idFont)
	Set the widget-local runtime tooltip font id override.
Sint32	CRM64Pro::Widget::getTooltipFont () const
	Get the effective tooltip font id.
Uint32	CRM64Pro::Widget::getTooltipOverrideMask () const
	Get the widget-local tooltip style override mask.
Sint32	CRM64Pro::Widget::resetTooltipStyle ()
	Reset widget-local tooltip style overrides.

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_FRAME	Frame widget.
WT_BUTTON	Standard button widget.
WT_CHECKBOX	CheckBox widget.
WT_PROGRESS	Progress widget.
WT_SLIDER	Slider widget.
WT_TEXTEDIT	TextEdit widget.
WT_NUMBEREDIT	NumberEdit widget.
WT_LIST	List widget.
WT_COMBOBOX	ComboBox widget.

◆ eSliderAxis

enum CRM64Pro::eSliderAxis

Slider axis.

Enumerator
SA_HORIZONTAL	Horizontal slider axis.
SA_VERTICAL	Vertical slider axis.

◆ eWidgetFeature

enum CRM64Pro::eWidgetFeature : Uint32

Widget feature flags.

Enumerator
WF_DISABLE	Disable all widget features. Default value.
WF_FADE	Fading effect at showing and hiding time.
WF_DRAGDROP	Allow to move the widget (drag&drop).
WF_ENCLOSE	Enclose the widget inside its parent (default).
WF_DETACH	The widget is detached from its parent.
WF_BGFIT	Background image/sprite auto-fit to widget size.
WF_BGDISABLE	Background rendering is disabled.
WF_EVENTS	Allow the widget to process events and generate semantic widget events.
WF_MOUSEOVER	Allow the widget to generate EC_WIDGET_MOUSEHOVER events.
WF_LOSTFOCUS	Allow the widget to generate EC_WIDGET_LOSTFOCUS events.

Function Documentation

◆ info()

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

virtual

Request Widget object information.

Writes information to the default log.

Parameters

iMode 0 (default) for a stand-alone widget dump including the widget heading and indentation, or 1 when called from a parent object info() method to print only the nested widget body.

Returns: true on success, or false on failure.

Reimplemented in CRM64Pro::WidgetList.

◆ getName()

const string & CRM64Pro::Widget::getName ( ) const

Get the widget name.

Returns: The widget name.

◆ getID()

Uint32 CRM64Pro::Widget::getID ( ) const

Get the widget ID.

Returns: Widget ID.

◆ getType()

eWidgetType CRM64Pro::Widget::getType ( ) const

Get the widget type.

Returns: Widget type.

◆ disable()

Sint32 CRM64Pro::Widget::disable ( )

Disable a widget.

Makes the widget non-interactive while keeping it renderable with its deactivated skin. Use hide() to remove it from rendering.

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

◆ enable()

Sint32 CRM64Pro::Widget::enable ( )

Enable a widget.

Restores widget interaction and returns the widget state to ::WS_NORMAL.

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

◆ show()

Sint32 CRM64Pro::Widget::show ( )

Show a widget.

Makes the widget visible. This does not modify its enabled/disabled state.

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

◆ hide()

Sint32 CRM64Pro::Widget::hide ( )

Hide a widget.

Makes the widget invisible. Hidden widgets are not updated or rendered.

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

◆ status()

eGeneralStatus CRM64Pro::Widget::status ( ) const

Get the widget status.

Returns: C64_STATUS_HIDDEN when the widget is fully hidden, C64_STATUS_DISABLED when it is disabled but still visible, or C64_STATUS_SHOWN when it is visible, showing, or hiding.

◆ setFeatures()

bool CRM64Pro::Widget::setFeatures	(	eWidgetFeature	eWF,
		bool	bEnable )

Set widget feature flags.

Check eWidgetFeature for a list of supported features.

Parameters

eWF	Widget features to enable or disable.
bEnable	true to enable the features, false to disable them.

Returns: true on success or false on failure.

◆ getFeatures()

eWidgetFeature CRM64Pro::Widget::getFeatures ( ) const

Get widget feature flags.

Returns: Current widget feature flags.

◆ setSize()

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

virtual

Set the size.

Parameters

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

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.; Some specialized widgets may clamp to a larger practical minimum to preserve their content layout.; For widgets managed by a panel flow layout, manual resizing invalidates the layout. If the parent layout is using LA_STRETCH, the new size becomes the child's restore size for later non-stretch alignment.; Applicable to: All widgets.

Reimplemented in CRM64Pro::WidgetList.

◆ getWidth()

Sint32 CRM64Pro::Widget::getWidth ( ) const

Get the widget width.

Returns: The widget width in pixels.

Note: Applicable to: All widgets.

◆ getHeight()

Sint32 CRM64Pro::Widget::getHeight ( ) const

Get the widget height.

Returns: The widget height in pixels.

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.

◆ getPositionX()

const Position & CRM64Pro::Widget::getPositionX ( ) const

Get the widget X position.

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

Returns: The Position struct containing X position (absolute or with helper).

Note: Applicable to: All widgets.

◆ getPositionY()

const Position & CRM64Pro::Widget::getPositionY ( ) const

Get the widget Y position.

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

Returns: The Position struct containing Y position (absolute or with helper).

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.

Reimplemented in CRM64Pro::WidgetList.

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

◆ 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 ( ) const

Get alpha modulation used for rendering this widget.

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

◆ getState()

eWidgetState CRM64Pro::Widget::getState ( ) const

Get the widget state.

Returns: Current widget state.

◆ setFont()

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

virtual

Set the font.

Parameters

idFont	Font id. The widget stores a borrowed reference and will not close it.
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 widgets that render text captions, editable text or item text, such as WT_LABEL, WT_BUTTON, WT_CHECKBOX, WT_TEXTEDIT, WT_NUMBEREDIT, WT_LIST and WT_COMBOBOX.

Reimplemented in CRM64Pro::WidgetList.

◆ getFont()

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

Get the font.

Parameters

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

Returns: Effective font id greater than 0, resolved from widget overrides, active theme or default GUI font.

Note: Applicable to widgets that render text captions, editable text or item text, such as WT_LABEL, WT_BUTTON, WT_CHECKBOX, WT_TEXTEDIT, WT_NUMBEREDIT, WT_LIST and WT_COMBOBOX.

◆ 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 ) const

Get the border width.

Parameters

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

Returns: Effective border width in pixels, resolved from widget overrides or active theme.

◆ 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 ) const

Get the border corner radius.

Parameters

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

Returns: Effective border radius in pixels, resolved from widget overrides or active theme.

◆ 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 ) const

Get the effective 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.

◆ setBackgroundColor()

Sint32 CRM64Pro::Widget::setBackgroundColor	(	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_LIST, WS_ACTION is used for rendering selected items. For WT_COMBOBOX, WS_ACTION is used for the selected popup item and WS_HOVERED for the hovered popup item.

◆ getBackgroundColor()

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

Get the effective 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.

◆ setSelectionColor()

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

Set the selection highlight 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.

Note: Applicable to widgets that render selection/highlight overlays such as WT_TEXTEDIT, WT_NUMBEREDIT, WT_LIST and WT_COMBOBOX.

◆ getSelectionColor()

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

Get the effective selection highlight 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.

◆ resetSkin()

Sint32 CRM64Pro::Widget::resetSkin ( eWidgetState eWS = WS_DEFAULT )

Clear custom skin overrides and custom background resources.

Parameters

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: After clearing, the widget resolves its appearance from the active GUI theme again for the affected state(s).

◆ getSkinOverrideMask()

Uint32 CRM64Pro::Widget::getSkinOverrideMask ( eWidgetState eWS = WS_NORMAL ) const

Get the custom skin override mask for one state.

Parameters

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

Returns: Bitmask composed of ::eSkinOverride flags for the stored custom values of the given state.

◆ clearBackground()

Sint32 CRM64Pro::Widget::clearBackground ( eWidgetState eWS = WS_DEFAULT )

Clear custom background resources for one state.

Parameters

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 clears assigned background image/sprite resources and their derived background/border color override bits for the affected state(s).

◆ setBackgroundImage() [1/3]

Sint32 CRM64Pro::Widget::setBackgroundImage	(	const string &	sCDCFile,
		const string &	sName,
		eWidgetState	eWS = WS_NORMAL )

Set the background image.

Parameters

sCDCFile	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 or WS_DEACTIVATED they use this one. With WS_PRESSED, if no other background is set on WS_ACTION it uses this one. Modified states also disable the border (alpha 0) and, without WF_BGFIT, the widget size matches the image size.

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

Note: Overwrites any previous background. Image alpha modulation affects only the rendered background.; The loaded image handle is owned by the widget and released when replaced, cleared or destroyed.

◆ setBackgroundImage() [2/3]

Sint32 CRM64Pro::Widget::setBackgroundImage	(	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 or WS_DEACTIVATED they use this one. With WS_PRESSED, if no other background is set on WS_ACTION it uses this one. Modified states also disable the border (alpha 0) and, without WF_BGFIT, the widget size matches the image size.

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

Note: Overwrites any previous background. Image alpha modulation affects only the rendered background.; The loaded image handle is owned by the widget and released when replaced, cleared or destroyed.

◆ setBackgroundImage() [3/3]

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

Set the background image.

Parameters

idImage	Image id. The image ownership will be taken by this widget; the caller must not close it after a successful call.
eWS	Widget state (WS_DEFAULT not supported). With WS_NORMAL, if no other background is set on WS_HOVERED or WS_DEACTIVATED they use this one. With WS_PRESSED, if no other background is set on WS_ACTION it uses this one. Modified states also disable the border (alpha 0) and, without WF_BGFIT, the widget size matches the image size.

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

Note: Overwrites any previous background. Image alpha modulation affects only the rendered background.

◆ getBackgroundImage()

Sint32 CRM64Pro::Widget::getBackgroundImage ( eWidgetState eWS = WS_NORMAL ) const

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.

◆ setBackgroundSprite() [1/3]

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

Set the background sprite.

Parameters

sCDCFile	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 WF_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. Sprite image alpha modulation affects only the rendered background.; The loaded sprite handle is owned by the widget and released when replaced, cleared or destroyed.; When using eWidgetType::WT_SLIDER, the thumb size is not automatically detected. The user must explicitly call setThumbSize().

◆ setBackgroundSprite() [2/3]

Sint32 CRM64Pro::Widget::setBackgroundSprite	(	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 WF_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. Sprite image alpha modulation affects only the rendered background.; The loaded sprite handle is owned by the widget and released when replaced, cleared or destroyed.; When using eWidgetType::WT_SLIDER, the thumb size is not automatically detected. The user must explicitly call setThumbSize().

◆ setBackgroundSprite() [3/3]

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

Set the background sprite.

Parameters

idSprite	Sprite id. The sprite ownership will be taken by this widget; the caller must not close it after a successful call.
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 WF_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. Sprite image alpha modulation affects only the rendered background.; When using eWidgetType::WT_SLIDER, the thumb size is not automatically detected. The user must explicitly call setThumbSize().

◆ getBackgroundSprite()

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

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.

◆ setOnAction()

Sint32 CRM64Pro::Widget::setOnAction ( function< void(Widget &)> callback )

Set a callback fired when the widget triggers an action.

Parameters

callback Callback invoked once when the widget enters WS_ACTION.

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

Note: This direct callback path complements, but does not replace, the SDL queue events generated by the widget.

◆ setOnHoverEnter()

Sint32 CRM64Pro::Widget::setOnHoverEnter ( function< void(Widget &)> callback )

Set a callback fired when the widget starts being hovered.

Parameters

callback Callback invoked once when the widget enters WS_HOVERED.

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

◆ setOnHoverExit()

Sint32 CRM64Pro::Widget::setOnHoverExit ( function< void(Widget &)> callback )

Set a callback fired when the widget stops being hovered.

Parameters

callback Callback invoked once when the widget leaves the hover/pressed/action flow and returns to WS_NORMAL.

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

◆ setOnPressed()

Sint32 CRM64Pro::Widget::setOnPressed ( function< void(Widget &)> callback )

Set a callback fired when the widget is pressed.

Parameters

callback Callback invoked once when the widget enters WS_PRESSED.

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

◆ setOnFocusLost()

Sint32 CRM64Pro::Widget::setOnFocusLost ( function< void(Widget &)> callback )

Set a callback fired when the widget loses focus.

Parameters

callback Callback invoked once on the same edge where EC_WIDGET_LOSTFOCUS is generated.

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

◆ setOnValueCommitted()

Sint32 CRM64Pro::Widget::setOnValueCommitted ( function< void(Widget &)> callback )

Set a callback fired when an edit widget commits a changed value.

Parameters

callback Callback invoked once on the same edge where EC_WIDGET_VALUECOMMITTED is generated.

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

Note: This is the semantic commit event for TextEdit and NumberEdit, including Enter and focus-loss commits.

◆ setOnSelectionChanged()

Sint32 CRM64Pro::Widget::setOnSelectionChanged ( function< void(Widget &)> callback )

Set a callback fired when a selection widget changes selection.

Parameters

callback Callback invoked once on the same edge where EC_WIDGET_SELECTIONCHANGED is generated.

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

Note: Intended for List and ComboBox widgets.

◆ setOnValueChanged()

Sint32 CRM64Pro::Widget::setOnValueChanged ( function< void(Widget &)> callback )

Set a callback fired when a live value widget changes value.

Parameters

callback Callback invoked once on the same edge where EC_WIDGET_VALUECHANGED is generated.

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

Note: Intended for widgets such as Slider that report live value changes. A Slider drag can invoke this once for each distinct value reached before mouse release.

◆ setOnToggled()

Sint32 CRM64Pro::Widget::setOnToggled ( function< void(Widget &)> callback )

Set a callback fired when a toggle widget changes state.

Parameters

callback Callback invoked once on the same edge where EC_WIDGET_TOGGLED is generated.

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

Note: Intended for user-driven CheckBox changes. Programmatic setters update state silently.

◆ setTooltip()

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

Set the tooltip text.

Assigns a tooltip that appears automatically after hovering the widget for a short time. Tooltip text is limited to 63 visible ASCII characters (64 bytes including the terminator) and longer input is truncated. The tooltip text is serialized with the widget and rendered by the GUI manager using the active theme shared tooltip style, unless the widget overrides that style locally. New widgets default to a tooltip TTL of 0, meaning the tooltip remains visible while it stays valid.

Parameters

sText Tooltip text. An empty string disables the tooltip.

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

◆ getTooltip()

const string & CRM64Pro::Widget::getTooltip ( ) const

Get the tooltip text.

Returns: The current tooltip text, or an empty string when no tooltip is assigned.

◆ setTooltipTTL()

Sint32 CRM64Pro::Widget::setTooltipTTL ( Sint32 iMS )

Set the tooltip auto-hide time.

Parameters

iMS	Auto-hide time in milliseconds. Use 0 to keep the tooltip visible while it remains valid.

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

◆ getTooltipTTL()

Sint32 CRM64Pro::Widget::getTooltipTTL ( ) const

Get the tooltip auto-hide time.

Returns: Tooltip auto-hide time in milliseconds. 0 means it stays visible while valid.

◆ setTooltipFollowCursor()

Sint32 CRM64Pro::Widget::setTooltipFollowCursor ( bool bEnable = true )

Set whether the tooltip follows the cursor.

Parameters

bEnable true to keep updating the tooltip position while hovering the same widget; false to freeze the position when shown.

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

◆ isTooltipFollowingCursor()

bool CRM64Pro::Widget::isTooltipFollowingCursor ( ) const

Check whether the tooltip follows the cursor.

Returns: true when the tooltip follows the cursor, or false when the shown position is frozen.

◆ setTooltipBackgroundColor()

Sint32 CRM64Pro::Widget::setTooltipBackgroundColor	(	Uint8	iR,
		Uint8	iG,
		Uint8	iB,
		Uint8	iA )

Set the widget-local tooltip background color override.

This override is not state-based. It applies to the widget tooltip as a whole.

Parameters

iR	Red component.
iG	Green component.
iB	Blue component.
iA	Alpha component.

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

◆ getTooltipBackgroundColor()

Sint32 CRM64Pro::Widget::getTooltipBackgroundColor	(	Uint8 *	iR,
		Uint8 *	iG,
		Uint8 *	iB,
		Uint8 *	iA ) const

Get the effective tooltip 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.
iA	pointer filled with the alpha component. If nullptr, value not retrieved.

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

◆ setTooltipBorderColor()

Sint32 CRM64Pro::Widget::setTooltipBorderColor	(	Uint8	iR,
		Uint8	iG,
		Uint8	iB,
		Uint8	iA )

Set the widget-local tooltip border color override.

This override is not state-based. It applies to the widget tooltip as a whole.

Parameters

iR	Red component.
iG	Green component.
iB	Blue component.
iA	Alpha component.

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

◆ getTooltipBorderColor()

Sint32 CRM64Pro::Widget::getTooltipBorderColor	(	Uint8 *	iR,
		Uint8 *	iG,
		Uint8 *	iB,
		Uint8 *	iA ) const

Get the effective tooltip 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.

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

◆ setTooltipFontName()

Sint32 CRM64Pro::Widget::setTooltipFontName ( const string & sFontName )

Set the widget-local tooltip font name override.

This override is not state-based. It applies to the widget tooltip as a whole.

Parameters

sFontName Font name. Built-in fonts should use the full @c64/font/... name.

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

◆ setTooltipFont()

Sint32 CRM64Pro::Widget::setTooltipFont ( Sint32 idFont )

Set the widget-local runtime tooltip font id override.

This override is not state-based. It applies to the widget tooltip as a whole.

Parameters

idFont Runtime font id. Set to -1 to clear the direct font id. The widget stores a borrowed reference and will not close it.

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

◆ getTooltipFont()

Sint32 CRM64Pro::Widget::getTooltipFont ( ) const

Get the effective tooltip font id.

Returns: Effective tooltip font id, resolved from widget overrides, active theme, widget skin font or default GUI font.

◆ getTooltipOverrideMask()

Uint32 CRM64Pro::Widget::getTooltipOverrideMask ( ) const

Get the widget-local tooltip style override mask.

Use this to know whether the effective tooltip style values come from widget-local overrides or the active theme.

Returns: Bitmask for the stored tooltip style override values. Bit 0 is background color, bit 1 is border color and bit 2 is font.

◆ resetTooltipStyle()

Sint32 CRM64Pro::Widget::resetTooltipStyle ( )

Reset widget-local tooltip style overrides.

Clears the widget-local tooltip font, background color and border color overrides so the tooltip style is resolved from the active theme again. This does not modify the tooltip text, TTL or follow-cursor setting.

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

Description

Overview

Key features

Text encoding note

Widget categories

Widget state machine

Skin properties

Widget feature flags (eWidgetFeature / WF_*)

Update return protocol

Direct callbacks

Tooltip notes

Progress notes

CDC persistence layout

Best practices

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ eWidgetState

◆ eWidgetType

◆ eSliderAxis

◆ eWidgetFeature

Function Documentation

◆ info()

◆ getName()

◆ getID()

◆ getType()

◆ disable()

◆ enable()

◆ show()

◆ hide()

◆ status()

◆ setFeatures()

◆ getFeatures()

◆ setSize()

◆ getWidth()

◆ getHeight()

◆ setPosition()

◆ getPositionX()

◆ getPositionY()

◆ setMargin()

◆ getMargin()

◆ setAlphaMod()

◆ getAlphaMod()

◆ getState()

◆ setFont()

◆ getFont()

◆ setBorderWidth()

◆ getBorderWidth()

◆ setBorderCorner()

◆ getBorderCorner()

◆ setBorderColor()

◆ getBorderColor()

◆ setBackgroundColor()

◆ getBackgroundColor()

◆ setSelectionColor()

◆ getSelectionColor()

◆ resetSkin()

◆ getSkinOverrideMask()

◆ clearBackground()

◆ setBackgroundImage() [1/3]

◆ setBackgroundImage() [2/3]

◆ setBackgroundImage() [3/3]

◆ getBackgroundImage()

◆ setBackgroundSprite() [1/3]

◆ setBackgroundSprite() [2/3]

◆ setBackgroundSprite() [3/3]

◆ getBackgroundSprite()

◆ setOnAction()

◆ setOnHoverEnter()

◆ setOnHoverExit()

◆ setOnPressed()

◆ setOnFocusLost()

◆ setOnValueCommitted()

◆ setOnSelectionChanged()

◆ setOnValueChanged()

◆ setOnToggled()

◆ setTooltip()

◆ getTooltip()

◆ setTooltipTTL()