CEGUI::Combobox Class Reference

Base class for the Combobox widget. More...

Inheritance diagram for CEGUI::Combobox:

Collaboration diagram for CEGUI::Combobox:

Public Member Functions
bool	isHit (const Vector2 &position, const bool allow_disabled=false) const
	check if the given pixel position would hit this window.
bool	getSingleClickEnabled (void) const
	returns the mode of operation for the combo box.
bool	isDropDownListVisible (void) const
	returns true if the drop down list is visible.
Editbox *	getEditbox () const
	Return a pointer to the Editbox component widget for this Combobox.
PushButton *	getPushButton () const
	Return a pointer to the PushButton component widget for this Combobox.
ComboDropList *	getDropList () const
	Return a pointer to the ComboDropList component widget for this Combobox.
bool	hasInputFocus (void) const
	return true if the Editbox has input focus.
bool	isReadOnly (void) const
	return true if the Editbox is read-only.
bool	isTextValid (void) const
	return true if the Editbox text is valid given the currently set validation string.
const String &	getValidationString (void) const
	return the currently set validation string
size_t	getCaratIndex (void) const
	return the current position of the carat.
size_t	getSelectionStartIndex (void) const
	return the current selection start point.
size_t	getSelectionEndIndex (void) const
	return the current selection end point.
size_t	getSelectionLength (void) const
	return the length of the current selection (in code points / characters).
size_t	getMaxTextLength (void) const
	return the maximum text length set for this Editbox.
size_t	getItemCount (void) const
	Return number of items attached to the list box.
ListboxItem *	getSelectedItem (void) const
	Return a pointer to the currently selected item.
ListboxItem *	getListboxItemFromIndex (size_t index) const
	Return the item at index position index.
size_t	getItemIndex (const ListboxItem *item) const
	Return the index of ListboxItem item.
bool	isSortEnabled (void) const
	return whether list sorting is enabled
bool	isItemSelected (size_t index) const
	return whether the string at index position index is selected
ListboxItem *	findItemWithText (const String &text, const ListboxItem *start_item)
	Search the list for an item with the specified text.
bool	isListboxItemInList (const ListboxItem *item) const
	Return whether the specified ListboxItem is in the List.
bool	isVertScrollbarAlwaysShown (void) const
	Return whether the vertical scroll bar is always shown.
bool	isHorzScrollbarAlwaysShown (void) const
	Return whether the horizontal scroll bar is always shown.
virtual void	initialiseComponents (void)
	Initialise the Window based object ready for use.
void	showDropList (void)
	Show the drop-down list.
void	hideDropList (void)
	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 String &validation_string)
	Set the text validation string.
void	setCaratIndex (size_t carat_pos)
	Set the current position of the carat.
void	setSelection (size_t start_pos, size_t end_pos)
	Define the current selection for the Editbox.
void	setMaxTextLength (size_t max_len)
	set the maximum text length for this Editbox.
void	activateEditbox (void)
	Activate the edit box component of the Combobox.
void	resetList (void)
	Remove all items from the list.
void	addItem (ListboxItem *item)
	Add the given ListboxItem to the list.
void	insertItem (ListboxItem item, const ListboxItem position)
	Insert an item into the list box after a specified item already in the list.
void	removeItem (const ListboxItem *item)
	Removes the given item from the list box.
void	clearAllSelections (void)
	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 (ListboxItem *item, bool state)
	Set the select state of an attached ListboxItem.
void	setItemSelectState (size_t item_index, bool state)
	Set the select state of an attached ListboxItem.
void	handleUpdatedListItemData (void)
	Causes the list box to update it's internal state after changes have been made to one or more attached ListboxItem objects.
	Combobox (const String &type, const String &name)
	Constructor for Combobox base class.
virtual	~Combobox (void)
	Destructor for Combobox base class.
Static Public Attributes
static const String	EventNamespace
	Namespace for global events.
static const String	WidgetTypeName
	Window factory name.
static const String	EventReadOnlyModeChanged
	The read-only mode for the edit box has been changed.
static const String	EventValidationStringChanged
	The validation string has been changed.
static const String	EventMaximumTextLengthChanged
	The maximum allowable string length has been changed.
static const String	EventTextInvalidated
	Some operation has made the current text invalid with regards to the validation string.
static const String	EventInvalidEntryAttempted
	The user attempted to modify the text in a way that would have made it invalid.
static const String	EventCaratMoved
	The text carat (insert point) has changed.
static const String	EventTextSelectionChanged
	The current text selection has changed.
static const String	EventEditboxFull
	The number of characters in the edit box has reached the current maximum.
static const String	EventTextAccepted
	The user has accepted the current text by pressing Return, Enter, or Tab.
static const String	EventListContentsChanged
	Event triggered when the contents of the list is changed.
static const String	EventListSelectionChanged
	Event triggered when there is a change to the currently selected item(s).
static const String	EventSortModeChanged
	Event triggered when the sort mode setting changes.
static const String	EventVertScrollbarModeChanged
	Event triggered when the vertical scroll bar 'force' setting changes.
static const String	EventHorzScrollbarModeChanged
	Event triggered when the horizontal scroll bar 'force' setting changes.
static const String	EventDropListDisplayed
	Event triggered when the drop-down list is displayed.
static const String	EventDropListRemoved
	Event triggered when the drop-down list is removed / hidden.
static const String	EventListSelectionAccepted
	Event triggered when the user accepts a selection from the drop-down list.
static const String	EditboxNameSuffix
	Widget name suffix for the editbox component.
static const String	DropListNameSuffix
	Widget name suffix for the drop list component.
static const String	ButtonNameSuffix
	Widget name suffix for the button component.
Protected Member Functions
bool	button_PressHandler (const EventArgs &e)
	Handler function for button clicks.
bool	droplist_SelectionAcceptedHandler (const EventArgs &e)
	Handler for selections made in the drop-list.
bool	droplist_HiddenHandler (const EventArgs &e)
	Handler for when drop-list hides itself.
bool	editbox_MouseDownHandler (const EventArgs &e)
	Mouse button down handler attached to edit box.
virtual bool	testClassName_impl (const String &class_name) const
	Return whether this window was inherited from the given class name at some point in the inheritance hierarchy.
void	itemSelectChangeTextUpdate (const ListboxItem *const item, bool new_state, bool old_state)
	Update the Combobox text to reflect programmatically made changes to selected list item.
bool	editbox_ReadOnlyChangedHandler (const EventArgs &e)
bool	editbox_ValidationStringChangedHandler (const EventArgs &e)
bool	editbox_MaximumTextLengthChangedHandler (const EventArgs &e)
bool	editbox_TextInvalidatedEventHandler (const EventArgs &e)
bool	editbox_InvalidEntryAttemptedHandler (const EventArgs &e)
bool	editbox_CaratMovedHandler (const EventArgs &e)
bool	editbox_TextSelectionChangedHandler (const EventArgs &e)
bool	editbox_EditboxFullEventHandler (const EventArgs &e)
bool	editbox_TextAcceptedEventHandler (const EventArgs &e)
bool	editbox_TextChangedEventHandler (const EventArgs &e)
bool	listbox_ListContentsChangedHandler (const EventArgs &e)
bool	listbox_ListSelectionChangedHandler (const EventArgs &e)
bool	listbox_SortModeChangedHandler (const EventArgs &e)
bool	listbox_VertScrollModeChangedHandler (const EventArgs &e)
bool	listbox_HorzScrollModeChangedHandler (const EventArgs &e)
virtual void	onReadOnlyChanged (WindowEventArgs &e)
	Handler called internally when the read only state of the Combobox's Editbox has been changed.
virtual void	onValidationStringChanged (WindowEventArgs &e)
	Handler called internally when the Combobox's Editbox validation string has been changed.
virtual void	onMaximumTextLengthChanged (WindowEventArgs &e)
	Handler called internally when the Combobox's Editbox maximum text length is changed.
virtual void	onTextInvalidatedEvent (WindowEventArgs &e)
	Handler called internally when the Combobox's Editbox text has been invalidated.
virtual void	onInvalidEntryAttempted (WindowEventArgs &e)
	Handler called internally when an invalid entry was attempted in the Combobox's Editbox.
virtual void	onCaratMoved (WindowEventArgs &e)
	Handler called internally when the carat in the Comboxbox's Editbox moves.
virtual void	onTextSelectionChanged (WindowEventArgs &e)
	Handler called internally when the selection within the Combobox's Editbox changes.
virtual void	onEditboxFullEvent (WindowEventArgs &e)
	Handler called internally when the maximum length is reached for text in the Combobox's Editbox.
virtual void	onTextAcceptedEvent (WindowEventArgs &e)
	Handler called internally when the text in the Combobox's Editbox is accepted (by various means).
virtual void	onListContentsChanged (WindowEventArgs &e)
	Handler called internally when the Combobox's Drop-down list contents are changed.
virtual void	onListSelectionChanged (WindowEventArgs &e)
	Handler called internally when the selection within the Combobox's drop-down list changes (this is not the 'final' accepted selection, just the currently highlighted item).
virtual void	onSortModeChanged (WindowEventArgs &e)
	Handler called fired internally when the sort mode for the Combobox's drop-down list is changed.
virtual void	onVertScrollbarModeChanged (WindowEventArgs &e)
	Handler called internally when the 'force' setting for the vertical scrollbar within the Combobox's drop-down list is changed.
virtual void	onHorzScrollbarModeChanged (WindowEventArgs &e)
	Handler called internally when the 'force' setting for the horizontal scrollbar within the Combobox's drop-down list is changed.
virtual void	onDropListDisplayed (WindowEventArgs &e)
	Handler called internally when the Combobox's drop-down list has been displayed.
virtual void	onDroplistRemoved (WindowEventArgs &e)
	Handler called internally when the Combobox's drop-down list has been hidden.
virtual void	onListSelectionAccepted (WindowEventArgs &e)
	Handler called internally when the user has confirmed a selection within the Combobox's drop-down list.
virtual void	onFontChanged (WindowEventArgs &e)
	Handler called when the window's font is changed.
virtual void	onTextChanged (WindowEventArgs &e)
	Handler called when the window's text is changed.
virtual void	onActivated (ActivationEventArgs &e)
	Handler called when this window has become the active window.
Protected Attributes
bool	d_singleClickOperation
	true if user can show and select from list in a single click.

Detailed Description

Base class for the Combobox widget.

Member Function Documentation

void CEGUI::Combobox::activateEditbox ( void )

Activate the edit box component of the Combobox.

Returns:: Nothing.

void CEGUI::Combobox::addItem ( ListboxItem * 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 CEGUI::Combobox::clearAllSelections ( void )

Clear the selected state for all items.

Returns:: Nothing.

ListboxItem* CEGUI::Combobox::findItemWithText	(	const String &	text,
		const ListboxItem *	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.

size_t CEGUI::Combobox::getCaratIndex ( void ) const

return the current position of the carat.

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

ComboDropList* CEGUI::Combobox::getDropList ( ) const

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.

Editbox* CEGUI::Combobox::getEditbox ( ) const

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.

size_t CEGUI::Combobox::getItemCount ( void ) const

Return number of items attached to the list box.

Returns:: the number of items currently attached to this list box.

size_t CEGUI::Combobox::getItemIndex ( const ListboxItem * item ) const

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.

ListboxItem* CEGUI::Combobox::getListboxItemFromIndex ( size_t index ) const

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.

size_t CEGUI::Combobox::getMaxTextLength ( void ) const

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

PushButton* CEGUI::Combobox::getPushButton ( ) const

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.

ListboxItem* CEGUI::Combobox::getSelectedItem ( void ) const

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.

size_t CEGUI::Combobox::getSelectionEndIndex ( void ) const

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.

size_t CEGUI::Combobox::getSelectionLength ( void ) const

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

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

size_t CEGUI::Combobox::getSelectionStartIndex ( void ) const

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.

bool CEGUI::Combobox::getSingleClickEnabled ( void ) const

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.

const String& CEGUI::Combobox::getValidationString ( void ) const

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

void CEGUI::Combobox::handleUpdatedListItemData ( void )

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.

bool CEGUI::Combobox::hasInputFocus ( void ) const

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.

void CEGUI::Combobox::hideDropList ( void )

Hide the drop-down list.

Returns:: Nothing.

virtual void CEGUI::Combobox::initialiseComponents ( void ) [virtual]

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

Reimplemented from CEGUI::Window.

void CEGUI::Combobox::insertItem	(	ListboxItem *	item,
		const ListboxItem *	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.

bool CEGUI::Combobox::isDropDownListVisible ( void ) const

returns true if the drop down list is visible.

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

bool CEGUI::Combobox::isHit	(	const Vector2 &	position,
		const bool	allow_disabled = `false`
	)			const `[virtual]`

check if the given pixel position would hit this window.

Parameters:

	position	Vector2 object describing the position to check. The position describes a pixel offset from the top-left corner of the display.
	allow_disabled	true specifies that the window may be 'hit' if it is disabled. false specifies that the window may only be hit if it is enabled.

Returns:

true if position hits this Window.
false if position does not hit this window.

Reimplemented from CEGUI::Window.

bool CEGUI::Combobox::isHorzScrollbarAlwaysShown ( void ) const

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.

bool CEGUI::Combobox::isItemSelected ( size_t index ) const

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.

bool CEGUI::Combobox::isListboxItemInList ( const ListboxItem * item ) const

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 CEGUI::Combobox::isReadOnly ( void ) const

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 CEGUI::Combobox::isSortEnabled ( void ) const

return whether list sorting is enabled

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

bool CEGUI::Combobox::isTextValid ( void ) const

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.

bool CEGUI::Combobox::isVertScrollbarAlwaysShown ( void ) const

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.

virtual void CEGUI::Combobox::onActivated ( ActivationEventArgs & e ) [protected, virtual]

Handler called when this window has become the active window.

Parameters:

e

ActivationEventArgs class whose 'otherWindow' field is set to the window that previously was active, or NULL for none.

Reimplemented from CEGUI::Window.

virtual void CEGUI::Combobox::onFontChanged ( WindowEventArgs & e ) [protected, virtual]

Handler called when the window's font is changed.

Parameters:

e

WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event. For this event the trigger window is always 'this'.

Reimplemented from CEGUI::Window.

virtual void CEGUI::Combobox::onTextChanged ( WindowEventArgs & e ) [protected, virtual]

Handler called when the window's text is changed.

Parameters:

e

WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event. For this event the trigger window is always 'this'.

Reimplemented from CEGUI::Window.

void CEGUI::Combobox::removeItem ( const ListboxItem * 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 CEGUI::Combobox::resetList ( void )

Remove all items from the list.

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

void CEGUI::Combobox::setCaratIndex ( size_t 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 CEGUI::Combobox::setItemSelectState	(	size_t	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 CEGUI::Combobox::setItemSelectState	(	ListboxItem *	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 CEGUI::Combobox::setMaxTextLength ( size_t 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 CEGUI::Combobox::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 CEGUI::Combobox::setSelection	(	size_t	start_pos,
		size_t	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 CEGUI::Combobox::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 CEGUI::Combobox::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 CEGUI::Combobox::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 CEGUI::Combobox::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 CEGUI::Combobox::setValidationString ( const String & 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 CEGUI::Combobox::showDropList ( void )

Show the drop-down list.

Returns:: Nothing

virtual bool CEGUI::Combobox::testClassName_impl ( const String & class_name ) const [inline, protected, virtual]

Return whether this window was inherited from the given class name at some point in the inheritance hierarchy.

Parameters:

class_name

The class name that is to be checked.

Returns:: true if this window was inherited from class_name. false if not.

Reimplemented from CEGUI::Window.

References CEGUI::Window::testClassName_impl().

CEGUI::Combobox Class Reference

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation