# CEGUI::MultiColumnList Class Reference

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

Inheritance diagram for CEGUI::MultiColumnList:

[legend]
Collaboration diagram for CEGUI::MultiColumnList:

[legend]
List of all members.

## 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.
float | getTotalColumnHeadersWidth (void) const
| Return the total width of all column headers.
float | 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.
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.
virtual void | initialise (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, float width)
| Add a column to the list box.
void | insertColumn (const String &text, uint col_id, float 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, float 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 | EventSelectionModeChanged
| Event fired when the selection mode for the list box changes.
static const String | EventNominatedSelectColumnChanged
| Event fired when the nominated select column changes.
static const String | EventNominatedSelectRowChanged
| Event fired when the nominated select row changes.
static const String | EventVertScrollbarModeChanged
| Event fired when the vertical scroll bar 'force' setting changes.
static const String | EventHorzScrollbarModeChanged
| Event fired when the horizontal scroll bar 'force' setting changes.
static const String | EventSelectionChanged
| Event fired when the current selection(s) within the list box changes.
static const String | EventListContentsChanged
| Event fired when the contents of the list box changes.
static const String | EventSortColumnChanged
| Event fired when the sort column changes.
static const String | EventSortDirectionChanged
| Event fired when the sort direction changes.
static const String | EventListColumnSized
| Event fired when the width of a column in the list changes.
static const String | EventListColumnMoved
| Event fired when the column order changes.

## Protected Types

typedef std::vector< ListRow > | ListItemGrid

## Protected Member Functions

virtual Rect | getListRenderArea (void) const =0
| Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering list items.
virtual ListHeader * | createListHeader (const String &name) const =0
| create and return a pointer to a ListHeaer widget for use as the column headers.
virtual Scrollbar * | createVertScrollbar (const String &name) const =0
| create and return a pointer to a Scrollbar widget for use as vertical scroll bar
virtual Scrollbar * | createHorzScrollbar (const String &name) const =0
| create and return a pointer to a Scrollbar widget for use as horizontal scroll bar
virtual void | cacheListboxBaseImagery ()=0
| Perform rendering of the widget control frame and other 'static' areas. This method should not render the actual items. Note that the items are typically rendered to layer 3, other layers can be used for rendering imagery behind and infront of the items.
void | addMultiColumnListboxEvents (void)
| Add multi column list box specific events.
virtual void | populateRenderCache ()
| Update the rendering cache.
void | configureScrollbars (void)
| display required integrated scroll bars according to current state of the list box and update their values.
bool | selectRange (const MCLGridRef &start, const MCLGridRef &end)
| select all strings between positions start and end. (inclusive). Returns true if something was modified.
float | getTotalRowsHeight (void) const
| Return the sum of all row heights.
float | getWidestColumnItemWidth (uint col_idx) const
| Return the width of the widest item in the given column.
float | getHighestRowItemHeight (uint row_idx) const
| Return the height of the highest item in the given row.
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 heirarchy.
int | writePropertiesXML (OutStream &out_stream) const
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 | 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

Scrollbar * | d_vertScrollbar
| vertical scroll-bar widget
Scrollbar * | d_horzScrollbar
| horizontal scroll-bar widget
ListHeader * | d_header
| The ListHeader attached to this multi-column list.
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)
ListItemGrid | d_grid
| Holds the list box data.

## Classes

struct | ListRow
| Struct used internally to represent a row in the list and also to ease sorting of the rows. More...

## Detailed Description

Base class for the multi column list widget.

## Member Function Documentation

void CEGUI::MultiColumnList::addColumn | ( | const String & | text,
|  | uint | col_id,
|  | float | 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 | Initial width to be set for the column using the active metrics mode for this window.

Returns:
  Nothing.

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.

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.

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.

virtual void CEGUI::MultiColumnList::cacheListboxBaseImagery | ( |  | ) | `[protected, pure virtual]`

Perform rendering of the widget control frame and other 'static' areas. This method should not render the actual items. Note that the items are typically rendered to layer 3, other layers can be used for rendering imagery behind and infront of the items.

Returns:
  Nothing.

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.

virtual Scrollbar* CEGUI::MultiColumnList::createHorzScrollbar | ( | const String & | name | ) | const`[protected, pure virtual]`

create and return a pointer to a Scrollbar widget for use as horizontal scroll bar

Parameters:

  | name | String holding the name to be assigned to the created component.

Returns:
  Pointer to a Scrollbar to be used for scrolling the list horizontally.

virtual ListHeader* CEGUI::MultiColumnList::createListHeader | ( | const String & | name | ) | const`[protected, pure virtual]`

create and return a pointer to a ListHeaer widget for use as the column headers.

Parameters:

  | name | String holding the name to be assigned to the created component.

Returns:
  Pointer to a ListHeader based object.

virtual Scrollbar* CEGUI::MultiColumnList::createVertScrollbar | ( | const String & | name | ) | const`[protected, pure virtual]`

create and return a pointer to a Scrollbar widget for use as vertical scroll bar

Parameters:

  | name | String holding the name to be assigned to the created component.

Returns:
  Pointer to a Scrollbar to be used for scrolling the list vertically.

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.

float 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, in whichever is the active metrics system.

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.

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.

virtual Rect CEGUI::MultiColumnList::getListRenderArea | ( | void |  | ) | const`[protected, pure virtual]`

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.

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.

float CEGUI::MultiColumnList::getTotalColumnHeadersWidth | ( | void |  | ) | const

Return the total width of all column headers.

Returns:
  Sum total of all the column header widths in whichever metrics system is active.

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.

void CEGUI::MultiColumnList::initialise | ( | 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,
|  | float | 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 | Initial width to be set for the column using the active metrics mode for this window.
  | 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.

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.

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.

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::populateRenderCache | ( |  | ) | `[protected, virtual]`

| Update the rendering cache. Populates the Window's RenderCache with imagery to be sent to the renderer. 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,
|  | float | 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 | float value specifying the new width for the column using the active metrics system.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if column is out of range.

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::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::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 heirarchy.

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.