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

Loading...
Searching...
No Matches
CRM64Pro::WidgetList
GUI modules » Widgets

List widget with single-selection or interactive multi-selection support. More...

## Detailed Description

List widget with single-selection or interactive multi-selection support.

Note
  Keyboard navigation moves the current selection. PageUp/PageDown move it by one visible page and scroll the list to keep it visible.
  Mouse wheel scrolling and setScroll() move the viewport without changing the current selection.

Inheritance diagram for CRM64Pro::WidgetList:

## Public Member Functions
bool | info (Sint32 iMode=0) override
| Request Widget object information.
Sint32 | setSize (Sint32 iWidth, Sint32 iHeight) override
| Set the size.
Sint32 | setMargin (Sint32 iTop, Sint32 iRight, Sint32 iBottom, Sint32 iLeft) override
| Set the margins.
Sint32 | getSelectedIndex () const
| Get the selected item index.
Sint32 | setSelectedIndex (Sint32 iValue)
| Select an item in the list.
Sint32 | getItemCount () const
| Get the number of items in the list.
Sint32 | setScroll (Sint32 iUnitsX, Sint32 iUnitsY)
| Modify the list scroll.
Sint32 | getScroll (Sint32 *iUnitsX, Sint32 *iUnitsY) const
| Get the current list scroll.
Sint32 | getVisibleItems (Sint32 *iUnitsX, Sint32 *iUnitsY) const
| Get the visible list area.
Sint32 | setVisibleItems (Sint32 iItems)
| Set the visible list item count.
Sint32 | setFont (Sint32 idFont, eWidgetState eWS=WS_DEFAULT) override
| Set the font.
Sint32 | setAutoSort (bool bEnable=true)
| Enable or disable automatic alphabetical sorting.
bool | isAutoSort () const
| Check whether automatic sorting is enabled.
Sint32 | setMultiSelect (bool bEnable=true)
| Enable or disable interactive multi-selection.
bool | isMultiSelect () const
| Check whether interactive multi-selection is enabled.
Sint32 | addItem (const string &sItem)
| Add an item to the list.
Sint32 | insertItem (Sint32 iIndex, const string &sItem)
| Insert an item at a specific index.
Sint32 | removeItem (Sint32 iIndex)
| Remove an item at a specific index.
Sint32 | clearItems ()
| Clear all items from the list.
Sint32 | clearSelection ()
| Clear all selected items from the list.
Sint32 | getSelectedCount () const
| Get the number of selected items.
Sint32 | getSelectedItems (vector< Sint32 > *vItems) const
| Get all selected item indices.
Sint32 | setSelectedText (const string &sText)
| Select the first item whose text exactly matches `sText`.
Sint32 | getSelectedText (string *sText=nullptr) const
| Get the selected item text.
Public Member Functions inherited from CRM64Pro::Widget
const string & | getName () const
| Get the widget name.
Uint32 | getID () const
| Get the widget ID.
eWidgetType | getType () const
| Get the widget type.
Sint32 | disable ()
| Disable a widget.
Sint32 | enable ()
| Enable a widget.
Sint32 | show ()
| Show a widget.
Sint32 | hide ()
| Hide a widget.
eGeneralStatus | status () const
| Get the widget status.
bool | setFeatures (eWidgetFeature eWF, bool bEnable)
| Set widget feature flags.
eWidgetFeature | getFeatures () const
| Get widget feature flags.
Sint32 | getWidth () const
| Get the widget width.
Sint32 | getHeight () const
| Get the widget height.
Sint32 | setPosition (const Position &posX=Position(PH_CENTER), const Position &posY=Position(PH_CENTER))
| Set the position.
const Position & | getPositionX () const
| Get the widget X position.
const Position & | getPositionY () const
| Get the widget Y position.
Sint32 | getMargin (Sint32 *iTop, Sint32 *iRight, Sint32 *iBottom, Sint32 *iLeft)
| Get the margins.
Sint32 | setAlphaMod (Uint8 iAlpha)
| Set alpha modulation used for rendering this widget.
Uint8 | getAlphaMod () const
| Get alpha modulation used for rendering this widget.
eWidgetState | getState () const
| Get the widget state.
Sint32 | getFont (eWidgetState eWS=WS_NORMAL) const
| Get the font.
Sint32 | setBorderWidth (Sint32 iWidth, eWidgetState eWS=WS_DEFAULT)
| Set the border width.
Sint32 | getBorderWidth (eWidgetState eWS=WS_NORMAL) const
| Get the border width.
Sint32 | setBorderCorner (Sint32 iRad, eWidgetState eWS=WS_DEFAULT)
| Set the border corner radius.
Sint32 | getBorderCorner (eWidgetState eWS=WS_NORMAL) const
| Get the border corner radius.
Sint32 | setBorderColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA, eWidgetState eWS=WS_DEFAULT)
| Set the border color.
Sint32 | getBorderColor (Uint8 *iR, Uint8 *iG, Uint8 *iB, Uint8 *iA, eWidgetState eWS=WS_NORMAL) const
| Get the effective border color.
Sint32 | setBackgroundColor (Uint8 iR, Uint8 iG, Uint8 iB, eWidgetState eWS=WS_DEFAULT)
| Set the background color.
Sint32 | getBackgroundColor (Uint8 *iR, Uint8 *iG, Uint8 *iB, eWidgetState eWS=WS_NORMAL) const
| Get the effective background color.
Sint32 | setSelectionColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA, eWidgetState eWS=WS_DEFAULT)
| Set the selection highlight color.
Sint32 | getSelectionColor (Uint8 *iR, Uint8 *iG, Uint8 *iB, Uint8 *iA, eWidgetState eWS=WS_NORMAL) const
| Get the effective selection highlight color.
Sint32 | resetSkin (eWidgetState eWS=WS_DEFAULT)
| Clear custom skin overrides and custom background resources.
Uint32 | getSkinOverrideMask (eWidgetState eWS=WS_NORMAL) const
| Get the custom skin override mask for one state.
Sint32 | clearBackground (eWidgetState eWS=WS_DEFAULT)
| Clear custom background resources for one state.
Sint32 | setBackgroundImage (const string &sCDCFile, const string &sName, eWidgetState eWS=WS_NORMAL)
| Set the background image.
Sint32 | setBackgroundImage (Sint32 idCDC, const string &sName, eWidgetState eWS=WS_NORMAL)
| Set the background image.
Sint32 | setBackgroundImage (Sint32 idImage, eWidgetState eWS=WS_NORMAL)
| Set the background image.
Sint32 | getBackgroundImage (eWidgetState eWS=WS_NORMAL) const
| Get the background image.
Sint32 | setBackgroundSprite (const string &sCDCFile, const string &sName, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
| Set the background sprite.
Sint32 | setBackgroundSprite (Sint32 idCDC, const string &sName, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
| Set the background sprite.
Sint32 | setBackgroundSprite (Sint32 idSprite, eWidgetState eWS=WS_DEFAULT, Sint32 iAnim=0)
| Set the background sprite.
Sint32 | getBackgroundSprite (eWidgetState eWS=WS_NORMAL, Sint32 *iAnim=nullptr) const
| Get the background sprite.
Sint32 | setOnAction (function< void(Widget &)> callback)
| Set a callback fired when the widget triggers an action.
Sint32 | setOnHoverEnter (function< void(Widget &)> callback)
| Set a callback fired when the widget starts being hovered.
Sint32 | setOnHoverExit (function< void(Widget &)> callback)
| Set a callback fired when the widget stops being hovered.
Sint32 | setOnPressed (function< void(Widget &)> callback)
| Set a callback fired when the widget is pressed.
Sint32 | setOnFocusLost (function< void(Widget &)> callback)
| Set a callback fired when the widget loses focus.
Sint32 | setOnValueCommitted (function< void(Widget &)> callback)
| Set a callback fired when an edit widget commits a changed value.
Sint32 | setOnSelectionChanged (function< void(Widget &)> callback)
| Set a callback fired when a selection widget changes selection.
Sint32 | setOnValueChanged (function< void(Widget &)> callback)
| Set a callback fired when a live value widget changes value.
Sint32 | setOnToggled (function< void(Widget &)> callback)
| Set a callback fired when a toggle widget changes state.
Sint32 | setTooltip (const string &sText)
| Set the tooltip text.
const string & | getTooltip () const
| Get the tooltip text.
Sint32 | setTooltipTTL (Sint32 iMS)
| Set the tooltip auto-hide time.
Sint32 | getTooltipTTL () const
| Get the tooltip auto-hide time.
Sint32 | setTooltipFollowCursor (bool bEnable=true)
| Set whether the tooltip follows the cursor.
bool | isTooltipFollowingCursor () const
| Check whether the tooltip follows the cursor.
Sint32 | setTooltipBackgroundColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA)
| Set the widget-local tooltip background color override.
Sint32 | getTooltipBackgroundColor (Uint8 *iR, Uint8 *iG, Uint8 *iB, Uint8 *iA) const
| Get the effective tooltip background color.
Sint32 | setTooltipBorderColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA)
| Set the widget-local tooltip border color override.
Sint32 | getTooltipBorderColor (Uint8 *iR, Uint8 *iG, Uint8 *iB, Uint8 *iA) const
| Get the effective tooltip border color.
Sint32 | setTooltipFontName (const string &sFontName)
| Set the widget-local tooltip font name override.
Sint32 | setTooltipFont (Sint32 idFont)
| Set the widget-local runtime tooltip font id override.
Sint32 | getTooltipFont () const
| Get the effective tooltip font id.
Uint32 | getTooltipOverrideMask () const
| Get the widget-local tooltip style override mask.
Sint32 | resetTooltipStyle ()
| Reset widget-local tooltip style overrides.

## Member Function Documentation

## ◆ info()

bool CRM64Pro::WidgetList::info | ( | Sint32 | iMode = 0 | ) |
| override 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 from CRM64Pro::Widget.

## ◆ setSize()

Sint32 CRM64Pro::WidgetList::setSize | ( | Sint32 | iWidth,
|  | Sint32 | iHeight )
| override 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 from CRM64Pro::Widget.

## ◆ setMargin()

Sint32 CRM64Pro::WidgetList::setMargin | ( | Sint32 | iTop,
|  | Sint32 | iRight,
|  | Sint32 | iBottom,
|  | Sint32 | iLeft )
| override 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 from CRM64Pro::Widget.

## ◆ getSelectedIndex()

Sint32 CRM64Pro::WidgetList::getSelectedIndex | ( |  | ) | const

Get the selected item index.

Returns
  Primary selected item [1,n], or 0 when no item is selected.

Note
  With multi-selection enabled, this is the anchor/current item, not the full selection set.
  List item contents and selection are runtime-owned and are not persisted in CDC widget blocks.

## ◆ setSelectedIndex()

Sint32 CRM64Pro::WidgetList::setSelectedIndex | ( | Sint32 | iValue | ) |

Select an item in the list.

Parameters

  iValue | item index [1,n] to select, or <1 to deselect.

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

Note
  If the selected item is outside the visible range, the list automatically scrolls it into view.
  This method applies a single selection. Interactive multi-selection is available when multi-selection mode is enabled.
  Programmatic selection changes are silent; EC_WIDGET_SELECTIONCHANGED is emitted only for user interaction.

## ◆ getItemCount()

Sint32 CRM64Pro::WidgetList::getItemCount | ( |  | ) | const

Get the number of items in the list.

Returns
  Number of items.

## ◆ setScroll()

Sint32 CRM64Pro::WidgetList::setScroll | ( | Sint32 | iUnitsX,
|  | Sint32 | iUnitsY )

Modify the list scroll.

WT_LIST currently implements vertical scrolling only.

Parameters

  iUnitsX | units to move scroll horizontally. Currently unsupported; nonzero values return an error.
  iUnitsY | units to move scroll vertically. Negative moves up, 0 no change, positive moves down.

Returns
  1 when the scroll position changed, 0 when unchanged, or a negative error code on failure.

## ◆ getScroll()

Sint32 CRM64Pro::WidgetList::getScroll | ( | Sint32 * | iUnitsX,
|  | Sint32 * | iUnitsY ) const

Get the current list scroll.

WT_LIST currently reports vertical scrolling only. iUnitsX is filled with 0.

Parameters

  iUnitsX | pointer to receive horizontal scroll units, or nullptr to skip. Currently always set to 0.
  iUnitsY | pointer to receive vertical scroll units, or nullptr to skip.

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

## ◆ getVisibleItems()

Sint32 CRM64Pro::WidgetList::getVisibleItems | ( | Sint32 * | iUnitsX,
|  | Sint32 * | iUnitsY ) const

Get the visible list area.

WT_LIST currently reports vertical visibility only. iUnitsX is filled with 0.

Parameters

  iUnitsX | pointer to receive visible horizontal capacity, or nullptr to skip. Currently always set to 0.
  iUnitsY | pointer to receive visible item count, or nullptr to skip.

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

## ◆ setVisibleItems()

Sint32 CRM64Pro::WidgetList::setVisibleItems | ( | Sint32 | iItems | ) |

Set the visible list item count.

Resizes the list height to fit the requested number of text rows using the active font and vertical margins.

Parameters

  iItems | Number of visible items. Must be at least 1.

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

## ◆ setFont()

Sint32 CRM64Pro::WidgetList::setFont | ( | Sint32 | idFont,
|  | eWidgetState | eWS = WS_DEFAULT )
| override 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 from CRM64Pro::Widget.

## ◆ setAutoSort()

Sint32 CRM64Pro::WidgetList::setAutoSort | ( | bool | bEnable = true | ) |

Enable or disable automatic alphabetical sorting.

When enabled, existing items are sorted immediately, current selection is cleared, inserted items are placed in sorted order and explicit insertion indices are ignored.

Parameters

  bEnable | true to enable automatic sorting, false to keep insertion order.

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

## ◆ isAutoSort()

bool CRM64Pro::WidgetList::isAutoSort | ( |  | ) | const

Check whether automatic sorting is enabled.

Returns
  true when automatic sorting is enabled, or false otherwise.

## ◆ setMultiSelect()

Sint32 CRM64Pro::WidgetList::setMultiSelect | ( | bool | bEnable = true | ) |

Enable or disable interactive multi-selection.

When enabled, Ctrl+Click toggles items and Shift+Click selects ranges.

Parameters

  bEnable | true to enable interactive multi-selection, false for single-selection mode.

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

## ◆ isMultiSelect()

bool CRM64Pro::WidgetList::isMultiSelect | ( |  | ) | const

Check whether interactive multi-selection is enabled.

Returns
  true when interactive multi-selection is enabled, or false otherwise.

## ◆ addItem()

Sint32 CRM64Pro::WidgetList::addItem | ( | const string & | sItem | ) |

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
  If auto-sort is enabled, the index depends on the alphabetical position.

## ◆ insertItem()

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

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
  The item index of the inserted item [1,n], or a negative error code on failure.

Note
  If auto-sort is enabled, iIndex is ignored and the returned index reflects the sorted position.
  If iIndex is beyond the end, the item is appended and the returned index is the final appended position.

## ◆ removeItem()

Sint32 CRM64Pro::WidgetList::removeItem | ( | Sint32 | iIndex | ) |

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.

## ◆ clearItems()

Sint32 CRM64Pro::WidgetList::clearItems | ( |  | ) |

Clear all items from the list.

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

## ◆ clearSelection()

Sint32 CRM64Pro::WidgetList::clearSelection | ( |  | ) |

Clear all selected items from the list.

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

## ◆ getSelectedCount()

Sint32 CRM64Pro::WidgetList::getSelectedCount | ( |  | ) | const

Get the number of selected items.

Returns
  Number of selected items. With single-selection mode, this is either 0 or 1.

## ◆ getSelectedItems()

Sint32 CRM64Pro::WidgetList::getSelectedItems | ( | vector< Sint32 > * | vItems | ) | const

Get all selected item indices.

Parameters

  vItems | Optional pointer to receive the selected item indices [1,n].

Returns
  Number of selected items.

## ◆ setSelectedText()

Sint32 CRM64Pro::WidgetList::setSelectedText | ( | const string & | sText | ) |

Select the first item whose text exactly matches `sText`.

Parameters

  sText | Item text to select.

Returns
  0 on success, or a negative error code when no matching item exists.

Note
  Programmatic selection changes are silent; EC_WIDGET_SELECTIONCHANGED is emitted only for user interaction.

## ◆ getSelectedText()

Sint32 CRM64Pro::WidgetList::getSelectedText | ( | string * | sText = nullptr | ) | const

Get the selected item text.

Parameters

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

Returns
  The primary selected item index [1,n], or a negative value if no item is selected.

Note
  With multi-selection enabled, this reports the anchor/current item, matching getSelectedIndex().