CEGUI::Tree Class Reference

Base class for standard Tree widget. More...

Inheritance diagram for CEGUI::Tree:

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

Collaboration graph
[legend]

List of all members.

Public Member Functions

void doTreeRender ()
void doScrollbars ()
size_t getItemCount (void) const
 Return number of items attached to the tree.
size_t getSelectedCount (void) const
 Return the number of selected items in the tree.
TreeItemgetFirstSelectedItem (void) const
 Return a pointer to the first selected item.
TreeItemgetLastSelectedItem (void) const
 Return a pointer to the first selected item.
TreeItemgetNextSelected (const TreeItem *start_item) const
 Return a pointer to the next selected item after item start_item.
TreeItemgetNextSelectedItemFromList (const LBItemList &itemList, const TreeItem *start_item, bool foundStartItem) const
bool isSortEnabled (void) const
 return whether tree sorting is enabled
void setItemRenderArea (Rect &r)
ScrollbargetVertScrollbar ()
ScrollbargetHorzScrollbar ()
bool isMultiselectEnabled (void) const
 return whether multi-select is enabled
bool isItemTooltipsEnabled (void) const
TreeItemfindFirstItemWithText (const String &text)
 Search the tree for an item with the specified text.
TreeItemfindNextItemWithText (const String &text, const TreeItem *start_item)
TreeItemfindItemWithTextFromList (const LBItemList &itemList, const String &text, const TreeItem *start_item, bool foundStartItem)
TreeItemfindFirstItemWithID (uint searchID)
 Search the tree for an item with the specified text.
TreeItemfindNextItemWithID (uint searchID, const TreeItem *start_item)
TreeItemfindItemWithIDFromList (const LBItemList &itemList, uint searchID, const TreeItem *start_item, bool foundStartItem)
bool isTreeItemInList (const TreeItem *item) const
 Return whether the specified TreeItem is in the tree.
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 tree.
void addItem (TreeItem *item)
 Add the given TreeItem to the tree.
void insertItem (TreeItem *item, const TreeItem *position)
 Insert an item into the tree after a specified item already in the tree.
void removeItem (const TreeItem *item)
 Removes the given item from the tree. 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.
bool clearAllSelectionsFromList (const LBItemList &itemList)
void setSortingEnabled (bool setting)
 Set whether the tree should be sorted.
void setMultiselectEnabled (bool setting)
 Set whether the tree 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 (TreeItem *item, bool state)
 Set the select state of an attached TreeItem.
void setItemSelectState (size_t item_index, bool state)
 Set the select state of an attached TreeItem.
virtual void setLookNFeel (const String &look)
 Set the LookNFeel that shoule be used for this window.
void handleUpdatedItemData (void)
 Causes the tree to update it's internal state after changes have been made to one or more attached TreeItem objects.
void ensureItemIsVisible (const TreeItem *item)
 Ensure the item at the specified index is visible within the tree.
 Tree (const String &type, const String &name)
 Constructor for Tree base class.
virtual ~Tree (void)
 Destructor for Tree base class.

Static Public Attributes

static const String EventNamespace
 Namespace for global events.
static const String WidgetTypeName
static const String EventListContentsChanged
 Event triggered when the contents of the tree 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.
static const String EventBranchOpened
 Event triggered when a branch of the tree is opened by the user.
static const String EventBranchClosed
 Event triggered when a branch of the tree is closed by the user.

Protected Member Functions

virtual Rect getTreeRenderArea (void) const
 Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering tree items.
virtual ScrollbarcreateVertScrollbar (const String &name) const
 create and return a pointer to a Scrollbar widget for use as vertical scroll bar.
virtual ScrollbarcreateHorzScrollbar (const String &name) const
 create and return a pointer to a Scrollbar widget for use as horizontal scroll bar.
virtual void cacheTreeBaseImagery ()
 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.
bool containsOpenItemRecursive (const LBItemList &itemList, TreeItem *item)
 Checks if a tree item is visible (searches sub-items).
void addTreeEvents (void)
 Add tree specific events.
void configureScrollbars (void)
 display required integrated scroll bars according to current state of the tree 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.
void getTotalItemsInListHeight (const LBItemList &itemList, float *heightSum) const
float getWidestItemWidth (void) const
 Return the width of the widest item.
void getWidestItemWidthInList (const LBItemList &itemList, int itemDepth, float *widest) const
bool getHeightToItemInList (const LBItemList &itemList, const TreeItem *treeItem, int itemDepth, float *height) const
 Clear the selected state for all items (implementation).
bool clearAllSelections_impl (void)
 Clear the selected state for all items (implementation).
TreeItemgetItemAtPoint (const Point &pt) const
 Return the TreeItem under the given window local pixel co-ordinate.
TreeItemgetItemFromListAtPoint (const LBItemList &itemList, float *bottomY, const Point &pt) const
bool resetList_impl (void)
 Remove all items from the tree.
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.
virtual void populateRenderCache ()
 Update the rendering cache.
void drawItemList (LBItemList &itemList, Rect &itemsArea, float widest, Vector3 &itemPos, RenderCache &cache, float alpha)
virtual void onListContentsChanged (WindowEventArgs &e)
 Handler called internally when the tree contents are changed.
virtual void onSelectionChanged (TreeEventArgs &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 onBranchOpened (TreeEventArgs &e)
 Handler called internally when the user opens a branch of the tree.
virtual void onBranchClosed (TreeEventArgs &e)
 Handler called internally when the user closes a branch of the tree.
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 tree 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 tree.
TreeItemd_lastSelected
 holds pointer to the last selected item (used in range selections)
ImagerySectionopenButtonImagery
ImagerySectioncloseButtonImagery

Friends

class TreeItem


Detailed Description

Base class for standard Tree widget.

Deprecated:
The CEGUI::Tree, CEGUI::TreeItem and any other associated classes are deprecated and thier use should be minimised - preferably eliminated - where possible. It is extremely unfortunate that this widget was ever added to CEGUI since its design and implementation are poor and do not meet established standards for the CEGUI project.
While no alternative currently exists, a superior, replacement tree widget will be provided prior to the final removal of the current implementation.

Member Function Documentation

void CEGUI::Tree::addItem ( TreeItem item  ) 

Add the given TreeItem to the tree.

Parameters:
item Pointer to the TreeItem to be added to the tree. Note that it is the passed object that is added to the tree, a copy is not made. If this parameter is NULL, nothing happens.
Returns:
Nothing.

References d_listItems, isSortEnabled(), CEGUI::lbi_less(), onListContentsChanged(), and CEGUI::TreeItem::setOwnerWindow().

Referenced by insertItem().

virtual void CEGUI::Tree::cacheTreeBaseImagery (  )  [inline, protected, 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.

Referenced by populateRenderCache().

void CEGUI::Tree::clearAllSelections ( void   ) 

Clear the selected state for all items.

Returns:
Nothing.

References clearAllSelections_impl(), and onSelectionChanged().

bool CEGUI::Tree::clearAllSelections_impl ( void   )  [protected]

Clear the selected state for all items (implementation).

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

References d_listItems.

Referenced by clearAllSelections(), onMouseButtonDown(), and setItemSelectState().

virtual Scrollbar* CEGUI::Tree::createHorzScrollbar ( const String name  )  const [inline, protected, 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 tree horizontally.

Referenced by configureScrollbars(), and initialise().

virtual Scrollbar* CEGUI::Tree::createVertScrollbar ( const String name  )  const [inline, protected, 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 tree vertically.

Referenced by configureScrollbars(), and initialise().

void CEGUI::Tree::ensureItemIsVisible ( const TreeItem item  ) 

Ensure the item at the specified index is visible within the tree.

Parameters:
item Pointer to the TreeItem to be made visible in the tree.
Returns:
Nothing.
Exceptions:
InvalidRequestException thrown if item is not attached to this tree.

References CEGUI::Size::d_height, d_listItems, d_vertScrollbar, CEGUI::Scrollbar::getDocumentSize(), CEGUI::Rect::getHeight(), getHeightToItemInList(), getItemCount(), CEGUI::Scrollbar::getPageSize(), CEGUI::TreeItem::getPixelSize(), CEGUI::Scrollbar::getScrollPosition(), getTreeRenderArea(), and CEGUI::Scrollbar::setScrollPosition().

Referenced by onMouseButtonDown().

TreeItem * CEGUI::Tree::findFirstItemWithID ( uint  searchID  ) 

Search the tree for an item with the specified text.

Parameters:
text String object containing the text to be searched for.
start_item TreeItem where the search is to begin, the search will not include item. If item is 0, the search will begin from the first item in the tree.
Returns:
Pointer to the first TreeItem in the tree after item that has text matching text. If no item matches the criteria 0 is returned.
Exceptions:
InvalidRequestException thrown if item is not attached to this tree.

References d_listItems.

TreeItem * CEGUI::Tree::findFirstItemWithText ( const String text  ) 

Search the tree for an item with the specified text.

Parameters:
text String object containing the text to be searched for.
start_item TreeItem where the search is to begin, the search will not include item. If item is 0, the search will begin from the first item in the tree.
Returns:
Pointer to the first TreeItem in the tree after item that has text matching text. If no item matches the criteria, 0 is returned.
Exceptions:
InvalidRequestException thrown if item is not attached to this tree.

References d_listItems.

TreeItem * CEGUI::Tree::getFirstSelectedItem ( void   )  const

Return a pointer to the first selected item.

Returns:
Pointer to a TreeItem based object that is the first selected item in the tree. will return 0 if no item is selected.

References d_listItems.

Referenced by setMultiselectEnabled().

bool CEGUI::Tree::getHeightToItemInList ( const LBItemList &  itemList,
const TreeItem treeItem,
int  itemDepth,
float *  height 
) const [protected]

Clear the selected state for all items (implementation).

Returns:
  • true if treeItem was found in the search.
  • false if it was not.

References getItemCount().

Referenced by ensureItemIsVisible().

TreeItem * CEGUI::Tree::getItemAtPoint ( const Point pt  )  const [protected]

Return the TreeItem under the given window local pixel co-ordinate.

Returns:
TreeItem that is under window pixel co-ordinate pt, or 0 if no item is under that position.

References d_listItems, CEGUI::Rect::d_top, d_vertScrollbar, CEGUI::Vector2::d_y, CEGUI::Scrollbar::getScrollPosition(), getTreeRenderArea(), and CEGUI::Rect::isPointInRect().

Referenced by onMouseButtonDown(), and onMouseMove().

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

Return number of items attached to the tree.

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

Referenced by containsOpenItemRecursive(), ensureItemIsVisible(), getHeightToItemInList(), resetList_impl(), and setItemSelectState().

TreeItem* CEGUI::Tree::getLastSelectedItem ( void   )  const [inline]

Return a pointer to the first selected item.

Returns:
Pointer to a TreeItem based object that is the last item selected by the user, not necessarily the last selected in the tree. Will return 0 if no item is selected.

TreeItem * CEGUI::Tree::getNextSelected ( const TreeItem start_item  )  const

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

Parameters:
start_item Pointer to the TreeItem where the search for the next selected item is to begin. If this parameter is 0, the search will begin with the first item in the tree.
Returns:
Pointer to a TreeItem based object that is the next selected item in the tree after the item specified by start_item. Will return 0 if no further items were selected.
Exceptions:
InvalidRequestException thrown if start_item is not attached to this tree.

References d_listItems.

Referenced by setMultiselectEnabled().

size_t CEGUI::Tree::getSelectedCount ( void   )  const

Return the number of selected items in the tree.

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

References d_listItems.

Referenced by setMultiselectEnabled().

virtual Rect CEGUI::Tree::getTreeRenderArea ( void   )  const [inline, protected, virtual]

Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used for rendering tree items.

Returns:
Rect object describing the area of the Window to be used for rendering tree items.

Referenced by configureScrollbars(), ensureItemIsVisible(), and getItemAtPoint().

void CEGUI::Tree::handleUpdatedItemData ( void   ) 

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

Client code must call this whenever it has made any changes to TreeItem objects already attached to the tree. 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.

References configureScrollbars(), and CEGUI::Window::requestRedraw().

void CEGUI::Tree::initialise ( void   )  [virtual]

void CEGUI::Tree::insertItem ( TreeItem item,
const TreeItem position 
)

Insert an item into the tree after a specified item already in the tree.

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

Parameters:
item Pointer to the TreeItem to be inserted. Note that it is the passed object that is added to the tree, a copy is not made. If this parameter is 0, nothing happens.
position Pointer to a TreeItem that item is to be inserted after. If this parameter is 0, the item is inserted at the start of the tree.
Returns:
Nothing.
Exceptions:
InvalidRequestException thrown if no TreeItem position is attached to this tree.

References addItem(), d_listItems, isSortEnabled(), onListContentsChanged(), and CEGUI::TreeItem::setOwnerWindow().

bool CEGUI::Tree::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.

References d_forceHorzScroll.

bool CEGUI::Tree::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::Tree::isSortEnabled ( void   )  const [inline]

return whether tree sorting is enabled

Returns:
  • true if the tree is sorted
  • false if the tree is not sorted

Referenced by addItem(), and insertItem().

bool CEGUI::Tree::isTreeItemInList ( const TreeItem item  )  const

Return whether the specified TreeItem is in the tree.

Returns:
  • true if TreeItem item is in the tree
  • false if TreeItem item is not in the tree.

References d_listItems.

bool CEGUI::Tree::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.

References d_forceVertScroll.

void CEGUI::Tree::onMouseButtonDown ( MouseEventArgs e  )  [protected, virtual]

void CEGUI::Tree::onMouseMove ( MouseEventArgs e  )  [protected, virtual]

void CEGUI::Tree::onMouseWheel ( MouseEventArgs e  )  [protected, virtual]

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

References configureScrollbars(), and CEGUI::EventArgs::handled.

void CEGUI::Tree::populateRenderCache (  )  [protected, virtual]

void CEGUI::Tree::removeItem ( const TreeItem item  ) 

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

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

References d_lastSelected, d_listItems, CEGUI::TreeItem::isAutoDeleted(), and onListContentsChanged().

void CEGUI::Tree::resetList ( void   ) 

Remove all items from the tree.

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

References onListContentsChanged(), and resetList_impl().

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

Remove all items from the tree.

Note:
Note that this will cause 'AutoDelete' items to be deleted.
Returns:
  • true if the tree contents were changed.
  • false if the tree contents were not changed (tree already empty).

References d_lastSelected, d_listItems, and getItemCount().

Referenced by resetList(), and ~Tree().

void CEGUI::Tree::setItemSelectState ( size_t  item_index,
bool  state 
)

Set the select state of an attached TreeItem.

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

Parameters:
item_index The zero based index of the TreeItem 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 tree

References clearAllSelections_impl(), d_listItems, d_multiselect, getItemCount(), onSelectionChanged(), and CEGUI::TreeEventArgs::treeItem.

void CEGUI::Tree::setItemSelectState ( TreeItem item,
bool  state 
)

Set the select state of an attached TreeItem.

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

Parameters:
item The TreeItem to be affected. This item must be attached to the tree.
state 
  • true to select the item.
  • false to de-select the item.
Returns:
Nothing.
Exceptions:
InvalidRequestException thrown if item is not attached to this tree.

References clearAllSelections_impl(), containsOpenItemRecursive(), d_lastSelected, d_listItems, d_multiselect, CEGUI::TreeItem::isSelected(), onSelectionChanged(), CEGUI::TreeItem::setSelected(), and CEGUI::TreeEventArgs::treeItem.

void CEGUI::Tree::setLookNFeel ( const String look  )  [virtual]

Set the LookNFeel that shoule be used for this window.

Parameters:
look String object holding the name of the look to be assigned to the window.
Returns:
Nothing.
Exceptions:
UnknownObjectException thrown if the look'n'feel specified by look does not exist.
Note:
Once a look'n'feel has been assigned it is locked - as in cannot be changed.

Reimplemented from CEGUI::Window.

References initialise().

void CEGUI::Tree::setMultiselectEnabled ( bool  setting  ) 

Set whether the tree 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.

References d_multiselect, getFirstSelectedItem(), getNextSelected(), getSelectedCount(), onMultiselectModeChanged(), onSelectionChanged(), and CEGUI::TreeItem::setSelected().

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

References configureScrollbars(), d_forceHorzScroll, and onHorzScrollbarModeChanged().

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

References configureScrollbars(), d_forceVertScroll, and onVertScrollbarModeChanged().

void CEGUI::Tree::setSortingEnabled ( bool  setting  ) 

Set whether the tree should be sorted.

Parameters:
setting 
  • true if the tree should be sorted
  • false if the tree should not be sorted.
Returns:
Nothing.

References d_listItems, d_sorted, CEGUI::lbi_less(), and onSortModeChanged().

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

References CEGUI::Window::testClassName_impl().


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