Base class for the multi column list widget. More...

Inheritance diagram for CEGUI::MultiColumnList:

Collaboration diagram for CEGUI::MultiColumnList:

Classes
struct	ListRow
	Struct used internally to represent a row in the list and also to ease sorting of the rows. More...
Public Types
enum	SelectionMode { RowSingle, RowMultiple, CellSingle, CellMultiple, NominatedColumnSingle, NominatedColumnMultiple, ColumnSingle, ColumnMultiple, NominatedRowSingle, NominatedRowMultiple }
	Enumerated values for the selection modes possible with a Multi-column list.
Public Member Functions
bool	isUserSortControlEnabled (void) const
	Return whether user manipulation of the sort column and direction are enabled.
bool	isUserColumnSizingEnabled (void) const
	Return whether the user may size column segments.
bool	isUserColumnDraggingEnabled (void) const
	Return whether the user may modify the order of the columns.
uint	getColumnCount (void) const
	Return the number of columns in the multi-column list.
uint	getRowCount (void) const
	Return the number of rows in the multi-column list.
uint	getSortColumn (void) const
	Return the zero based index of the current sort column. There must be at least one column to successfully call this method.
uint	getColumnWithID (uint col_id) const
	Return the zero based column index of the column with the specified ID.
uint	getColumnWithHeaderText (const String &text) const
	Return the zero based index of the column whos header text matches the specified text.
UDim	getTotalColumnHeadersWidth (void) const
	Return the total width of all column headers.
UDim	getColumnHeaderWidth (uint col_idx) const
	Return the width of the specified column header (and therefore the column itself).
ListHeaderSegment::SortDirection	getSortDirection (void) const
	Return the currently set sort direction.
ListHeaderSegment &	getHeaderSegmentForColumn (uint col_idx) const
	Return the ListHeaderSegment object for the specified column.
uint	getItemRowIndex (const ListboxItem *item) const
	Return the zero based index of the Row that contains item.
uint	getItemColumnIndex (const ListboxItem *item) const
	Return the current zero based index of the column that contains item.
MCLGridRef	getItemGridReference (const ListboxItem *item) const
	Return the grid reference for item.
ListboxItem *	getItemAtGridReference (const MCLGridRef &grid_ref) const
	Return a pointer to the ListboxItem at the specified grid reference.
bool	isListboxItemInColumn (const ListboxItem *item, uint col_idx) const
	return whether ListboxItem item is attached to the column at index col_idx.
bool	isListboxItemInRow (const ListboxItem *item, uint row_idx) const
	return whether ListboxItem item is attached to the row at index row_idx.
bool	isListboxItemInList (const ListboxItem *item) const
	return whether ListboxItem item is attached to the list box.
ListboxItem *	findColumnItemWithText (const String &text, uint col_idx, const ListboxItem *start_item) const
	Return the ListboxItem in column col_idx that has the text string text.
ListboxItem *	findRowItemWithText (const String &text, uint row_idx, const ListboxItem *start_item) const
	Return the ListboxItem in row row_idx that has the text string text.
ListboxItem *	findListItemWithText (const String &text, const ListboxItem *start_item) const
	Return the ListboxItem that has the text string text.
ListboxItem *	getFirstSelectedItem (void) const
	Return a pointer to the first selected ListboxItem attached to this list box.
ListboxItem *	getNextSelected (const ListboxItem *start_item) const
	Return a pointer to the next selected ListboxItem after start_item.
uint	getSelectedCount (void) const
	Return the number of selected ListboxItems attached to this list box.
bool	isItemSelected (const MCLGridRef &grid_ref) const
	Return whether the ListboxItem at grid_ref is selected.
uint	getNominatedSelectionColumnID (void) const
	Return the ID of the currently set nominated selection column to be used when in one of the NominatedColumn* selection modes. There must be at least one column to successfully call this method.
uint	getNominatedSelectionColumn (void) const
	Return the index of the currently set nominated selection column to be used when in one of the NominatedColumn* selection modes.
uint	getNominatedSelectionRow (void) const
	Return the index of the currently set nominated selection row to be used when in one of the NominatedRow* selection modes.
MultiColumnList::SelectionMode	getSelectionMode (void) const
	Return the currently set selection mode.
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.
uint	getColumnID (uint col_idx) const
	Return the ID code assigned to the requested column.
uint	getRowID (uint row_idx) const
	Return the ID code assigned to the requested row.
uint	getRowWithID (uint row_id) const
	Return the zero based row index of the row with the specified ID.
Rect	getListRenderArea (void) const
	Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering list items.
Scrollbar *	getVertScrollbar () const
	Return a pointer to the vertical scrollbar component widget for this MultiColumnList.
Scrollbar *	getHorzScrollbar () const
	Return a pointer to the horizontal scrollbar component widget for this MultiColumnList.
ListHeader *	getListHeader () const
	Return a pointer to the list header component widget for this MultiColumnList.
float	getTotalRowsHeight (void) const
	Return the sum of all row heights in pixels.
float	getWidestColumnItemWidth (uint col_idx) const
	Return the pixel width of the widest item in the given column.
float	getHighestRowItemHeight (uint row_idx) const
	Return, in pixels, the height of the highest item in the given row.
virtual void	initialiseComponents (void)
	Initialise the Window based object ready for use.
void	resetList (void)
	Remove all items from the list.
void	addColumn (const String &text, uint col_id, const UDim &width)
	Add a column to the list box.
void	insertColumn (const String &text, uint col_id, const UDim &width, uint position)
	Insert a new column in the list.
void	removeColumn (uint col_idx)
	Removes a column from the list box. This will cause any ListboxItem using the autoDelete option in the column to be deleted.
void	removeColumnWithID (uint col_id)
	Removes a column from the list box. This will cause any ListboxItem using the autoDelete option in the column to be deleted.
void	moveColumn (uint col_idx, uint position)
	Move the column at index col_idx so it is at index position.
void	moveColumnWithID (uint col_id, uint position)
	Move the column with ID col_id so it is at index position.
uint	addRow (uint row_id=0)
	Add an empty row to the list box.
uint	addRow (ListboxItem *item, uint col_id, uint row_id=0)
	Add a row to the list box, and set the item in the column with ID col_id to item.
uint	insertRow (uint row_idx, uint row_id=0)
	Insert an empty row into the list box.
uint	insertRow (ListboxItem *item, uint col_id, uint row_idx, uint row_id=0)
	Insert a row into the list box, and set the item in the column with ID col_id to item.
void	removeRow (uint row_idx)
	Remove the list box row with index row_idx. Any ListboxItem in row row_idx using autoDelete mode will be deleted.
void	setItem (ListboxItem *item, const MCLGridRef &position)
	Set the ListboxItem for grid reference position.
void	setItem (ListboxItem *item, uint col_id, uint row_idx)
	Set the ListboxItem for the column with ID col_id in row row_idx.
void	setSelectionMode (MultiColumnList::SelectionMode sel_mode)
	Set the selection mode for the list box.
void	setNominatedSelectionColumnID (uint col_id)
	Set the column to be used for the NominatedColumn* selection modes.
void	setNominatedSelectionColumn (uint col_idx)
	Set the column to be used for the NominatedColumn* selection modes.
void	setNominatedSelectionRow (uint row_idx)
	Set the row to be used for the NominatedRow* selection modes.
void	setSortDirection (ListHeaderSegment::SortDirection direction)
	Set the sort direction to be used.
void	setSortColumn (uint col_idx)
	Set the column to be used as the sort key.
void	setSortColumnByID (uint col_id)
	Set the column to be used as the sort key.
void	setShowVertScrollbar (bool setting)
	Set whether the vertical scroll bar should always be shown, or just when needed.
void	setShowHorzScrollbar (bool setting)
	Set whether the horizontal scroll bar should always be shown, or just when needed.
void	clearAllSelections (void)
	Removed the selected state from any currently selected ListboxItem attached to the list.
void	setItemSelectState (ListboxItem *item, bool state)
	Sets or clears the selected state of the given ListboxItem which must be attached to the list.
void	setItemSelectState (const MCLGridRef &grid_ref, bool state)
	Sets or clears the selected state of the ListboxItem at the given grid reference.
void	handleUpdatedItemData (void)
	Inform the list box that one or more attached ListboxItems have been externally modified, and the list should re-sync its internal state and refresh the display as needed.
void	setColumnHeaderWidth (uint col_idx, const UDim &width)
	Set the width of the specified column header (and therefore the column itself).
void	setUserSortControlEnabled (bool setting)
	Set whether user manipulation of the sort column and direction are enabled.
void	setUserColumnSizingEnabled (bool setting)
	Set whether the user may size column segments.
void	setUserColumnDraggingEnabled (bool setting)
	Set whether the user may modify the order of the columns.
void	autoSizeColumnHeader (uint col_idx)
	Automatically determines the "best fit" size for the specified column and sets the column width to the same.
void	setRowID (uint row_idx, uint row_id)
	Set the ID code assigned to a given row.
	MultiColumnList (const String &type, const String &name)
	Constructor for the Multi-column list base class.
virtual	~MultiColumnList (void)
	Destructor for the multi-column list base class.
Static Public Attributes
static const String	EventNamespace
	Namespace for global events.
static const String	WidgetTypeName
	Window factory name.
static const String	EventSelectionModeChanged
static const String	EventNominatedSelectColumnChanged
static const String	EventNominatedSelectRowChanged
static const String	EventVertScrollbarModeChanged
static const String	EventHorzScrollbarModeChanged
static const String	EventSelectionChanged
static const String	EventListContentsChanged
static const String	EventSortColumnChanged
static const String	EventSortDirectionChanged
static const String	EventListColumnSized
static const String	EventListColumnMoved
static const String	VertScrollbarNameSuffix
	Widget name suffix for the vertical scrollbar component.
static const String	HorzScrollbarNameSuffix
	Widget name suffix for the horizontal scrollbar component.
static const String	ListHeaderNameSuffix
	Widget name suffix for the list header component.
Protected Types
typedef std::vector< ListRow >	ListItemGrid
Protected Member Functions
void	configureScrollbars (void)
	Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering list items.
bool	selectRange (const MCLGridRef &start, const MCLGridRef &end)
	select all strings between positions start and end. (inclusive). Returns true if something was modified.
bool	clearAllSelections_impl (void)
	Clear the selected state for all items (implementation)
ListboxItem *	getItemAtPoint (const Point &pt) const
	Return the ListboxItem under the given window local pixel co-ordinate.
bool	setItemSelectState_impl (const MCLGridRef grid_ref, bool state)
	Set select state for the given item. This appropriately selects other items depending upon the select mode. Returns true if something is changed, else false.
void	setSelectForItemsInRow (uint row_idx, bool state)
	Set select state for all items in the given row.
void	setSelectForItemsInColumn (uint col_idx, bool state)
	Set select state for all items in the given column.
void	moveColumn_impl (uint col_idx, uint position)
	Move the column at index col_idx so it is at index position. Implementation version which does not move the header segment (since that may have already happened).
bool	resetList_impl (void)
	Remove all items from the list.
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.
virtual bool	validateWindowRenderer (const String &name) const
	Function used in checking if a WindowRenderer is valid for this window.
int	writePropertiesXML (XMLSerializer &xml_stream) const
void	resortList ()
	Causes the internal list to be (re)sorted.
virtual void	onSelectionModeChanged (WindowEventArgs &e)
	Handler called when the selection mode of the list box changes.
virtual void	onNominatedSelectColumnChanged (WindowEventArgs &e)
	Handler called when the nominated selection column changes.
virtual void	onNominatedSelectRowChanged (WindowEventArgs &e)
	Handler called when the nominated selection row changes.
virtual void	onVertScrollbarModeChanged (WindowEventArgs &e)
	Handler called when the vertical scroll bar 'force' mode is changed.
virtual void	onHorzScrollbarModeChanged (WindowEventArgs &e)
	Handler called when the horizontal scroll bar 'force' mode is changed.
virtual void	onSelectionChanged (WindowEventArgs &e)
	Handler called when the current selection changes.
virtual void	onListContentsChanged (WindowEventArgs &e)
	Handler called when the list contents is changed.
virtual void	onSortColumnChanged (WindowEventArgs &e)
	Handler called when the sort column changes.
virtual void	onSortDirectionChanged (WindowEventArgs &e)
	Handler called when the sort direction changes.
virtual void	onListColumnSized (WindowEventArgs &e)
	Handler called when a column is sized.
virtual void	onListColumnMoved (WindowEventArgs &e)
	Handler called when the column order is changed.
virtual void	onFontChanged (WindowEventArgs &e)
	Handler called when the window's font is changed.
virtual void	onSized (WindowEventArgs &e)
	Handler called when the window's size changes.
virtual void	onMouseButtonDown (MouseEventArgs &e)
	Handler called when a mouse button has been depressed within this window's area.
virtual void	onMouseWheel (MouseEventArgs &e)
	Handler called when the mouse wheel (z-axis) position changes within this window's area.
bool	handleHeaderScroll (const EventArgs &e)
bool	handleHeaderSegMove (const EventArgs &e)
bool	handleColumnSizeChange (const EventArgs &e)
bool	handleHorzScrollbar (const EventArgs &e)
bool	handleVertScrollbar (const EventArgs &e)
bool	handleSortColumnChange (const EventArgs &e)
bool	handleSortDirectionChange (const EventArgs &e)
bool	handleHeaderSegDblClick (const EventArgs &e)
Static Protected Member Functions
static bool	pred_descend (const ListRow &a, const ListRow &b)
	std algorithm predicate used for sorting in descending order
Protected Attributes
bool	d_forceVertScroll
	true if vertical scrollbar should always be displayed
bool	d_forceHorzScroll
	true if horizontal scrollbar should always be displayed
SelectionMode	d_selectMode
	Holds selection mode (represented by settings below).
uint	d_nominatedSelectCol
	Nominated column for single column selection.
uint	d_nominatedSelectRow
	Nominated row for single row selection.
bool	d_multiSelect
	Allow multiple selections.
bool	d_fullRowSelect
	All items in a row are selected.
bool	d_fullColSelect
	All items in a column are selected.
bool	d_useNominatedRow
	true if we use a nominated row to select.
bool	d_useNominatedCol
	true if we use a nominated col to select.
ListboxItem *	d_lastSelected
	holds pointer to the last selected item (used in range selections)
uint	d_columnCount
	keeps track of the number of columns.
ListItemGrid	d_grid
	Holds the list box data.
Friends
class	MultiColumnListWindowRenderer

Detailed Description

Base class for the multi column list widget.

Member Function Documentation

void CEGUI::MultiColumnList::addColumn	(	const String &	text,
		uint	col_id,
		const UDim &	width
	)

Add a column to the list box.

Parameters:

text	String object containing the text label for the column header.
col_id	ID code to be assigned to the column header.
width	UDim describing the initial width to be set for the column.

Returns:: Nothing.

uint CEGUI::MultiColumnList::addRow ( uint row_id = 0 )

Add an empty row to the list box.

Parameters:

row_id ID code to be assigned to the new row.

Note:: If the list is being sorted, the new row will appear at an appropriate position according to the sorting being applied. If no sorting is being done, the new row will appear at the bottom of the list.

Returns:: Initial zero based index of the new row.

uint CEGUI::MultiColumnList::addRow	(	ListboxItem *	item,
		uint	col_id,
		uint	row_id = `0`
	)

Add a row to the list box, and set the item in the column with ID col_id to item.

Note:: If the list is being sorted, the new row will appear at an appropriate position according to the sorting being applied. If no sorting is being done, the new row will appear at the bottom of the list.

Parameters:

item	Pointer to a ListboxItem to be used as the initial contents for the column with ID col_id.
col_id	ID code of the column whos initial item is to be set to item.
row_id	ID code to be assigned to the new row.

Returns:: Initial zero based index of the new row.

Exceptions:

InvalidRequestException thrown if no column with the specified ID is attached to the list box.

void CEGUI::MultiColumnList::autoSizeColumnHeader ( uint col_idx )

Automatically determines the "best fit" size for the specified column and sets the column width to the same.

Parameters:

col_idx Zero based index of the column to be sized.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if col_idx is out of range.

void CEGUI::MultiColumnList::clearAllSelections ( void )

Removed the selected state from any currently selected ListboxItem attached to the list.

Returns:: Nothing.

bool CEGUI::MultiColumnList::clearAllSelections_impl ( void ) [protected]

Clear the selected state for all items (implementation)

Returns:: true if some selections were cleared, false nothing was changed.

void CEGUI::MultiColumnList::configureScrollbars ( void ) [protected]

Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering list items.

Returns:: Rect object describing the area of the Window to be used for rendering list box items.

display required integrated scroll bars according to current state of the list box and update their values.

ListboxItem* CEGUI::MultiColumnList::findColumnItemWithText	(	const String &	text,
		uint	col_idx,
		const ListboxItem *	start_item
	)		const

Return the ListboxItem in column col_idx that has the text string text.

Parameters:

text	String object containing the text to be searched for.
col_idx	Zero based index of the column to be searched.
start_item	Pointer to the ListboxItem where the exclusive search is to start, or NULL to search from the top of the column.

Returns:: Pointer to the first ListboxItem in column col_idx, after start_item, that has the string text.

Exceptions:

InvalidRequestException thrown if start_item is not attached to the list box, or if col_idx is out of range.

ListboxItem* CEGUI::MultiColumnList::findListItemWithText	(	const String &	text,
		const ListboxItem *	start_item
	)		const

Return the ListboxItem that has the text string text.

Note:: List box searching progresses across the columns in each row.

Parameters:

text	String object containing the text to be searched for.
start_item	Pointer to the ListboxItem where the exclusive search is to start, or NULL to search the whole list box.

Returns:: Pointer to the first ListboxItem, after start_item, that has the string text.

Exceptions:

InvalidRequestException thrown if start_item is not attached to the list box.

ListboxItem* CEGUI::MultiColumnList::findRowItemWithText	(	const String &	text,
		uint	row_idx,
		const ListboxItem *	start_item
	)		const

Return the ListboxItem in row row_idx that has the text string text.

Parameters:

text	String object containing the text to be searched for.
row_idx	Zero based index of the row to be searched.
start_item	Pointer to the ListboxItem where the exclusive search is to start, or NULL to search from the start of the row.

Returns:: Pointer to the first ListboxItem in row row_idx, after start_item, that has the string text.

Exceptions:

InvalidRequestException thrown if start_item is not attached to the list box, or if row_idx is out of range.

uint CEGUI::MultiColumnList::getColumnCount ( void ) const

Return the number of columns in the multi-column list.

Returns:: uint value equal to the number of columns in the list.

UDim CEGUI::MultiColumnList::getColumnHeaderWidth ( uint col_idx ) const

Return the width of the specified column header (and therefore the column itself).

Parameters:

col_idx Zero based column index of the column whos width is to be returned.

Returns:: Width of the column header at the zero based column index specified by col_idx, as a UDim

Exceptions:

InvalidRequestException thrown if column is out of range.

uint CEGUI::MultiColumnList::getColumnID ( uint col_idx ) const

Return the ID code assigned to the requested column.

Parameters:

col_idx Zero based index of the column whos ID code is to be returned.

Returns:: Current ID code assigned to the column at the requested index.

Exceptions:

InvalidRequestException thrown if col_idx is out of range

uint CEGUI::MultiColumnList::getColumnWithHeaderText ( const String & text ) const

Return the zero based index of the column whos header text matches the specified text.

Parameters:

text	String object containing the text to be searched for.

Returns:: Zero based column index of the column whos header has the specified text.

Exceptions:

InvalidRequestException thrown if no columns header has the requested text.

uint CEGUI::MultiColumnList::getColumnWithID ( uint col_id ) const

Return the zero based column index of the column with the specified ID.

Parameters:

col_id ID code of the column whos index is to be returned.

Returns:: Zero based column index of the first column whos ID matches col_id.

Exceptions:

InvalidRequestException thrown if no attached column has the requested ID.

ListboxItem* CEGUI::MultiColumnList::getFirstSelectedItem ( void ) const

Return a pointer to the first selected ListboxItem attached to this list box.

Note:: List box searching progresses across the columns in each row.

Returns:: Pointer to the first ListboxItem attached to this list box that is selected, or NULL if no item is selected.

ListHeaderSegment& CEGUI::MultiColumnList::getHeaderSegmentForColumn ( uint col_idx ) const

Return the ListHeaderSegment object for the specified column.

Parameters:

col_idx zero based index of the column whos ListHeaderSegment is to be returned.

Returns:: ListHeaderSegment object for the column at the requested index.

Exceptions:

InvalidRequestException thrown if col_idx is out of range.

Scrollbar* CEGUI::MultiColumnList::getHorzScrollbar ( ) const

Return a pointer to the horizontal scrollbar component widget for this MultiColumnList.

Returns:: Pointer to a Scrollbar object.

Exceptions:

UnknownObjectException Thrown if the horizontal Scrollbar component does not exist.

ListboxItem* CEGUI::MultiColumnList::getItemAtGridReference ( const MCLGridRef & grid_ref ) const

Return a pointer to the ListboxItem at the specified grid reference.

Parameters:

grid_ref MCLGridRef object that describes the position of the ListboxItem to be returned.

Returns:: Pointer to the ListboxItem at grid reference grid_ref.

Exceptions:

InvalidRequestException thrown if grid_ref is invalid for this list box.

ListboxItem* CEGUI::MultiColumnList::getItemAtPoint ( const Point & pt ) const [protected]

Return the ListboxItem under the given window local pixel co-ordinate.

Returns:: ListboxItem that is under window pixel co-ordinate pt, or NULL if no item is under that position.

uint CEGUI::MultiColumnList::getItemColumnIndex ( const ListboxItem * item ) const

Return the current zero based index of the column that contains item.

Parameters:

item	Pointer to the ListboxItem that the column index is to returned for.

Returns:: Zero based index of the column that contains ListboxItem item.

Exceptions:

InvalidRequestException thrown if item is not attached to the list box.

MCLGridRef CEGUI::MultiColumnList::getItemGridReference ( const ListboxItem * item ) const

Return the grid reference for item.

Parameters:

item	Pointer to the ListboxItem whos current grid reference is to be returned.

Returns:: MCLGridRef object describing the current grid reference of ListboxItem item.

Exceptions:

InvalidRequestException thrown if item is not attached to the list box.

uint CEGUI::MultiColumnList::getItemRowIndex ( const ListboxItem * item ) const

Return the zero based index of the Row that contains item.

Parameters:

item	Pointer to the ListboxItem that the row index is to returned for.

Returns:: Zero based index of the row that contains ListboxItem item.

Exceptions:

InvalidRequestException thrown if item is not attached to the list box.

ListHeader* CEGUI::MultiColumnList::getListHeader ( ) const

Return a pointer to the list header component widget for this MultiColumnList.

Returns:: Pointer to a ListHeader object.

Exceptions:

UnknownObjectException Thrown if the list header component does not exist.

Rect CEGUI::MultiColumnList::getListRenderArea ( void ) const

Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering list items.

Returns:: Rect object describing the area of the Window to be used for rendering list box items.

ListboxItem* CEGUI::MultiColumnList::getNextSelected ( const ListboxItem * start_item ) const

Return a pointer to the next selected ListboxItem after start_item.

Note:: List box searching progresses across the columns in each row.

Parameters:

start_item Pointer to the ListboxItem where the exclusive search is to start, or NULL to search the whole list box.

Returns:: Pointer to the first selected ListboxItem attached to this list box, after start_item, or NULL if no item is selected.

Exceptions:

InvalidRequestException thrown if start_item is not attached to the list box.

uint CEGUI::MultiColumnList::getNominatedSelectionColumn ( void ) const

Return the index of the currently set nominated selection column to be used when in one of the NominatedColumn* selection modes.

Returns:: Zero based index of the nominated selection column.

uint CEGUI::MultiColumnList::getNominatedSelectionColumnID ( void ) const

Return the ID of the currently set nominated selection column to be used when in one of the NominatedColumn* selection modes. There must be at least one column to successfully call this method.

Note:: You should only ever call this when getColumnCount() returns > 0.

Returns:: ID code of the nominated selection column.

uint CEGUI::MultiColumnList::getNominatedSelectionRow ( void ) const

Return the index of the currently set nominated selection row to be used when in one of the NominatedRow* selection modes.

Returns:: Zero based index of the nominated selection column.

uint CEGUI::MultiColumnList::getRowCount ( void ) const

Return the number of rows in the multi-column list.

Returns:: uint value equal to the number of rows currently in the list.

uint CEGUI::MultiColumnList::getRowID ( uint row_idx ) const

Return the ID code assigned to the requested row.

Parameters:

row_idx Zero based index of the row who's ID code is to be returned.

Returns:: Current ID code assigned to the row at the requested index.

Exceptions:

InvalidRequestException thrown if row_idx is out of range

uint CEGUI::MultiColumnList::getRowWithID ( uint row_id ) const

Return the zero based row index of the row with the specified ID.

Parameters:

row_id ID code of the row who's index is to be returned.

Returns:: Zero based row index of the first row who's ID matches row_id.

Exceptions:

InvalidRequestException thrown if no row has the requested ID.

uint CEGUI::MultiColumnList::getSelectedCount ( void ) const

Return the number of selected ListboxItems attached to this list box.

return uint value equal to the number of ListboxItems attached to this list box that are currently selected.

MultiColumnList::SelectionMode CEGUI::MultiColumnList::getSelectionMode ( void ) const

Return the currently set selection mode.

Returns:: One of the MultiColumnList::SelectionMode enumerated values specifying the current selection mode.

uint CEGUI::MultiColumnList::getSortColumn ( void ) const

Return the zero based index of the current sort column. There must be at least one column to successfully call this method.

Returns:: Zero based column index that is the current sort column.

Exceptions:

InvalidRequestException thrown if there are no columns in this multi column list.

ListHeaderSegment::SortDirection CEGUI::MultiColumnList::getSortDirection ( void ) const

Return the currently set sort direction.

Returns:: One of the ListHeaderSegment::SortDirection enumerated values specifying the current sort direction.

UDim CEGUI::MultiColumnList::getTotalColumnHeadersWidth ( void ) const

Return the total width of all column headers.

Returns:: Sum total of all the column header widths as a UDim.

Scrollbar* CEGUI::MultiColumnList::getVertScrollbar ( ) const

Return a pointer to the vertical scrollbar component widget for this MultiColumnList.

Returns:: Pointer to a Scrollbar object.

Exceptions:

UnknownObjectException Thrown if the vertical Scrollbar component does not exist.

void CEGUI::MultiColumnList::handleUpdatedItemData ( void )

Inform the list box that one or more attached ListboxItems have been externally modified, and the list should re-sync its internal state and refresh the display as needed.

Returns:: Nothing.

virtual void CEGUI::MultiColumnList::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::MultiColumnList::insertColumn	(	const String &	text,
		uint	col_id,
		const UDim &	width,
		uint	position
	)

Insert a new column in the list.

Parameters:

text	String object containing the text label for the column header.
col_id	ID code to be assigned to the column header.
width	UDim describing the initial width to be set for the column.
position	Zero based index where the column is to be inserted. If this is greater than the current number of columns, the new column is inserted at the end.

Returns:: Nothing.

uint CEGUI::MultiColumnList::insertRow	(	ListboxItem *	item,
		uint	col_id,
		uint	row_idx,
		uint	row_id = `0`
	)

Insert a row into the list box, and set the item in the column with ID col_id to item.

Note:: If the list is being sorted, the new row will appear at an appropriate position according to the sorting being applied. If no sorting is being done, the new row will appear at the specified index.

Parameters:

item	Pointer to a ListboxItem to be used as the initial contents for the column with ID col_id.
col_id	ID code of the column whos initial item is to be set to item.
row_idx	Zero based index where the row should be inserted. If this is greater than the current number of rows, the row is appended to the list.
row_id	ID code to be assigned to the new row.

Returns:: Zero based index where the row was actually inserted.

Exceptions:

InvalidRequestException thrown if no column with the specified ID is attached to the list box.

uint CEGUI::MultiColumnList::insertRow	(	uint	row_idx,
		uint	row_id = `0`
	)

Insert an empty row into the list box.

Note:: If the list is being sorted, the new row will appear at an appropriate position according to the sorting being applied. If no sorting is being done, the new row will appear at the specified index.

Parameters:

row_idx	Zero based index where the row should be inserted. If this is greater than the current number of rows, the row is appended to the list.
row_id	ID code to be assigned to the new row.

Returns:: Zero based index where the row was actually inserted.

bool CEGUI::MultiColumnList::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::MultiColumnList::isItemSelected ( const MCLGridRef & grid_ref ) const

Return whether the ListboxItem at grid_ref is selected.

Parameters:

grid_ref MCLGridRef object describing the grid reference that is to be examined.

Returns:

true if there is a ListboxItem at grid_ref and it is selected.
false if there is no ListboxItem at grid_ref, or if the item is not selected.

Exceptions:

InvalidRequestException thrown if grid_ref contains an invalid grid position.

bool CEGUI::MultiColumnList::isListboxItemInColumn	(	const ListboxItem *	item,
		uint	col_idx
	)		const

return whether ListboxItem item is attached to the column at index col_idx.

Parameters:

item	Pointer to the ListboxItem to look for.
col_idx	Zero based index of the column that is to be searched.

Returns:

true if item is attached to list box column col_idx.
false if item is not attached to list box column col_idx.

Exceptions:

InvalidRequestException thrown if col_idx is out of range.

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

return whether ListboxItem item is attached to the list box.

Parameters:

item	Pointer to the ListboxItem to look for.

Returns:

true if item is attached to list box.
false if item is not attached to list box.

bool CEGUI::MultiColumnList::isListboxItemInRow	(	const ListboxItem *	item,
		uint	row_idx
	)		const

return whether ListboxItem item is attached to the row at index row_idx.

Parameters:

item	Pointer to the ListboxItem to look for.
row_idx	Zero based index of the row that is to be searched.

Returns:

true if item is attached to list box row row_idx.
false if item is not attached to list box row row_idx.

Exceptions:

InvalidRequestException thrown if row_idx is out of range.

bool CEGUI::MultiColumnList::isUserColumnDraggingEnabled ( void ) const

Return whether the user may modify the order of the columns.

Returns:: true if the user may interactively modify the order of the columns, false if they may not.

bool CEGUI::MultiColumnList::isUserColumnSizingEnabled ( void ) const

Return whether the user may size column segments.

Returns:: true if the user may interactively modify the width of columns, false if they may not.

bool CEGUI::MultiColumnList::isUserSortControlEnabled ( void ) const

Return whether user manipulation of the sort column and direction are enabled.

Returns:: true if the user may interactively modify the sort column and direction. false if the user may not modify the sort column and direction (these can still be set programmatically).

bool CEGUI::MultiColumnList::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.

void CEGUI::MultiColumnList::moveColumn	(	uint	col_idx,
		uint	position
	)

Move the column at index col_idx so it is at index position.

Parameters:

col_idx	Zero based index of the column to be moved.
position	Zero based index of the new position for the column.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if col_idx is invalid.

void CEGUI::MultiColumnList::moveColumn_impl	(	uint	col_idx,
		uint	position
	)		`[protected]`

Move the column at index col_idx so it is at index position. Implementation version which does not move the header segment (since that may have already happened).

Exceptions:

InvalidRequestException thrown if col_idx is invalid.

void CEGUI::MultiColumnList::moveColumnWithID	(	uint	col_id,
		uint	position
	)

Move the column with ID col_id so it is at index position.

Parameters:

col_id	ID code of the column to be moved.
position	Zero based index of the new position for the column.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if no column with col_id is available on this list box.

virtual void CEGUI::MultiColumnList::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::MultiColumnList::onMouseButtonDown ( MouseEventArgs & e ) [protected, virtual]

Handler called when a mouse button has been depressed within this window's area.

Parameters:

e	MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

virtual void CEGUI::MultiColumnList::onMouseWheel ( MouseEventArgs & e ) [protected, virtual]

Handler called when the mouse wheel (z-axis) position changes within this window's area.

Parameters:

e	MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

virtual void CEGUI::MultiColumnList::onSized ( WindowEventArgs & e ) [protected, virtual]

Handler called when the window's size changes.

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::MultiColumnList::removeColumn ( uint col_idx )

Removes a column from the list box. This will cause any ListboxItem using the autoDelete option in the column to be deleted.

Parameters:

col_idx Zero based index of the column to be removed.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if col_idx is invalid.

void CEGUI::MultiColumnList::removeColumnWithID ( uint col_id )

Removes a column from the list box. This will cause any ListboxItem using the autoDelete option in the column to be deleted.

Parameters:

col_id ID code of the column to be deleted.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if no column with col_id is available on this list box.

void CEGUI::MultiColumnList::removeRow ( uint row_idx )

Remove the list box row with index row_idx. Any ListboxItem in row row_idx using autoDelete mode will be deleted.

Parameters:

row_idx Zero based index of the row to be removed.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if row_idx is invalid.

void CEGUI::MultiColumnList::resetList ( void )

Remove all items from the list.

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

bool CEGUI::MultiColumnList::resetList_impl ( void ) [protected]

Remove all items from the list.

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

Returns:

true if the list contents were changed.
false if the list contents were not changed (list already empty).

void CEGUI::MultiColumnList::setColumnHeaderWidth	(	uint	col_idx,
		const UDim &	width
	)

Set the width of the specified column header (and therefore the column itself).

Parameters:

col_idx	Zero based column index of the column whos width is to be set.
width	UDim value specifying the new width for the column.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if column is out of range.

void CEGUI::MultiColumnList::setItem	(	ListboxItem *	item,
		const MCLGridRef &	position
	)

Set the ListboxItem for grid reference position.

Parameters:

item	Pointer to the ListboxItem to be set at position.
position	MCLGridRef describing the grid reference of the item to be set.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if position contains an invalid grid reference.

void CEGUI::MultiColumnList::setItem	(	ListboxItem *	item,
		uint	col_id,
		uint	row_idx
	)

Set the ListboxItem for the column with ID col_id in row row_idx.

Parameters:

item	Pointer to the ListboxItem to be set into the list.
col_id	ID code of the column to receive item.
row_idx	Zero based index of the row to receive item.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if no column with ID col_id exists, or of row_idx is out of range.

void CEGUI::MultiColumnList::setItemSelectState	(	const MCLGridRef &	grid_ref,
		bool	state
	)

Sets or clears the selected state of the ListboxItem at the given grid reference.

Note:: Depending upon the current selection mode, this may cause other items to be selected, other items to be deselected, or for nothing to actually happen at all.

Parameters:

grid_ref	MCLGridRef object describing the position of the item to be affected.
state	true to put the ListboxItem into the selected state. false to put the ListboxItem into the de-selected state.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if grid_ref is invalid for this list box.

void CEGUI::MultiColumnList::setItemSelectState	(	ListboxItem *	item,
		bool	state
	)

Sets or clears the selected state of the given ListboxItem which must be attached to the list.

Note:: Depending upon the current selection mode, this may cause other items to be selected, other items to be deselected, or for nothing to actually happen at all.

Parameters:

item	Pointer to the attached ListboxItem to be affected.
state	true to put the ListboxItem into the selected state. false to put the ListboxItem into the de-selected state.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if item is not attached to the list box.

void CEGUI::MultiColumnList::setNominatedSelectionColumn ( uint col_idx )

Set the column to be used for the NominatedColumn* selection modes.

Parameters:

col_idx zero based index of the column to be used in NominatedColumn* selection modes.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if col_idx is out of range.

void CEGUI::MultiColumnList::setNominatedSelectionColumnID ( uint col_id )

Set the column to be used for the NominatedColumn* selection modes.

Parameters:

col_id ID code of the column to be used in NominatedColumn* selection modes.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if no column has ID code col_id.

void CEGUI::MultiColumnList::setNominatedSelectionRow ( uint row_idx )

Set the row to be used for the NominatedRow* selection modes.

Parameters:

row_idx zero based index of the row to be used in NominatedRow* selection modes.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if row_idx is out of range.

void CEGUI::MultiColumnList::setRowID	(	uint	row_idx,
		uint	row_id
	)

Set the ID code assigned to a given row.

Parameters:

row_idx	Zero based index of the row who's ID code is to be set.
row_id	ID code to be assigned to the row at the requested index.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if row_idx is out of range

void CEGUI::MultiColumnList::setSelectionMode ( MultiColumnList::SelectionMode sel_mode )

Set the selection mode for the list box.

Parameters:

sel_mode One of the MultiColumnList::SelectionMode enumerated values specifying the selection mode to be used.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if the value specified for sel_mode is invalid.

void CEGUI::MultiColumnList::setShowHorzScrollbar ( bool setting )

Set whether the horizontal scroll bar should always be shown, or just when needed.

Parameters:

setting

true to have the horizontal scroll bar shown at all times.
false to have the horizontal scroll bar appear only when needed.

Returns:: Nothing.

void CEGUI::MultiColumnList::setShowVertScrollbar ( bool setting )

Set whether the vertical scroll bar should always be shown, or just when needed.

Parameters:

setting

true to have the vertical scroll bar shown at all times.
false to have the vertical scroll bar appear only when needed.

Returns:: Nothing.

void CEGUI::MultiColumnList::setSortColumn ( uint col_idx )

Set the column to be used as the sort key.

Parameters:

col_idx Zero based index of the column to use as the key when sorting the list items.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if col_idx is out of range.

void CEGUI::MultiColumnList::setSortColumnByID ( uint col_id )

Set the column to be used as the sort key.

Parameters:

col_id ID code of the column to use as the key when sorting the list items.

Returns:: Nothing.

Exceptions:

InvalidRequestException thrown if col_id is invalid for this list box.

void CEGUI::MultiColumnList::setSortDirection ( ListHeaderSegment::SortDirection direction )

Set the sort direction to be used.

Parameters:

direction One of the ListHeaderSegment::SortDirection enumerated values specifying the sort direction to be used.

Returns:: Nothing.

void CEGUI::MultiColumnList::setUserColumnDraggingEnabled ( bool setting )

Set whether the user may modify the order of the columns.

Parameters:

setting

true if the user may interactively modify the order of the columns.
false if the user may not modify the order of the columns.

void CEGUI::MultiColumnList::setUserColumnSizingEnabled ( bool setting )

Set whether the user may size column segments.

Parameters:

setting

true if the user may interactively modify the width of columns.
false if the user may not change the width of the columns.

Returns:: Nothing.

void CEGUI::MultiColumnList::setUserSortControlEnabled ( bool setting )

Set whether user manipulation of the sort column and direction are enabled.

Parameters:

setting

true if the user may interactively modify the sort column and direction.
false if the user may not modify the sort column and direction (these can still be set programmatically).

Returns:: Nothing.

virtual bool CEGUI::MultiColumnList::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().

virtual bool CEGUI::MultiColumnList::validateWindowRenderer ( const String & name ) const [inline, protected, virtual]

Function used in checking if a WindowRenderer is valid for this window.

Returns:: Returns true if the given WindowRenderer class name is valid for this window. False if not.

Reimplemented from CEGUI::Window.

Member Data Documentation

const String CEGUI::MultiColumnList::EventHorzScrollbarModeChanged [static]

Event fired when the horizontal scroll bar 'force' setting changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose horizontal scroll bar mode has been changed.

const String CEGUI::MultiColumnList::EventListColumnMoved [static]

Event fired when the column order changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList for which the order of columns has been changed.

const String CEGUI::MultiColumnList::EventListColumnSized [static]

Event fired when the width of a column in the list changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList for which a column width has changed.

const String CEGUI::MultiColumnList::EventListContentsChanged [static]

Event fired when the contents of the list box changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose contents has changed.

const String CEGUI::MultiColumnList::EventNominatedSelectColumnChanged [static]

Event fired when the nominated select column changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose nominated selection column has been changed.

const String CEGUI::MultiColumnList::EventNominatedSelectRowChanged [static]

Event fired when the nominated select row changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose nominated selection row has been changed.

const String CEGUI::MultiColumnList::EventSelectionChanged [static]

Event fired when the current selection(s) within the list box changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose current selection has changed.

const String CEGUI::MultiColumnList::EventSelectionModeChanged [static]

Event fired when the selection mode for the list box changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose selection mode has been changed.

const String CEGUI::MultiColumnList::EventSortColumnChanged [static]

Event fired when the sort column changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose sort column has been changed.

const String CEGUI::MultiColumnList::EventSortDirectionChanged [static]

Event fired when the sort direction changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose sort direction has been changed.

const String CEGUI::MultiColumnList::EventVertScrollbarModeChanged [static]

Event fired when the vertical scroll bar 'force' setting changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiColumnList whose vertical scroll bar mode has been changed.

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Function Documentation

Member Data Documentation