CEGUI::Listbox Class Reference

Base class for standard Listbox widget. More...

Inheritance diagram for CEGUI::Listbox:

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

Collaboration graph
[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.
ListboxItemgetFirstSelectedItem (void) const
 Return a pointer to the first selected item.
ListboxItemgetNextSelected (const ListboxItem *start_item) const
 Return a pointer to the next selected item after item start_item.
ListboxItemgetListboxItemFromIndex (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
ListboxItemfindItemWithText (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 initialise (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 after 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.
 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 EventListContentsChanged
 Event triggered when the contents of the list is changed.
static const String EventSelectionChanged
 Event triggered when there is a change to the currently selected item(s).
static const String EventSortModeChanged
 Event triggered when the sort mode setting changes.
static const String EventMultiselectModeChanged
 Event triggered when the multi-select mode setting changes.
static const String EventVertScrollbarModeChanged
 Event triggered when the vertical scroll bar 'force' setting changes.
static const String EventHorzScrollbarModeChanged
 Event triggered when the horizontal scroll bar 'force' setting changes.

Protected Types

typedef std::vector< ListboxItem * > LBItemList

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 ScrollbarcreateVertScrollbar (const String &name) const =0
 create and return a pointer to a Scrollbar widget for use as vertical scroll bar
virtual ScrollbarcreateHorzScrollbar (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 caching 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 addListboxEvents (void)
 Add list box specific events.
void configureScrollbars (void)
 display required integrated scroll bars according to current state of the list box and update their values.
void selectRange (size_t start, size_t end)
 select all strings between positions start and end. (inclusive) including end.
float getTotalItemsHeight (void) const
 Return the sum of all item heights.
float getWidestItemWidth (void) const
 Return the width of the widest item.
bool clearAllSelections_impl (void)
 Clear the selected state for all items (implementation).
ListboxItemgetItemAtPoint (const Point &pt) const
 Return the ListboxItem under the given window local pixel co-ordinate.
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.
bool handle_scrollChange (const EventArgs &args)
 Internal handler that is triggered when the user interacts with the scrollbars.
void populateRenderCache ()
 Update the rendering cache.
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
Scrollbard_vertScrollbar
 vertical scroll-bar widget
Scrollbard_horzScrollbar
 horizontal scroll-bar widget
LBItemList d_listItems
 list of items in the list box.
ListboxItemd_lastSelected
 holds pointer to the last selected item (used in range selections)

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.

virtual void CEGUI::Listbox::cacheListboxBaseImagery  )  [protected, pure virtual]
 

Perform caching 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::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.

virtual Scrollbar* CEGUI::Listbox::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 given to the created widget component.
Returns:
Pointer to a Scrollbar to be used for scrolling the list horizontally.

virtual Scrollbar* CEGUI::Listbox::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 given to the created widget component.
Returns:
Pointer to a Scrollbar to be used for scrolling the list vertically.

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.

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.

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.

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

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

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.

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

Reimplemented in CEGUI::ComboDropList.

void CEGUI::Listbox::insertItem ListboxItem item,
const ListboxItem position
 

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

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

Parameters:
item Pointer to the ListboxItem to be inserted. Note that it is the passed object that is added to the list, a copy is not made. If this parameter is NULL, nothing happens.
position Pointer to a ListboxItem that item is to be inserted after. If this parameter is NULL, the item is inserted at the start of the list.
Returns:
Nothing.
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.

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.

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.

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.

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

Reimplemented in CEGUI::ComboDropList.


Generated on Sat Nov 26 10:10:05 2005 for Crazy Eddies GUI System by  doxygen 1.4.5