CRM64Pro::WidgetComboBox

ComboBox widget for drop-down single selection. More...

Detailed Description

ComboBox widget for drop-down single selection.

Displays the selected text item and opens a popup list when activated. It shares list-style item management while keeping one active selection.

Inheritance diagram for CRM64Pro::WidgetComboBox:

Public Member Functions
bool	info (Sint32 iMode=0) override
	Request ComboBox information.
Sint32	setSize (Sint32 iWidth, Sint32 iHeight) override
	Set the ComboBox size.
bool	setMargin (Sint32 iTop, Sint32 iRight, Sint32 iBottom, Sint32 iLeft) override
	Set ComboBox content margins.
Sint32	setSelectedIndex (Sint32 iValue)
	Select an item in the ComboBox.
Sint32	getSelectedIndex () const
	Get the selected item index.
Sint32	getItemCount () const
	Get the number of items in the ComboBox.
Sint32	setScroll (Sint32 iUnits, bool *bChanged=nullptr)
	Modify the popup list scroll.
bool	getScroll (Sint32 *iUnits) const
	Get the current popup list scroll.
bool	getVisibleItems (Sint32 *iUnits) const
	Get the visible popup capacity.
Sint32	setVisibleItems (Sint32 iItems)
	Set the visible popup item count.
Sint32	setFont (Sint32 idFont, eWidgetState eWS=WS_DEFAULT) override
	Set the ComboBox font.
Sint32	setAutoSort (bool bEnable=true)
	Enable or disable automatic alphabetical sorting.
bool	isAutoSort () const
	Check whether automatic sorting is enabled.
Sint32	addItem (const string &sItem)
	Add an item to the ComboBox.
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 ComboBox.
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.
Sint32	open ()
	Open the popup list.
Sint32	close ()
	Close the popup list.
bool	isOpen () const
	Check whether the popup list is open.
Public Member Functions inherited from CRM64Pro::Widget
const string &	getName () const
	Get the widget name.
Sint32	getID () const
	Get the widget ID.
eWidgetType	getType () const
	Get the widget type.
bool	disable ()
	Disable a widget.
bool	enable ()
	Enable a widget.
bool	show ()
	Show a widget.
bool	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 &rPosX=Position(PH_CENTER), const Position &rPosY=Position(PH_CENTER))
	Set the position.
const Position &	getPositionX () const
	Get the widget X position.
const Position &	getPositionY () const
	Get the widget Y position.
bool	getMargin (Sint32 *iTop, Sint32 *iRight, Sint32 *iBottom, Sint32 *iLeft)
	Get the margins.
bool	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.
bool	setOnAction (function< void(Widget &)> fnCallback)
	Set a callback fired when the widget triggers an action.
bool	setOnHoverEnter (function< void(Widget &)> fnCallback)
	Set a callback fired when the widget starts being hovered.
bool	setOnHoverExit (function< void(Widget &)> fnCallback)
	Set a callback fired when mouse hover exits the widget.
bool	setOnPressed (function< void(Widget &)> fnCallback)
	Set a callback fired when the widget is pressed.
bool	setOnFocusLost (function< void(Widget &)> fnCallback)
	Set a callback fired when the widget loses focus.
bool	setOnValueCommitted (function< void(Widget &)> fnCallback)
	Set a callback fired when an edit widget commits a changed value.
bool	setOnSelectionChanged (function< void(Widget &)> fnCallback)
	Set a callback fired when a selection widget changes selection.
bool	setOnValueChanged (function< void(Widget &)> fnCallback)
	Set a callback fired when a live value widget changes value.
bool	setOnToggled (function< void(Widget &)> fnCallback)
	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.
bool	setTooltipBackgroundColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA)
	Set the widget-local tooltip background color override.
bool	getTooltipBackgroundColor (Uint8 *iR, Uint8 *iG, Uint8 *iB, Uint8 *iA) const
	Get the effective tooltip background color.
bool	setTooltipBorderColor (Uint8 iR, Uint8 iG, Uint8 iB, Uint8 iA)
	Set the widget-local tooltip border color override.
bool	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::WidgetComboBox::info ( Sint32 iMode = 0 )

overridevirtual

Request ComboBox information.

Writes information to the default log.

Parameters

iMode

currently forwarded to the common widget info path.

Returns

true on success, or false on failure.

Reimplemented from CRM64Pro::Widget.

setSize()

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

overridevirtual

Set the ComboBox size.

Parameters

iWidth	New width.
iHeight	New height. The final height is clamped to fit at least one text row plus margins.

Returns

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

Reimplemented from CRM64Pro::Widget.

setMargin()

bool CRM64Pro::WidgetComboBox::setMargin ( Sint32 iTop, Sint32 iRight, Sint32 iBottom, Sint32 iLeft )

overridevirtual

Set ComboBox content margins.

Parameters

iTop	Top margin.
iRight	Right margin.
iBottom	Bottom margin.
iLeft	Left margin.

Returns

true on success, or false on failure.

Reimplemented from CRM64Pro::Widget.

setSelectedIndex()

Sint32 CRM64Pro::WidgetComboBox::setSelectedIndex

(

Sint32

iValue

)

Select an item in the ComboBox.

Parameters

iValue

Item index [1,n] to select, or <1 to clear the current selection.

Returns

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

Note

Selecting an item also scrolls the popup viewport as needed so the item is visible when opened.

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

getSelectedIndex()

Sint32 CRM64Pro::WidgetComboBox::getSelectedIndex

(

)

const

Get the selected item index.

Returns

Selected item index [1,n], or 0 when no item is selected.

Note

ComboBox item contents and selection are runtime-owned and are not persisted in CDC widget blocks.

getItemCount()

Sint32 CRM64Pro::WidgetComboBox::getItemCount

(

)

const

Get the number of items in the ComboBox.

Returns

Number of items currently stored.

setScroll()

Sint32 CRM64Pro::WidgetComboBox::setScroll	(	Sint32	iUnits,
		bool *	bChanged = nullptr )

Modify the popup list scroll.

Parameters

iUnits	Units to move scroll vertically. Negative moves up, 0 no change, positive moves down.
bChanged	optional pointer filled with true when the scroll position changed, or false otherwise.

Returns

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

getScroll()

bool CRM64Pro::WidgetComboBox::getScroll

(

Sint32 *

iUnits

)

const

Get the current popup list scroll.

Parameters

iUnits

Pointer to receive vertical scroll units, or nullptr to skip.

Returns

true on success, or false on failure.

getVisibleItems()

bool CRM64Pro::WidgetComboBox::getVisibleItems

(

Sint32 *

iUnits

)

const

Get the visible popup capacity.

Parameters

iUnits

Pointer to receive visible popup item count, or nullptr to skip.

Returns

true on success, or false on failure.

setVisibleItems()

Sint32 CRM64Pro::WidgetComboBox::setVisibleItems

(

Sint32

iItems

)

Set the visible popup item count.

Changes the maximum number of items shown by the open popup before scrolling is needed.

Parameters

iItems

Number of visible popup items. Must be at least 1.

Returns

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

Note

The selected item is preserved and the popup scroll is clamped to the new capacity.

setFont()

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

overridevirtual

Set the ComboBox font.

Parameters

idFont	Font id.
eWS	Widget state. WS_ACTION is used by the selected popup item and WS_HOVERED by the hovered popup item.

Returns

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

Reimplemented from CRM64Pro::Widget.

setAutoSort()

Sint32 CRM64Pro::WidgetComboBox::setAutoSort

(

bool

bEnable = true

)

Enable or disable automatic alphabetical sorting.

When enabled, 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::WidgetComboBox::isAutoSort

(

)

const

Check whether automatic sorting is enabled.

Returns

true when automatic sorting is enabled, or false otherwise.

addItem()

Sint32 CRM64Pro::WidgetComboBox::addItem

(

const string &

sItem

)

Add an item to the ComboBox.

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.

When the first item is added to an empty ComboBox, it becomes the current selection automatically.

insertItem()

Sint32 CRM64Pro::WidgetComboBox::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.

When the first item is inserted into an empty ComboBox, it becomes the current selection automatically.

removeItem()

Sint32 CRM64Pro::WidgetComboBox::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::WidgetComboBox::clearItems

(

)

Clear all items from the ComboBox.

Returns

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

Note

Clearing items also clears the current selection and closes the popup if it is open.

setSelectedText()

Sint32 CRM64Pro::WidgetComboBox::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::WidgetComboBox::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

Selected item index [1,n], or 0 when no item is selected.

open()

Sint32 CRM64Pro::WidgetComboBox::open

(

)

Open the popup list.

Returns

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

Note

Fails when the ComboBox has no items to display.

close()

Sint32 CRM64Pro::WidgetComboBox::close

(

)

Close the popup list.

Returns

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

isOpen()

bool CRM64Pro::WidgetComboBox::isOpen

(

)

const

Check whether the popup list is open.

Returns

true when the popup list is open, or false otherwise.