Crazy Eddie's GUI System  0.8.4
CEGUI::MultiColumnList Class Reference

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

+ Inheritance diagram for CEGUI::MultiColumnList:
+ Collaboration diagram for CEGUI::MultiColumnList:

List of all members.

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 getSortColumnID (void) const
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.
ListHeaderSegmentgetHeaderSegmentForColumn (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.
ListboxItemgetItemAtGridReference (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.
ListboxItemfindColumnItemWithText (const String &text, uint col_idx, const ListboxItem *start_item) const
 Return the ListboxItem in column col_idx that has the text string text.
ListboxItemfindRowItemWithText (const String &text, uint row_idx, const ListboxItem *start_item) const
 Return the ListboxItem in row row_idx that has the text string text.
ListboxItemfindListItemWithText (const String &text, const ListboxItem *start_item) const
 Return the ListboxItem that has the text string text.
ListboxItemgetFirstSelectedItem (void) const
 Return a pointer to the first selected ListboxItem attached to this list box.
ListboxItemgetNextSelected (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.
Rectf 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.
ScrollbargetVertScrollbar () const
 Return a pointer to the vertical scrollbar component widget for this MultiColumnList.
ScrollbargetHorzScrollbar () const
 Return a pointer to the horizontal scrollbar component widget for this MultiColumnList.
ListHeadergetListHeader () 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.
bool getAutoSizeColumnUsesHeader () const
 Get whether or not column auto-sizing (autoSizeColumnHeader()) will use the list header segment size.
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 addColumn (const String &value)
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.
void ensureItemIsVisible (const ListboxItem *item)
 Ensure the specified item is made visible within the multi-column listbox.
void ensureItemIsVisible (const MCLGridRef &grid_ref)
 Ensure the item at the specified grid coordinate is visible within the multi-column listbox.
void ensureItemRowIsVisible (const ListboxItem *item)
 Ensure that the row of the item is visible within the multi-column listbox.
void ensureItemColumnIsVisible (const ListboxItem *item)
 Ensure that the column of item is visible within the multi-column listbox.
void ensureRowIsVisible (uint row_idx)
 Ensure that the row with index row_idx is visible within the multi-column listbox.
void ensureColumnIsVisible (uint column_idx)
 Ensure that the column with ID column_idx is visible within the multi-column listbox.
void setAutoSizeColumnUsesHeader (bool include_header)
 Instruct column auto-sizing (autoSizeColumnHeader()) to also use the list header segment size.
 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 VertScrollbarName
 Widget name for the vertical scrollbar component.
static const String HorzScrollbarName
 Widget name for the horizontal scrollbar component.
static const String ListHeaderName
 Widget name for the list header component.

Protected Types

typedef std::vector< ListRow
CEGUI_VECTOR_ALLOC(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)
ListboxItemgetItemAtPoint (const Vector2f &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 validateWindowRenderer (const WindowRenderer *renderer) 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 (ElementEventArgs &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.
ListboxItemd_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.
bool d_autoSizeColumnUsesHeader
 whether header size will be considered when auto-sizing columns.

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:
textString object containing the text label for the column header.
col_idID code to be assigned to the column header.
widthUDim 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_idID 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:
itemPointer to a ListboxItem to be used as the initial contents for the column with ID col_id.
col_idID code of the column whos initial item is to be set to item.
row_idID code to be assigned to the new row.
Returns:
Initial zero based index of the new row.
Exceptions:
InvalidRequestExceptionthrown if no column with the specified ID is attached to the list box.

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

Parameters:
col_idxZero based index of the column to be sized.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if col_idx is out of range.

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

Returns:
Nothing.

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.

Ensure that the column with ID column_idx is visible within the multi-column listbox.

Parameters:
column_idxcolumn_idx is the zero-based index of the column to be made visible.
Returns:
Nothing.

Ensure that the column of item is visible within the multi-column listbox.

Note:
This doesn't necessarily make item visible.
Parameters:
itemPointer to the ListboxItem whose column is to be made visible in the multi-column listbox.
Returns:
Nothing.

Ensure the specified item is made visible within the multi-column listbox.

Parameters:
itemPointer to the ListboxItem to be made visible in the multi-column listbox.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if item is not attached to this multicolumnlist.

Ensure the item at the specified grid coordinate is visible within the multi-column listbox.

Parameters:
grid_refMCLGridRef object holding the grid coordinate that is to be made visible.
Returns:
Nothing.

Ensure that the row of the item is visible within the multi-column listbox.

Note:
This doesn't necessarily make item visible.
Parameters:
itemPointer to the ListboxItem whose row is to be made visible in the multi-column listbox.
Returns:
Nothing.

Ensure that the row with index row_idx is visible within the multi-column listbox.

Parameters:
row_idrow_idx is the zero-based index of the row to be made visible.
Returns:
Nothing.
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:
textString object containing the text to be searched for.
col_idxZero based index of the column to be searched.
start_itemPointer 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:
InvalidRequestExceptionthrown 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:
textString object containing the text to be searched for.
start_itemPointer 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:
InvalidRequestExceptionthrown 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:
textString object containing the text to be searched for.
row_idxZero based index of the row to be searched.
start_itemPointer 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:
InvalidRequestExceptionthrown if start_item is not attached to the list box, or if row_idx is out of range.

Get whether or not column auto-sizing (autoSizeColumnHeader()) will use the list header segment size.

Returns:
Return true if the header segment will be included in the width calculation.

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

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

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

Parameters:
col_idxZero 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:
InvalidRequestExceptionthrown 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_idxZero 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:
InvalidRequestExceptionthrown if col_idx is out of range

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

Parameters:
textString object containing the text to be searched for.
Returns:
Zero based column index of the column whos header has the specified text.
Exceptions:
InvalidRequestExceptionthrown 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_idID 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:
InvalidRequestExceptionthrown if no attached column has the requested ID.

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.

Return the ListHeaderSegment object for the specified column.

Parameters:
col_idxzero based index of the column whos ListHeaderSegment is to be returned.
Returns:
ListHeaderSegment object for the column at the requested index.
Exceptions:
InvalidRequestExceptionthrown if col_idx is out of range.

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

Returns:
Pointer to a Scrollbar object.
Exceptions:
UnknownObjectExceptionThrown if the horizontal Scrollbar component does not exist.

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

Parameters:
grid_refMCLGridRef object that describes the position of the ListboxItem to be returned.
Returns:
Pointer to the ListboxItem at grid reference grid_ref.
Exceptions:
InvalidRequestExceptionthrown if grid_ref is invalid for this list box.
ListboxItem* CEGUI::MultiColumnList::getItemAtPoint ( const Vector2f 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.

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

Parameters:
itemPointer to the ListboxItem that the column index is to returned for.
Returns:
Zero based index of the column that contains ListboxItem item.
Exceptions:
InvalidRequestExceptionthrown if item is not attached to the list box.

Return the grid reference for item.

Parameters:
itemPointer to the ListboxItem whos current grid reference is to be returned.
Returns:
MCLGridRef object describing the current grid reference of ListboxItem item.
Exceptions:
InvalidRequestExceptionthrown if item is not attached to the list box.

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

Parameters:
itemPointer to the ListboxItem that the row index is to returned for.
Returns:
Zero based index of the row that contains ListboxItem item.
Exceptions:
InvalidRequestExceptionthrown if item is not attached to the list box.

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

Returns:
Pointer to a ListHeader object.
Exceptions:
UnknownObjectExceptionThrown if the list header component does not exist.

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.

Return a pointer to the next selected ListboxItem after start_item.

Note:
List box searching progresses across the columns in each row.
Parameters:
start_itemPointer 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:
InvalidRequestExceptionthrown if start_item is not attached to the list box.

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.

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.

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_idxZero 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:
InvalidRequestExceptionthrown 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_idID 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:
InvalidRequestExceptionthrown if no row has the requested ID.

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.

Return the currently set selection mode.

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

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:
InvalidRequestExceptionthrown if there are no columns in this multi column list.

Return the currently set sort direction.

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

Return the total width of all column headers.

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

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

Returns:
Pointer to a Scrollbar object.
Exceptions:
UnknownObjectExceptionThrown if the vertical Scrollbar component does not exist.

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:
textString object containing the text label for the column header.
col_idID code to be assigned to the column header.
widthUDim describing the initial width to be set for the column.
positionZero 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 ( 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_idxZero 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_idID code to be assigned to the new row.
Returns:
Zero based index where the row was actually inserted.
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:
itemPointer to a ListboxItem to be used as the initial contents for the column with ID col_id.
col_idID code of the column whos initial item is to be set to item.
row_idxZero 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_idID code to be assigned to the new row.
Returns:
Zero based index where the row was actually inserted.
Exceptions:
InvalidRequestExceptionthrown if no column with the specified ID is attached to the list box.

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_refMCLGridRef 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:
InvalidRequestExceptionthrown 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:
itemPointer to the ListboxItem to look for.
col_idxZero 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:
InvalidRequestExceptionthrown if col_idx is out of range.

return whether ListboxItem item is attached to the list box.

Parameters:
itemPointer 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:
itemPointer to the ListboxItem to look for.
row_idxZero 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:
InvalidRequestExceptionthrown if row_idx is out of range.

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.

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.

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

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_idxZero based index of the column to be moved.
positionZero based index of the new position for the column.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown 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:
InvalidRequestExceptionthrown 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_idID code of the column to be moved.
positionZero based index of the new position for the column.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown 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:
eWindowEventArgs 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:
eMouseEventArgs 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:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

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

Handler called when the window's size changes.

Parameters:
eWindowEventArgs 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_idxZero based index of the column to be removed.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if col_idx is invalid.

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

Parameters:
col_idID code of the column to be deleted.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown 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_idxZero based index of the row to be removed.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if row_idx is invalid.

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

Instruct column auto-sizing (autoSizeColumnHeader()) to also use the list header segment size.

Parameters:
include_headerWhether method autoSizeColumnHeader() also should use the size of the column header segment.
Returns:
Nothing.
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_idxZero based column index of the column whos width is to be set.
widthUDim value specifying the new width for the column.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if column is out of range.
void CEGUI::MultiColumnList::setItem ( ListboxItem item,
const MCLGridRef position 
)

Set the ListboxItem for grid reference position.

Parameters:
itemPointer to the ListboxItem to be set at position.
positionMCLGridRef describing the grid reference of the item to be set.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown 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:
itemPointer to the ListboxItem to be set into the list.
col_idID code of the column to receive item.
row_idxZero based index of the row to receive item.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if no column with ID col_id exists, or of row_idx is out of range.
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:
itemPointer 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:
InvalidRequestExceptionthrown if item is not attached to the list box.
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_refMCLGridRef 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:
InvalidRequestExceptionthrown if grid_ref is invalid for this list box.

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

Parameters:
col_idxzero based index of the column to be used in NominatedColumn* selection modes.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if col_idx is out of range.

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

Parameters:
col_idID code of the column to be used in NominatedColumn* selection modes.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if no column has ID code col_id.

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

Parameters:
row_idxzero based index of the row to be used in NominatedRow* selection modes.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown 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_idxZero based index of the row who's ID code is to be set.
row_idID code to be assigned to the row at the requested index.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if row_idx is out of range

Set the selection mode for the list box.

Parameters:
sel_modeOne of the MultiColumnList::SelectionMode enumerated values specifying the selection mode to be used.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if the value specified for sel_mode is invalid.

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.

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_idxZero based index of the column to use as the key when sorting the list items.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if col_idx is out of range.

Set the column to be used as the sort key.

Parameters:
col_idID code of the column to use as the key when sorting the list items.
Returns:
Nothing.
Exceptions:
InvalidRequestExceptionthrown if col_id is invalid for this list box.

Set the sort direction to be used.

Parameters:
directionOne of the ListHeaderSegment::SortDirection enumerated values specifying the sort direction to be used.
Returns:
Nothing.

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.

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.

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::validateWindowRenderer ( const WindowRenderer renderer) const [protected, virtual]

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

Parameters:
rendererWindow renderer that will be checked (it can be null!)
Returns:
Returns true if the given WindowRenderer class name is valid for this window. False if not.

Reimplemented from CEGUI::Window.


Member Data Documentation

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends