| CRM64Pro GDK v0.15.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Widgets
GUI modules

## 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. Background disabled by default.
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 bool | 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.
eGeneralStatus | CRM64Pro::Widget::status () const
| Get the widget status.
bool | CRM64Pro::Widget::setFeatures (Uint32 iFeatures, bool bEnable)
| Set advanced features.
Uint32 | CRM64Pro::Widget::getFeatures () const
| Get advanced features.
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.
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) const
| Get the text.
virtual string | CRM64Pro::Widget::getLine (Sint32 iLineIndex) const
| Get a specific line of text.
virtual Sint32 | CRM64Pro::Widget::getLineCount () const
| 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 Sint32 | CRM64Pro::Widget::getSelectedItem (string *sItem=nullptr) const
| 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 () const
| 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 () const
| 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) const
| Get the widget current scroll.
virtual Sint32 | CRM64Pro::Widget::getVisibleItems (Sint32 *iUnitsX, Sint32 *iUnitsY) const
| 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 () const
| 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 &sCDCFile, 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 &sCDCFile, 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 EC_WIDGET_ACTION event.

## ◆ WIDGET_FEATURE_MOUSEOVER

#define WIDGET_FEATURE_MOUSEOVER 0x00800000

Widget feature: allow the widget to generate EC_WIDGET_MOUSEHOVER events.

## ◆ WIDGET_FEATURE_LOSTFOCUS

#define WIDGET_FEATURE_LOSTFOCUS 0x01000000

Widget feature: allow the widget to generate EC_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 and Console 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()

bool 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
  true on success, or false 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()

eGeneralStatus CRM64Pro::Widget::status | ( |  | ) | const

Get the widget status.

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

## ◆ setFeatures()

bool CRM64Pro::Widget::setFeatures | ( | Uint32 | iFeatures,
|  | bool | bEnable )

Set advanced features.

Check WIDGET_FEATURE_x defines for a list of supported features.

Parameters

  iFeatures | 32bits unsigned integer with desired features.
  bEnable | true to enable the features, false to disable them.

Returns
  true on success or false on failure.

## ◆ getFeatures()

Uint32 CRM64Pro::Widget::getFeatures | ( |  | ) | const

Get advanced features.

Returns
  32bits unsigned integer with current features.

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

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

## ◆ 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 ) const
| 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 | ) | const
| 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 | ( |  | ) | const
| 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, n], 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()

Sint32 CRM64Pro::Widget::getSelectedItem | ( | string * | sItem = nullptr | ) | const
| virtual

Get the selected item text.

Parameters

  sItem | Optional pointer to receive the selected item text. If nullptr, the text is not retrieved.

Returns
  The index of the selected item [1,n], or a negative value 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 | ( |  | ) | const
| 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 | ( |  | ) | const
| 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 ) const
| 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 ) const
| 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 | ( |  | ) | const
| 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 & | 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/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 & | 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 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.