CEGUI::ItemListBase Class Reference

Base class for item list widgets. More...

Inheritance diagram for CEGUI::ItemListBase:

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

Collaboration graph
[legend]

List of all members.

Public Types

enum  SortMode { Ascending, Descending, UserSort }
 Sort modes for ItemListBase.
typedef bool(* SortCallback )(const ItemEntry *a, const ItemEntry *b)

Public Member Functions

size_t getItemCount (void) const
 Return number of items attached to the list.
ItemEntrygetItemFromIndex (size_t index) const
 Return the item at index position index.
size_t getItemIndex (const ItemEntry *item) const
 Return the index of ItemEntry item.
ItemEntryfindItemWithText (const String &text, const ItemEntry *start_item)
 Search the list for an item with the specified text.
bool isItemInList (const ItemEntry *item) const
 Return whether the specified ItemEntry is in the List.
bool isAutoResizeEnabled () const
 Return whether this window is automatically resized to fit its content.
bool isSortEnabled (void) const
 Returns 'true' if the list is sorted.
SortMode getSortMode (void) const
 Get sort mode.
SortCallback getSortCallback (void) const
 Get user sorting callback.
virtual void initialiseComponents (void)
 Initialise the Window based object ready for use.
void resetList (void)
 Remove all items from the list.
void addItem (ItemEntry *item)
 Add the given ItemEntry to the list.
void insertItem (ItemEntry *item, const ItemEntry *position)
 Insert an item into the list before a specified item already in the list.
void removeItem (ItemEntry *item)
 Removes the given item from the list. If the item is has the 'DestroyedByParent' property set to 'true', the item will be deleted.
void handleUpdatedItemData (bool resort=false)
 Causes the list to update it's internal state after changes have been made to one or more attached ItemEntry objects.
void setAutoResizeEnabled (bool setting)
 Set whether or not this ItemListBase widget should automatically resize to fit its content.
virtual void sizeToContent (void)
 Resize the ItemListBase to exactly fit the content that is attached to it. Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering items.
virtual void endInitialisation (void)
 Triggers a ListContentsChanged event. These are not fired during initialisation for optimization purposes.
virtual void performChildWindowLayout (void)
 method called to perform extended laying out of attached child windows.
Rect getItemRenderArea (void) const
 Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering list items.
WindowgetContentPane (void) const
 Returns a pointer to the window that all items are directed too.
virtual void notifyItemClicked (ItemEntry *li)
 Notify this ItemListBase that the given item was just clicked. Internal function - NOT to be used from client code.
virtual void notifyItemSelectState (ItemEntry *li, bool state)
 Notify this ItemListBase that the given item just changed selection state. Internal function - NOT to be used from client code.
void setSortEnabled (bool setting)
 Set whether the list should be sorted (by text).
void setSortMode (SortMode mode)
 Set mode to be used when sorting the list.
void setSortCallback (SortCallback cb)
 Set a user callback as sorting function.
void sortList (bool relayout=true)
 Sort the list.
 ItemListBase (const String &type, const String &name)
 Constructor for ItemListBase base class.
virtual ~ItemListBase (void)
 Destructor for ItemListBase 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 EventSortEnabledChanged
 Event fired when the sort enabled state changes.
static const String EventSortModeChanged
 Event fired when the sort mode changes.

Protected Types

typedef std::vector< ItemEntry * > ItemEntryList

Protected Member Functions

virtual void sizeToContent_impl (void)
 Resize the ItemListBase to exactly fit the content that is attached to it. Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering items.
virtual Size getContentSize () const =0
 Returns the Size in unclipped pixels of the content attached to this ItemListBase that is attached to it.
virtual void layoutItemWidgets ()=0
 Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering list items.
bool resetList_impl (void)
 Remove all items from the list.
virtual bool testClassName_impl (const String &class_name) const
 Return whether this window was inherited from the given class name at some point in the inheritance hierarchy.
virtual bool validateWindowRenderer (const String &name) const
 Function used in checking if a WindowRenderer is valid for this window.
SortCallback getRealSortCallback (void) const
 Returns the SortCallback that's really going to be used for the sorting operation.
virtual void onListContentsChanged (WindowEventArgs &e)
 Handler called internally when the list contents are changed.
virtual void onSortEnabledChanged (WindowEventArgs &e)
 Handler called internally when sorting gets enabled.
virtual void onSortModeChanged (WindowEventArgs &e)
 Handler called internally when the sorting mode is changed.

Protected Attributes

ItemEntryList d_listItems
 list of items in the list.
bool d_autoResize
 Pointer to the content pane (for items), 0 if we're not using one.
Windowd_pane
 True if this ItemListBase is sorted. False if not.
bool d_sortEnabled
 The current sorting mode applied if sorting is enabled.
SortMode d_sortMode
 The user sort callback or 0 if none.
SortCallback d_sortCallback
 True if the list needs to be resorted.
bool d_resort


Detailed Description

Base class for item list widgets.

Member Function Documentation

void CEGUI::ItemListBase::addItem ( ItemEntry item  ) 

Add the given ItemEntry to the list.

Parameters:
item Pointer to the ItemEntry 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.

References CEGUI::Window::addChildWindow(), d_listItems, CEGUI::ItemEntry::d_ownerList, d_sortEnabled, getRealSortCallback(), and handleUpdatedItemData().

Referenced by insertItem().

ItemEntry * CEGUI::ItemListBase::findItemWithText ( const String text,
const ItemEntry 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 ItemEntry 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 ItemEntry 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.

References d_listItems, getItemIndex(), and CEGUI::Window::getText().

Window* CEGUI::ItemListBase::getContentPane ( void   )  const [inline]

Returns a pointer to the window that all items are directed too.

Returns:
A pointer to the content pane window, or 'this' if children are added directly to this window.

virtual Size CEGUI::ItemListBase::getContentSize (  )  const [protected, pure virtual]

Returns the Size in unclipped pixels of the content attached to this ItemListBase that is attached to it.

Returns:
Size object describing in unclipped pixels the size of the content ItemEntries attached to this menu.

Implemented in CEGUI::ItemListbox, CEGUI::Menubar, and CEGUI::PopupMenu.

Referenced by sizeToContent_impl().

size_t CEGUI::ItemListBase::getItemCount ( void   )  const [inline]

Return number of items attached to the list.

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

Referenced by CEGUI::ScrolledItemListBase::onMouseWheel().

ItemEntry * CEGUI::ItemListBase::getItemFromIndex ( 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 ItemEntry at index position index in the list.
Exceptions:
InvalidRequestException thrown if index is out of range.

References d_listItems.

size_t CEGUI::ItemListBase::getItemIndex ( const ItemEntry item  )  const

Return the index of ItemEntry item.

Parameters:
item Pointer to a ItemEntry whos zero based index is to be returned.
Returns:
Zero based index indicating the position of ItemEntry item in the list.
Exceptions:
InvalidRequestException thrown if item is not attached to this list.

References d_listItems.

Referenced by findItemWithText(), CEGUI::ItemListbox::getNextSelectedItemAfter(), and CEGUI::ItemListbox::notifyItemClicked().

Rect CEGUI::ItemListBase::getItemRenderArea ( void   )  const

void CEGUI::ItemListBase::handleUpdatedItemData ( bool  resort = false  ) 

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

It should not be necessary to call this from client code, as the ItemEntries themselves call it if their parent is an ItemListBase.

Parameters:
resort 'true' to redo the list sorting as well. 'false' to only do layout and perhaps auto resize. (defaults to 'false')
Returns:
Nothing.

References CEGUI::Window::d_destructionStarted, and onListContentsChanged().

Referenced by addItem(), endInitialisation(), insertItem(), resetList(), and setSortCallback().

void CEGUI::ItemListBase::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::ItemListbox, and CEGUI::ScrolledItemListBase.

References d_pane, CEGUI::Window::EventChildRemoved, and CEGUI::EventSet::subscribeEvent().

void CEGUI::ItemListBase::insertItem ( ItemEntry item,
const ItemEntry position 
)

Insert an item into the list 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 ItemEntry 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 ItemEntry that item is to be inserted before. If this parameter is NULL, the item is inserted at the start of the list.
Returns:
Nothing.

References CEGUI::Window::addChildWindow(), addItem(), d_listItems, CEGUI::ItemEntry::d_ownerList, d_sortEnabled, and handleUpdatedItemData().

bool CEGUI::ItemListBase::isAutoResizeEnabled (  )  const [inline]

Return whether this window is automatically resized to fit its content.

Returns:
true if automatic resizing is enabled, false if it is disabled.

bool CEGUI::ItemListBase::isItemInList ( const ItemEntry item  )  const

Return whether the specified ItemEntry is in the List.

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

References CEGUI::ItemEntry::d_ownerList.

virtual void CEGUI::ItemListBase::layoutItemWidgets (  )  [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 window relative area of the that is to be used for rendering the items.
Setup size and position for the item widgets attached to this ItemListBase
Returns:
Nothing.

Implemented in CEGUI::ItemListbox, CEGUI::Menubar, and CEGUI::PopupMenu.

Referenced by onListContentsChanged(), performChildWindowLayout(), and sortList().

void CEGUI::ItemListBase::performChildWindowLayout ( void   )  [virtual]

method called to perform extended laying out of attached child windows.

The system may call this at various times (like when it is resized for example), and it may be invoked directly where required.

Returns:
Nothing.

Reimplemented from CEGUI::Window.

References CEGUI::Window::d_initialising, and layoutItemWidgets().

void CEGUI::ItemListBase::removeItem ( ItemEntry item  ) 

Removes the given item from the list. If the item is has the 'DestroyedByParent' property set to 'true', the item will be deleted.

Parameters:
item Pointer to the ItemEntry that is to be removed. If item is not attached to this list then nothing will happen.
Returns:
Nothing.

References CEGUI::ItemEntry::d_ownerList, d_pane, CEGUI::Window::isDestroyedByParent(), and CEGUI::Window::removeChildWindow().

void CEGUI::ItemListBase::resetList ( void   ) 

Remove all items from the list.

Note that this will cause items, which does not have the 'DestroyedByParent' property set to 'false', to be deleted.

References handleUpdatedItemData(), and resetList_impl().

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

Remove all items from the list.

Note:
Note that this will cause items with the 'DestroyedByParent' property set to 'true', to be deleted.
Returns:
  • true if the list contents were changed.
  • false if the list contents were not changed (list already empty).

References d_listItems, d_pane, CEGUI::Window::isDestroyedByParent(), and CEGUI::Window::removeChildWindow().

Referenced by resetList().

void CEGUI::ItemListBase::setAutoResizeEnabled ( bool  setting  ) 

Set whether or not this ItemListBase widget should automatically resize to fit its content.

Parameters:
setting Boolean value that if true enables automatic resizing, if false disables automatic resizing.
Returns:
Nothing.

References d_autoResize, CEGUI::Window::d_initialising, and sizeToContent().

void CEGUI::ItemListBase::setSortCallback ( SortCallback  cb  ) 

Set a user callback as sorting function.

Parameters:
mode SortCallback

References CEGUI::Window::d_initialising, d_sortCallback, d_sortEnabled, handleUpdatedItemData(), and sortList().

void CEGUI::ItemListBase::setSortMode ( SortMode  mode  ) 

Set mode to be used when sorting the list.

Parameters:
mode SortMode enum.

References CEGUI::Window::d_initialising, d_sortEnabled, d_sortMode, onSortModeChanged(), and sortList().

virtual void CEGUI::ItemListBase::sizeToContent ( void   )  [inline, virtual]

Resize the ItemListBase to exactly fit the content that is attached to it. Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering items.

Returns:
Nothing

Referenced by onListContentsChanged(), and setAutoResizeEnabled().

void CEGUI::ItemListBase::sizeToContent_impl ( void   )  [protected, virtual]

Resize the ItemListBase to exactly fit the content that is attached to it. Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering items.

Returns:
Nothing

References CEGUI::Size::d_height, CEGUI::Size::d_width, CEGUI::Window::getArea(), getContentSize(), CEGUI::Rect::getHeight(), getItemRenderArea(), CEGUI::Window::getParentPixelSize(), CEGUI::Rect::getWidth(), and CEGUI::Window::setSize().

void CEGUI::ItemListBase::sortList ( bool  relayout = true  ) 

Sort the list.

Parameters:
relayout True if the item layout should be redone after the sorting. False to only sort the internal list. Nothing more.
This parameter defaults to true and should generally not be used in client code.

References d_listItems, getRealSortCallback(), and layoutItemWidgets().

Referenced by onListContentsChanged(), setSortCallback(), setSortEnabled(), and setSortMode().

virtual bool CEGUI::ItemListBase::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::ItemListbox, CEGUI::Menubar, CEGUI::MenuBase, CEGUI::PopupMenu, and CEGUI::ScrolledItemListBase.

References CEGUI::Window::testClassName_impl().

Referenced by CEGUI::ScrolledItemListBase::testClassName_impl(), and CEGUI::MenuBase::testClassName_impl().

virtual bool CEGUI::ItemListBase::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

ItemEntryList CEGUI::ItemListBase::d_listItems [protected]


Generated on Thu Nov 27 20:34:35 2008 for Crazy Eddies GUI System by  doxygen 1.5.7.1