DigitalSpaces::DICEGUICombobox Struct Reference
[CEGUI]

#include <CEGUIInterfaces.h>

Inherits DigitalSpaces::DIObjectBase.

Public Member Functions
bool	isHit (in_Pairf *position)
	check if the given position would hit this window.
bool	getSingleClickEnabled ()
	returns the mode of operation for the combo box.
bool	isDropDownListVisible ()
	returns true if the drop down list is visible.
DICEGUIEditbox *	getEditbox ()
	Return a pointer to the Editbox component widget for this Combobox.
DICEGUIButton *	getPushButton ()
	Return a pointer to the PushButton component widget for this Combobox.
DICEGUIComboDropList *	getDropList ()
	Return a pointer to the ComboDropList component widget for this Combobox.
bool	hasInputFocus ()
	return true if the Editbox has input focus.
bool	isReadOnly ()
	return true if the Editbox is read-only.
bool	isTextValid ()
	return true if the Editbox text is valid given the currently set validation string.
const char *	getValidationString ()
	return the currently set validation string
unsigned long	getCaratIndex ()
	return the current position of the carat.
unsigned long	getSelectionStartIndex ()
	return the current selection start point.
unsigned long	getSelectionEndIndex ()
	return the current selection end point.
unsigned long	getSelectionLength ()
	return the length of the current selection (in code points / characters).
unsigned long	getMaxTextLength ()
	return the maximum text length set for this Editbox.
unsigned long	getItemCount ()
	Return number of items attached to the list box.
DICEGUIListboxItem *	getSelectedItem ()
	Return a pointer to the currently selected item.
DICEGUIListboxItem *	getListboxItemFromIndex (unsigned long index)
	Return the item at index position index.
unsigned long	getItemIndex (DICEGUIListboxItem *item)
	Return the index of ListboxItem item.
bool	isSortEnabled ()
	return whether list sorting is enabled
bool	isItemSelected (unsigned long index)
	return whether the string at index position index is selected
DICEGUIListboxItem *	findItemWithText (const char *text, DICEGUIListboxItem *start_item)
	Search the list for an item with the specified text.
bool	isListboxItemInList (DICEGUIListboxItem *item)
	Return whether the specified ListboxItem is in the List.
bool	isVertScrollbarAlwaysShown ()
	Return whether the vertical scroll bar is always shown.
bool	isHorzScrollbarAlwaysShown ()
	Return whether the horizontal scroll bar is always shown.
void	initialiseComponents ()
	Initialise the Window based object ready for use.
void	showDropList ()
	Show the drop-down list.
void	hideDropList ()
	Hide the drop-down list.
void	setSingleClickEnabled (bool setting)
	Set the mode of operation for the combo box.
void	setReadOnly (bool setting)
	Specify whether the Editbox is read-only.
void	setValidationString (const char *validation_string)
	Set the text validation string.
void	setCaratIndex (unsigned long carat_pos)
	Set the current position of the carat.
void	setSelection (unsigned long start_pos, unsigned long end_pos)
	Define the current selection for the Editbox.
void	setMaxTextLength (unsigned long max_len)
	set the maximum text length for this Editbox.
void	activateEditbox ()
	Activate the edit box component of the Combobox.
void	resetList ()
	Remove all items from the list.
void	addItem (DICEGUIListboxItem *item)
	Add the given ListboxItem to the list.
void	insertItem (DICEGUIListboxItem *item, DICEGUIListboxItem *position)
	Insert an item into the list box after a specified item already in the list.
void	removeItem (DICEGUIListboxItem *item)
	Removes the given item from the list box.
void	clearAllSelections ()
	Clear the selected state for all items.
void	setSortingEnabled (bool setting)
	Set whether the list should be sorted.
void	setShowVertScrollbar (bool setting)
	Set whether the vertical scroll bar should always be shown.
void	setShowHorzScrollbar (bool setting)
	Set whether the horizontal scroll bar should always be shown.
void	setItemSelectState (DICEGUIListboxItem *item, bool state)
	Set the select state of an attached ListboxItem.
void	setItemSelectState (unsigned long item_index, bool state)
	Set the select state of an attached ListboxItem.
void	handleUpdatedListItemData ()
	Causes the list box to update it's internal state after changes have been made to one or more attached ListboxItem objects.

---

Member Function Documentation

bool DigitalSpaces::DICEGUICombobox::isHit

(

in_Pairf *

position

)

check if the given position would hit this window.

Parameters:

position

Point object describing the position to check in screen pixels

Returns:

true if position 'hits' this Window, else false.

bool DigitalSpaces::DICEGUICombobox::getSingleClickEnabled

(

)

returns the mode of operation for the combo box.

Returns:

• true if the user can show the list and select an item with a single mouse click.
• false if the user must click to show the list and then click again to select an item.

bool DigitalSpaces::DICEGUICombobox::isDropDownListVisible

(

)

returns true if the drop down list is visible.

Returns:

true if the drop down list is visible, false otherwise.

DICEGUIEditbox* DigitalSpaces::DICEGUICombobox::getEditbox

(

)

Return a pointer to the Editbox component widget for this Combobox.

Returns:

Pointer to an Editbox object.

Exceptions:

UnknownObjectException

Thrown if the Editbox component does not exist.

DICEGUIButton* DigitalSpaces::DICEGUICombobox::getPushButton

(

)

Return a pointer to the PushButton component widget for this Combobox.

Returns:

Pointer to a PushButton object.

Exceptions:

UnknownObjectException

Thrown if the PushButton component does not exist.

DICEGUIComboDropList* DigitalSpaces::DICEGUICombobox::getDropList

(

)

Return a pointer to the ComboDropList component widget for this Combobox.

Returns:

Pointer to an ComboDropList object.

Exceptions:

UnknownObjectException

Thrown if the ComboDropList component does not exist.

bool DigitalSpaces::DICEGUICombobox::hasInputFocus

(

)

return true if the Editbox has input focus.

Returns:

true if the Editbox has keyboard input focus, false if the Editbox does not have keyboard input focus.

bool DigitalSpaces::DICEGUICombobox::isReadOnly

(

)

return true if the Editbox is read-only.

Returns:

true if the Editbox is read only and can't be edited by the user, false if the Editbox is not read only and may be edited by the user.

bool DigitalSpaces::DICEGUICombobox::isTextValid

(

)

return true if the Editbox text is valid given the currently set validation string.

Note:

It is possible to programmatically set 'invalid' text for the Editbox by calling setText. This has certain implications since if invalid text is set, whatever the user types into the box will be rejected when the input is validated.

Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed validation. If the text does not match with the regex then the text fails validation.

Returns:

true if the current Editbox text passes validation, false if the text does not pass validation.

const char* DigitalSpaces::DICEGUICombobox::getValidationString

(

)

return the currently set validation string

Note:

Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed validation. If the text does not match with the regex then the text fails validation.

Returns:

String object containing the current validation regex data

unsigned long DigitalSpaces::DICEGUICombobox::getCaratIndex

(

)

return the current position of the carat.

Returns:

Index of the insert carat relative to the start of the text.

unsigned long DigitalSpaces::DICEGUICombobox::getSelectionStartIndex

(

)

return the current selection start point.

Returns:

Index of the selection start point relative to the start of the text. If no selection is defined this function returns the position of the carat.

unsigned long DigitalSpaces::DICEGUICombobox::getSelectionEndIndex

(

)

return the current selection end point.

Returns:

Index of the selection end point relative to the start of the text. If no selection is defined this function returns the position of the carat.

unsigned long DigitalSpaces::DICEGUICombobox::getSelectionLength

(

)

return the length of the current selection (in code points / characters).

Returns:

Number of code points (or characters) contained within the currently defined selection.

unsigned long DigitalSpaces::DICEGUICombobox::getMaxTextLength

(

)

return the maximum text length set for this Editbox.

Returns:

The maximum number of code points (characters) that can be entered into this Editbox.

Note:

Depending on the validation string set, the actual length of text that can be entered may be less than the value returned here (it will never be more).

unsigned long DigitalSpaces::DICEGUICombobox::getItemCount

(

)

Return number of items attached to the list box.

Returns:

the number of items currently attached to this list box.

DICEGUIListboxItem* DigitalSpaces::DICEGUICombobox::getSelectedItem

(

)

Return a pointer to the currently selected item.

Returns:

Pointer to a ListboxItem based object that is the selected item in the list. will return NULL if no item is selected.

DICEGUIListboxItem* DigitalSpaces::DICEGUICombobox::getListboxItemFromIndex

(

unsigned long

index

)

Return the item at index position index.

Parameters:

index

Zero based index of the item to be returned.

Returns:

Pointer to the ListboxItem at index position index in the list box.

Exceptions:

InvalidRequestException

thrown if index is out of range.

unsigned long DigitalSpaces::DICEGUICombobox::getItemIndex

(

DICEGUIListboxItem *

item

)

Return the index of ListboxItem item.

Parameters:

item

Pointer to a ListboxItem whos zero based index is to be returned.

Returns:

Zero based index indicating the position of ListboxItem item in the list box.

Exceptions:

InvalidRequestException

thrown if item is not attached to this list box.

bool DigitalSpaces::DICEGUICombobox::isSortEnabled

(

)

return whether list sorting is enabled

Returns:

true if the list is sorted, false if the list is not sorted

bool DigitalSpaces::DICEGUICombobox::isItemSelected

(

unsigned long

index

)

return whether the string at index position index is selected

Parameters:

index

Zero based index of the item to be examined.

Returns:

true if the item at index is selected, false if the item at index is not selected.

Exceptions:

InvalidRequestException

thrown if index is out of range.

DICEGUIListboxItem* DigitalSpaces::DICEGUICombobox::findItemWithText	(	const char *	text,
		DICEGUIListboxItem *	start_item
	)

Search the list for an item with the specified text.

Parameters:

	text	String object containing the text to be searched for.
	start_item	ListboxItem where the search is to begin, the search will not include item. If item is NULL, the search will begin from the first item in the list.

Returns:

Pointer to the first ListboxItem in the list after item that has text matching text. If no item matches the criteria NULL is returned.

Exceptions:

InvalidRequestException

thrown if item is not attached to this list box.

bool DigitalSpaces::DICEGUICombobox::isListboxItemInList

(

DICEGUIListboxItem *

item

)

Return whether the specified ListboxItem is in the List.

Returns:

true if ListboxItem item is in the list, false if ListboxItem item is not in the list.

bool DigitalSpaces::DICEGUICombobox::isVertScrollbarAlwaysShown

(

)

Return whether the vertical scroll bar is always shown.

Returns:

• true if the scroll bar will always be shown even if it is not required.
• false if the scroll bar will only be shown when it is required.

bool DigitalSpaces::DICEGUICombobox::isHorzScrollbarAlwaysShown

(

)

Return whether the horizontal scroll bar is always shown.

Returns:

• true if the scroll bar will always be shown even if it is not required.
• false if the scroll bar will only be shown when it is required.

void DigitalSpaces::DICEGUICombobox::initialiseComponents

(

)

Initialise the Window based object ready for use.

Note:

This must be called for every window created. Normally this is handled automatically by the WindowFactory for each Window type.

Returns:

Nothing

void DigitalSpaces::DICEGUICombobox::showDropList

(

)

Show the drop-down list.

Returns:

Nothing

void DigitalSpaces::DICEGUICombobox::hideDropList

(

)

Hide the drop-down list.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setSingleClickEnabled

(

bool

setting

)

Set the mode of operation for the combo box.

Parameters:

setting

true if the user should be able to show the list and select an item with a single mouse click. false if the user must click to show the list and then click again to select an item.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setReadOnly

(

bool

setting

)

Specify whether the Editbox is read-only.

Parameters:

setting

true if the Editbox is read only and can't be edited by the user, false if the Editbox is not read only and may be edited by the user.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setValidationString

(

const char *

validation_string

)

Set the text validation string.

Note:

Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed validation. If the text does not match with the regex then the text fails validation.

Parameters:

validation_string

String object containing the validation regex data to be used.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setCaratIndex

(

unsigned long

carat_pos

)

Set the current position of the carat.

Parameters:

carat_pos

New index for the insert carat relative to the start of the text. If the value specified is greater than the number of characters in the Editbox, the carat is positioned at the end of the text.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setSelection	(	unsigned long	start_pos,
		unsigned long	end_pos
	)

Define the current selection for the Editbox.

Parameters:

	start_pos	Index of the starting point for the selection. If this value is greater than the number of characters in the Editbox, the selection start will be set to the end of the text.
	end_pos	Index of the ending point for the selection. If this value is greater than the number of characters in the Editbox, the selection start will be set to the end of the text.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setMaxTextLength

(

unsigned long

max_len

)

set the maximum text length for this Editbox.

Parameters:

max_len

The maximum number of code points (characters) that can be entered into this Editbox.

Note:

Depending on the validation string set, the actual length of text that can be entered may be less than the value set here (it will never be more).

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::activateEditbox

(

)

Activate the edit box component of the Combobox.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::resetList

(

)

Remove all items from the list.

Note that this will cause 'AutoDelete' items to be deleted.

void DigitalSpaces::DICEGUICombobox::addItem

(

DICEGUIListboxItem *

item

)

Add the given ListboxItem to the list.

Parameters:

item

Pointer to the ListboxItem to be added to the list. Note that it is the passed object that is added to the list, a copy is not made. If this parameter is NULL, nothing happens.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::insertItem	(	DICEGUIListboxItem *	item,
		DICEGUIListboxItem *	position
	)

Insert an item into the list box after a specified item already in the list.

Note that if the list is sorted, the item may not end up in the requested position.

Parameters:

	item	Pointer to the ListboxItem to be inserted. Note that it is the passed object that is added to the list, a copy is not made. If this parameter is NULL, nothing happens.
	position	Pointer to a ListboxItem that item is to be inserted after. If this parameter is NULL, the item is inserted at the start of the list.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::removeItem

(

DICEGUIListboxItem *

item

)

Removes the given item from the list box.

Parameters:

item

Pointer to the ListboxItem that is to be removed. If item is not attached to this list box then nothing will happen.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::clearAllSelections

(

)

Clear the selected state for all items.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setSortingEnabled

(

bool

setting

)

Set whether the list should be sorted.

Parameters:

setting

true if the list should be sorted, false if the list should not be sorted.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setShowVertScrollbar

(

bool

setting

)

Set whether the vertical scroll bar should always be shown.

Parameters:

setting

true if the vertical scroll bar should be shown even when it is not required. false if the vertical scroll bar should only be shown when it is required.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setShowHorzScrollbar

(

bool

setting

)

Set whether the horizontal scroll bar should always be shown.

Parameters:

setting

true if the horizontal scroll bar should be shown even when it is not required. false if the horizontal scroll bar should only be shown when it is required.

Returns:

Nothing.

void DigitalSpaces::DICEGUICombobox::setItemSelectState	(	DICEGUIListboxItem *	item,
		bool	state
	)

Set the select state of an attached ListboxItem.

This is the recommended way of selecting and deselecting items attached to a list box as it respects the multi-select mode setting. It is possible to modify the setting on ListboxItems directly, but that approach does not respect the settings of the list box.

Parameters:

	item	The ListboxItem to be affected. This item must be attached to the list box.
	state	true to select the item, false to de-select the item.

Returns:

Nothing.

Exceptions:

InvalidRequestException

thrown if item is not attached to this list box.

void DigitalSpaces::DICEGUICombobox::setItemSelectState	(	unsigned long	item_index,
		bool	state
	)

Set the select state of an attached ListboxItem.

This is the recommended way of selecting and deselecting items attached to a list box as it respects the multi-select mode setting. It is possible to modify the setting on ListboxItems directly, but that approach does not respect the settings of the list box.

Parameters:

	item_index	The zero based index of the ListboxItem to be affected. This must be a valid index (0 <= index < getItemCount())
	state	true to select the item, false to de-select the item.

Returns:

Nothing.

Exceptions:

InvalidRequestException

thrown if item_index is out of range for the list box

void DigitalSpaces::DICEGUICombobox::handleUpdatedListItemData

(

)

Causes the list box to update it's internal state after changes have been made to one or more attached ListboxItem objects.

Client code must call this whenever it has made any changes to ListboxItem objects already attached to the list box. If you are just adding items, or removed items to update them prior to re-adding them, there is no need to call this method.

Returns:

Nothing.

---

The documentation for this struct was generated from the following file:

• CEGUIInterfaces/CEGUIInterfaces.h