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 )

overridevirtual

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 )

overridevirtual

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 )

overridevirtual

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 )

overridevirtual

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().

Detailed Description

Public Member Functions

Member Function Documentation

◆ info()

◆ setSize()

◆ setMargin()

◆ getSelectedIndex()

◆ setSelectedIndex()

◆ getItemCount()

◆ setScroll()

◆ getScroll()

◆ getVisibleItems()

◆ setVisibleItems()

◆ setFont()

◆ setAutoSort()

◆ isAutoSort()

◆ setMultiSelect()

◆ isMultiSelect()

◆ addItem()

◆ insertItem()

◆ removeItem()

◆ clearItems()

◆ clearSelection()

◆ getSelectedCount()

◆ getSelectedItems()

◆ setSelectedText()

◆ getSelectedText()