Crazy Eddies GUI System: CEGUI::Listbox Class Reference

Crazy Eddies GUI System 0.7.6

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Attributes | Protected Types | Protected Member Functions | Protected Attributes | Friends
CEGUI::Listbox Class Reference

Base class for standard Listbox widget. More...

Inheritance diagram for CEGUI::Listbox:
[legend]
Collaboration diagram for CEGUI::Listbox:
[legend]

List of all members.

## Public Member Functions
size_t | getItemCount (void) const
| Return number of items attached to the list box.
size_t | getSelectedCount (void) const
| Return the number of selected items in the list box.
ListboxItem * | getFirstSelectedItem (void) const
| Return a pointer to the first selected item.
ListboxItem * | getNextSelected (const ListboxItem *start_item) const
| Return a pointer to the next selected item after item start_item.
ListboxItem * | getListboxItemFromIndex (size_t index) const
| Return the item at index position index.
size_t | getItemIndex (const ListboxItem *item) const
| Return the index of ListboxItem item.
bool | isSortEnabled (void) const
| return whether list sorting is enabled
bool | isMultiselectEnabled (void) const
| return whether multi-select is enabled
bool | isItemTooltipsEnabled (void) const
bool | isItemSelected (size_t index) const
| return whether the string at index position index is selected
ListboxItem * | findItemWithText (const String &text, const ListboxItem *start_item)
| Search the list for an item with the specified text.
bool | isListboxItemInList (const ListboxItem *item) const
| Return whether the specified ListboxItem is in the List.
bool | isVertScrollbarAlwaysShown (void) const
| Return whether the vertical scroll bar is always shown.
bool | isHorzScrollbarAlwaysShown (void) const
| Return whether the horizontal scroll bar is always shown.
virtual void | initialiseComponents (void)
| Initialise the Window based object ready for use.
void | resetList (void)
| Remove all items from the list.
void | addItem (ListboxItem *item)
| Add the given ListboxItem to the list.
void | insertItem (ListboxItem *item, const ListboxItem *position)
| Insert an item into the list box before a specified item already in the list.
void | removeItem (const ListboxItem *item)
| Removes the given item from the list box. If the item is has the auto delete state set, the item will be deleted.
void | clearAllSelections (void)
| Clear the selected state for all items.
void | setSortingEnabled (bool setting)
| Set whether the list should be sorted.
void | setMultiselectEnabled (bool setting)
| Set whether the list should allow multiple selections or just a single selection.
void | setShowVertScrollbar (bool setting)
| Set whether the vertical scroll bar should always be shown.
void | setShowHorzScrollbar (bool setting)
| Set whether the horizontal scroll bar should always be shown.
void | setItemTooltipsEnabled (bool setting)
void | setItemSelectState (ListboxItem *item, bool state)
| Set the select state of an attached ListboxItem.
void | setItemSelectState (size_t item_index, bool state)
| Set the select state of an attached ListboxItem.
void | handleUpdatedItemData (void)
| Causes the list box to update it's internal state after changes have been made to one or more attached ListboxItem objects.
void | ensureItemIsVisible (size_t item_index)
| Ensure the item at the specified index is visible within the list box.
void | ensureItemIsVisible (const ListboxItem *item)
| Ensure the item at the specified index is visible within the list box.
virtual Rect | getListRenderArea (void) const
| Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering list items.
Scrollbar * | getVertScrollbar () const
| Return a pointer to the vertical scrollbar component widget for this Listbox.
Scrollbar * | getHorzScrollbar () const
| Return a pointer to the horizontal scrollbar component widget for this Listbox.
float | getTotalItemsHeight (void) const
| Return the sum of all item heights.
float | getWidestItemWidth (void) const
| Return the width of the widest item.
ListboxItem * | getItemAtPoint (const Point &pt) const
| Return a pointer to the ListboxItem attached to this Listbox at the given screen pixel co-ordinate.
| Listbox (const String &type, const String &name)
| Constructor for Listbox base class.
virtual | ~Listbox (void)
| Destructor for Listbox base class.
## Static Public Attributes
static const String | EventNamespace
| Namespace for global events.
static const String | WidgetTypeName
| Window factory name.
static const String | EventListContentsChanged
static const String | EventSelectionChanged
static const String | EventSortModeChanged
static const String | EventMultiselectModeChanged
static const String | EventVertScrollbarModeChanged
static const String | EventHorzScrollbarModeChanged
static const String | VertScrollbarNameSuffix
| Widget name suffix for the vertical scrollbar component.
static const String | HorzScrollbarNameSuffix
| Widget name suffix for the horizontal scrollbar component.
## Protected Types
typedef std::vector < ListboxItem * > | LBItemList
## 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.
void | selectRange (size_t start, size_t end)
| select all strings between positions start and end. (inclusive) including end.
bool | clearAllSelections_impl (void)
| Clear the selected state for all items (implementation)
bool | resetList_impl (void)
| Remove all items from the list.
virtual bool | testClassName_impl (const String &class_name) const
| Return whether this window was inherited from the given class name at some point in the inheritance hierarchy.
bool | handle_scrollChange (const EventArgs &args)
| Internal handler that is triggered when the user interacts with the scrollbars.
virtual bool | validateWindowRenderer (const String &name) const
| Function used in checking if a WindowRenderer is valid for this window.
void | resortList ()
| Causes the internal list to be (re)sorted.
virtual void | onListContentsChanged (WindowEventArgs &e)
| Handler called internally when the list contents are changed.
virtual void | onSelectionChanged (WindowEventArgs &e)
| Handler called internally when the currently selected item or items changes.
virtual void | onSortModeChanged (WindowEventArgs &e)
| Handler called internally when the sort mode setting changes.
virtual void | onMultiselectModeChanged (WindowEventArgs &e)
| Handler called internally when the multi-select mode setting changes.
virtual void | onVertScrollbarModeChanged (WindowEventArgs &e)
| Handler called internally when the forced display of the vertical scroll bar setting changes.
virtual void | onHorzScrollbarModeChanged (WindowEventArgs &e)
| Handler called internally when the forced display of the horizontal scroll bar setting changes.
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.
virtual void | onMouseMove (MouseEventArgs &e)
| Handler called when the mouse cursor has been moved within this window's area.
## Protected Attributes
bool | d_sorted
| true if list is sorted
bool | d_multiselect
| true if multi-select is enabled
bool | d_forceVertScroll
| true if vertical scrollbar should always be displayed
bool | d_forceHorzScroll
| true if horizontal scrollbar should always be displayed
bool | d_itemTooltips
| true if each item should have an individual tooltip
LBItemList | d_listItems
| list of items in the list box.
ListboxItem * | d_lastSelected
| holds pointer to the last selected item (used in range selections)
## Friends
class | ListboxWindowRenderer

## Detailed Description

Base class for standard Listbox widget.

## Member Function Documentation

void CEGUI::Listbox::addItem | ( | ListboxItem * | item | ) |

Add the given ListboxItem to the list.

Parameters:

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

Returns:
  Nothing.

void CEGUI::Listbox::clearAllSelections | ( | void |  | ) |

Clear the selected state for all items.

Returns:
  Nothing.

bool CEGUI::Listbox::clearAllSelections_impl | ( | void |  | ) | `[protected]`

Clear the selected state for all items (implementation)

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

void CEGUI::Listbox::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.

void CEGUI::Listbox::ensureItemIsVisible | ( | size_t | item_index | ) |

Ensure the item at the specified index is visible within the list box.

Parameters:

  item_index | Zero based index of the item to be made visible in the list box. If this value is out of range, the list is always scrolled to the bottom.

Returns:
  Nothing.

void CEGUI::Listbox::ensureItemIsVisible | ( | const ListboxItem * | item | ) |

Ensure the item at the specified index is visible within the list box.

Parameters:

  item | Pointer to the ListboxItem to be made visible in the list box.

Returns:
  Nothing.

Exceptions:

  InvalidRequestException | thrown if item is not attached to this list box.

ListboxItem* CEGUI::Listbox::findItemWithText | ( | const String & | text,
|  | const ListboxItem * | start_item
| ) |  |

Search the list for an item with the specified text.

Parameters:

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

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

Exceptions:

  InvalidRequestException | thrown if item is not attached to this list box.

ListboxItem* CEGUI::Listbox::getFirstSelectedItem | ( | void |  | ) | const

Return a pointer to the first selected item.

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

Scrollbar* CEGUI::Listbox::getHorzScrollbar | ( |  | ) | const

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

Returns:
  Pointer to a Scrollbar object.

Exceptions:

  UnknownObjectException | Thrown if the horizontal Scrollbar component does not exist.

ListboxItem* CEGUI::Listbox::getItemAtPoint | ( | const Point & | pt | ) | const

Return a pointer to the ListboxItem attached to this Listbox at the given screen pixel co-ordinate.

Returns:
  Pointer to the ListboxItem attached to this Listbox that is at screen position pt, or 0 if no ListboxItem attached to this Listbox is at that position.

size_t CEGUI::Listbox::getItemCount | ( | void |  | ) | const`[inline]`

Return number of items attached to the list box.

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

size_t CEGUI::Listbox::getItemIndex | ( | const ListboxItem * | item | ) | const

Return the index of ListboxItem item.

Parameters:

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

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

Exceptions:

  InvalidRequestException | thrown if item is not attached to this list box.

ListboxItem* CEGUI::Listbox::getListboxItemFromIndex | ( | size_t | index | ) | const

Return the item at index position index.

Parameters:

  index | Zero based index of the item to be returned.

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

Exceptions:

  InvalidRequestException | thrown if index is out of range.

virtual Rect CEGUI::Listbox::getListRenderArea | ( | void |  | ) | const`[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::Listbox::getNextSelected | ( | const ListboxItem * | start_item | ) | const

Return a pointer to the next selected item after item start_item.

Parameters:

  start_item | Pointer to the ListboxItem where the search for the next selected item is to begin. If this parameter is NULL, the search will begin with the first item in the list box.

Returns:
  Pointer to a ListboxItem based object that is the next selected item in the list after the item specified by start_item. Will return NULL if no further items were selected.

Exceptions:

  InvalidRequestException | thrown if start_item is not attached to this list box.

size_t CEGUI::Listbox::getSelectedCount | ( | void |  | ) | const

Return the number of selected items in the list box.

Returns:
  Total number of attached items that are in the selected state.

Scrollbar* CEGUI::Listbox::getVertScrollbar | ( |  | ) | const

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

Returns:
  Pointer to a Scrollbar object.

Exceptions:

  UnknownObjectException | Thrown if the vertical Scrollbar component does not exist.

void CEGUI::Listbox::handleUpdatedItemData | ( | void |  | ) |

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

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

Returns:
  Nothing.

virtual void CEGUI::Listbox::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.

Reimplemented in CEGUI::ComboDropList.

void CEGUI::Listbox::insertItem | ( | ListboxItem * | item,
|  | const ListboxItem * | position
| ) |  |

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

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

Parameters:

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

Returns:
  Nothing.

Exceptions:

  InvalidRequestException | thrown if no ListboxItem position is attached to this list box.

bool CEGUI::Listbox::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::Listbox::isItemSelected | ( | size_t | index | ) | const

return whether the string at index position index is selected

Parameters:

  index | Zero based index of the item to be examined.

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

Exceptions:

  InvalidRequestException | thrown if index is out of range.

bool CEGUI::Listbox::isListboxItemInList | ( | const ListboxItem * | item | ) | const

Return whether the specified ListboxItem is in the List.

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

bool CEGUI::Listbox::isMultiselectEnabled | ( | void |  | ) | const`[inline]`

return whether multi-select is enabled

Returns:
  true if multi-select is enabled, false if multi-select is not enabled.

bool CEGUI::Listbox::isSortEnabled | ( | void |  | ) | const`[inline]`

return whether list sorting is enabled

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

bool CEGUI::Listbox::isVertScrollbarAlwaysShown | ( | void |  | ) | const

Return whether the vertical scroll bar is always shown.

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

virtual void CEGUI::Listbox::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.

Reimplemented in CEGUI::ComboDropList.

virtual void CEGUI::Listbox::onMouseMove | ( | MouseEventArgs & | e | ) | `[protected, virtual]`

Handler called when the mouse cursor has been moved within this window's area.

Parameters:

  e | MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

Reimplemented in CEGUI::ComboDropList.

virtual void CEGUI::Listbox::onMouseWheel | ( | MouseEventArgs & | e | ) | `[protected, virtual]`

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

Parameters:

  e | MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

virtual void CEGUI::Listbox::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::Listbox::removeItem | ( | const ListboxItem * | item | ) |

Removes the given item from the list box. If the item is has the auto delete state set, the item will be deleted.

Parameters:

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

Returns:
  Nothing.

void CEGUI::Listbox::resetList | ( | void |  | ) |

Remove all items from the list.

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

bool CEGUI::Listbox::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::Listbox::setItemSelectState | ( | size_t | item_index,
|  | bool | state
| ) |  |

Set the select state of an attached ListboxItem.

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

Parameters:

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

Returns:
  Nothing.

Exceptions:

  InvalidRequestException | thrown if item_index is out of range for the list box

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

Set the select state of an attached ListboxItem.

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

Parameters:

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

Returns:
  Nothing.

Exceptions:

  InvalidRequestException | thrown if item is not attached to this list box.

void CEGUI::Listbox::setMultiselectEnabled | ( | bool | setting | ) |

Set whether the list should allow multiple selections or just a single selection.

Parameters:

  setting | true if the widget should allow multiple items to be selected, false if the widget should only allow a single selection.

Returns:
  Nothing.

void CEGUI::Listbox::setShowHorzScrollbar | ( | bool | setting | ) |

Set whether the horizontal scroll bar should always be shown.

Parameters:

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

Returns:
  Nothing.

void CEGUI::Listbox::setShowVertScrollbar | ( | bool | setting | ) |

Set whether the vertical scroll bar should always be shown.

Parameters:

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

Returns:
  Nothing.

void CEGUI::Listbox::setSortingEnabled | ( | bool | setting | ) |

Set whether the list should be sorted.

Parameters:

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

Returns:
  Nothing.

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

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

Parameters:

  class_name | The class name that is to be checked.

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

Reimplemented from CEGUI::Window.

Reimplemented in CEGUI::ComboDropList.

References CEGUI::Window::testClassName_impl().

Referenced by CEGUI::ComboDropList::testClassName_impl().

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

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

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

Reimplemented from CEGUI::Window.

## Member Data Documentation

const String CEGUI::Listbox::EventHorzScrollbarModeChanged`[static]`

Event fired when the mode setting that forces the display of the horizontal scroll bar for the Listbox is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Listbox whose horizontal scrollbar mode has been changed.

const String CEGUI::Listbox::EventListContentsChanged`[static]`

Event fired when the contents of the list is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Listbox whose content is changed.

const String CEGUI::Listbox::EventMultiselectModeChanged`[static]`

Event fired when the multi-select mode setting changes for the Listbox. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Listbox whose multi-select mode has been changed.

const String CEGUI::Listbox::EventSelectionChanged`[static]`

Event fired when there is a change to the currently selected item(s) within the list. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Litbox that has had a change in the selected items.

const String CEGUI::Listbox::EventSortModeChanged`[static]`

Event fired when the sort mode setting changes for the Listbox. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Listbox whose sort mode has been changed.

const String CEGUI::Listbox::EventVertScrollbarModeChanged`[static]`

Event fired when the mode setting that forces the display of the vertical scroll bar for the Listbox is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Listbox whose vertical scrollbar mode has been changed.