Crazy Eddie's GUI System  0.8.7
widgets/Tree.h
1 /***********************************************************************
2  created: 5-13-07
3  author: Jonathan Welch (Based on Code by David Durant)
4  *************************************************************************/
5 /***************************************************************************
6  * Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team
7  *
8  * Permission is hereby granted, free of charge, to any person obtaining
9  * a copy of this software and associated documentation files (the
10  * "Software"), to deal in the Software without restriction, including
11  * without limitation the rights to use, copy, modify, merge, publish,
12  * distribute, sublicense, and/or sell copies of the Software, and to
13  * permit persons to whom the Software is furnished to do so, subject to
14  * the following conditions:
15  *
16  * The above copyright notice and this permission notice shall be
17  * included in all copies or substantial portions of the Software.
18  *
19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
20  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
22  * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
23  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
24  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25  * OTHER DEALINGS IN THE SOFTWARE.
26  ***************************************************************************/
27 #ifndef _CEGUITree_h_
28 #define _CEGUITree_h_
29 
30 #include "../Base.h"
31 #include "../Window.h"
32 #include "../WindowManager.h"
33 #include "./TreeItem.h"
34 #include "./Scrollbar.h"
35 #include <vector>
36 
37 #if defined(_MSC_VER)
38 # pragma warning(push)
39 # pragma warning(disable : 4251)
40 #endif
41 
42 // Start of CEGUI namespace section
43 namespace CEGUI
44 {
50 class CEGUIEXPORT TreeEventArgs : public WindowEventArgs
51 {
52 public:
54  { treeItem = 0; }
55 
56  TreeItem *treeItem;
57 };
58 
59 
74 class CEGUIEXPORT Tree : public Window
75 {
76  friend class TreeItem;
77 
78  typedef std::vector<TreeItem*
79  CEGUI_VECTOR_ALLOC(TreeItem*)> LBItemList;
80 
81 public:
83  static const String EventNamespace;
84  static const String WidgetTypeName;
85 
86  /*************************************************************************
87  Constants
88  *************************************************************************/
89  // event names
134  static const String EventBranchOpened;
141  static const String EventBranchClosed;
142 
143  //Render the actual tree
144  void doTreeRender()
145  { populateGeometryBuffer(); }
146 
147  //UpdateScrollbars
148  void doScrollbars()
149  { configureScrollbars(); }
150 
151  /*************************************************************************
152  Accessor Methods
153  *************************************************************************/
161  size_t getItemCount(void) const
162  { return d_listItems.size(); }
163 
171  size_t getSelectedCount(void) const;
172 
182 
193  { return d_lastSelected; }
194 
212  TreeItem* getNextSelected(const TreeItem* start_item) const;
213 
214  TreeItem* getNextSelectedItemFromList(const LBItemList &itemList,
215  const TreeItem* start_item,
216  bool& foundStartItem) const;
217 
226  bool isSortEnabled(void) const
227  { return d_sorted; }
228 
229  void setItemRenderArea(Rectf& r)
230  { d_itemArea = r; }
231 
232  Scrollbar* getVertScrollbar()
233  { return d_vertScrollbar; }
234 
235  Scrollbar* getHorzScrollbar()
236  { return d_horzScrollbar; }
237 
245  bool isMultiselectEnabled(void) const
246  { return d_multiselect; }
247 
248  bool isItemTooltipsEnabled(void) const
249  { return d_itemTooltips; }
250 
271 
272  TreeItem* findNextItemWithText(const String& text,
273  const TreeItem* start_item);
274 
275  TreeItem* findItemWithTextFromList(const LBItemList &itemList,
276  const String& text,
277  const TreeItem* start_item,
278  bool foundStartItem);
279 
299  TreeItem* findFirstItemWithID(uint searchID);
300  TreeItem* findNextItemWithID(uint searchID, const TreeItem* start_item);
301  TreeItem* findItemWithIDFromList(const LBItemList &itemList, uint searchID,
302  const TreeItem* start_item,
303  bool foundStartItem);
304 
313  bool isTreeItemInList(const TreeItem* item) const;
314 
323  bool isVertScrollbarAlwaysShown(void) const;
324 
333  bool isHorzScrollbarAlwaysShown(void) const;
334 
335  /*************************************************************************
336  Manipulator Methods
337  *************************************************************************/
349  virtual void initialise(void);
350 
357  void resetList(void);
358 
371  void addItem(TreeItem* item);
372 
396  void insertItem(TreeItem* item, const TreeItem* position);
397 
410  void removeItem(const TreeItem* item);
411 
419  void clearAllSelections(void);
420  bool clearAllSelectionsFromList(const LBItemList &itemList);
421 
433  void setSortingEnabled(bool setting);
434 
447  void setMultiselectEnabled(bool setting);
448 
462  void setShowVertScrollbar(bool setting);
463 
477  void setShowHorzScrollbar(bool setting);
478 
479  void setItemTooltipsEnabled(bool setting);
480 
504  void setItemSelectState(TreeItem* item, bool state);
505 
529  void setItemSelectState(size_t item_index, bool state);
530 
548  virtual void setLookNFeel(const String& look);
549 
564 
578  void ensureItemIsVisible(const TreeItem* item);
579 
580 
581  /*************************************************************************
582  Construction and Destruction
583  *************************************************************************/
588  Tree(const String& type, const String& name);
589 
594  virtual ~Tree(void);
595 
596 protected:
597  /*************************************************************************
598  Abstract Implementation Functions (must be provided by derived class)
599  *************************************************************************/
609  virtual Rectf getTreeRenderArea(void) const
610  { return d_itemArea; }
611 
623  virtual Scrollbar* createVertScrollbar(const String& name) const
624  { return static_cast<Scrollbar*>(getChild(name)); }
625 
637  virtual Scrollbar* createHorzScrollbar(const String& name) const
638  { return static_cast<Scrollbar*>(getChild(name)); }
639 
650  virtual void cacheTreeBaseImagery()
651  {}
652 
653  /*************************************************************************
654  Implementation Functions
655  *************************************************************************/
660  bool containsOpenItemRecursive(const LBItemList& itemList, TreeItem* item);
661 
666  void addTreeEvents(void);
667 
668 
675 
681  void selectRange(size_t start, size_t end);
682 
687  float getTotalItemsHeight(void) const;
688  void getTotalItemsInListHeight(const LBItemList &itemList,
689  float *heightSum) const;
690 
695  float getWidestItemWidth(void) const;
696  void getWidestItemWidthInList(const LBItemList &itemList, int itemDepth,
697  float *widest) const;
698 
707  bool getHeightToItemInList(const LBItemList &itemList,
708  const TreeItem *treeItem,
709  int itemDepth,
710  float *height) const;
711 
721 
730  TreeItem* getItemAtPoint(const Vector2f& pt) const;
731  TreeItem* getItemFromListAtPoint(const LBItemList &itemList, float *bottomY,
732  const Vector2f& pt) const;
733 
745  bool resetList_impl(void);
746 
752  bool handle_scrollChange(const EventArgs& args);
753 
754  // overridden from Window base class.
755  virtual void populateGeometryBuffer();
757 
758  void drawItemList(LBItemList& itemList, Rectf& itemsArea, float widest,
759  Vector2f& itemPos, GeometryBuffer& geometry, float alpha);
760 
761  /*************************************************************************
762  New event handlers
763  *************************************************************************/
769 
776 
782 
788 
795 
802 
807  virtual void onBranchOpened(TreeEventArgs& e);
808 
813  virtual void onBranchClosed(TreeEventArgs& e);
814 
815  /*************************************************************************
816  Overridden Event handlers
817  *************************************************************************/
818  virtual void onSized(ElementEventArgs& e);
820  virtual void onMouseWheel(MouseEventArgs& e);
821  virtual void onMouseMove(MouseEventArgs& e);
822 
823  /*************************************************************************
824  Implementation Data
825  *************************************************************************/
827  bool d_sorted;
841  LBItemList d_listItems;
844  const ImagerySection* d_openButtonImagery;
845  const ImagerySection* d_closeButtonImagery;
846 
847 private:
848  /*************************************************************************
849  Private methods
850  *************************************************************************/
851  void addTreeProperties(void);
852  Rectf d_itemArea;
853 };
854 
860 bool lbi_less(const TreeItem* a, const TreeItem* b);
861 
862 
868 bool lbi_greater(const TreeItem* a, const TreeItem* b);
869 
870 } // End of CEGUI namespace section
871 
872 
873 #if defined(_MSC_VER)
874 # pragma warning(pop)
875 #endif
876 
877 #endif // end of guard _CEGUITree_h_
EventArgs based class that is used for objects passed to handlers triggered for events concerning som...
Definition: Element.h:211
Base class used as the argument to all subscribers Event object.
Definition: EventArgs.h:51
Abstract class defining the interface for objects that buffer geometry for later rendering.
Definition: GeometryBuffer.h:44
Class that encapsulates a re-usable collection of imagery specifications.
Definition: ImagerySection.h:49
EventArgs based class that is used for objects passed to input event handlers concerning mouse input.
Definition: InputEvent.h:281
Base scroll bar class.
Definition: widgets/Scrollbar.h:90
String class used within the GUI system.
Definition: String.h:64
EventArgs based class that is used for objects passed to input event handlers concerning Tree events.
Definition: widgets/Tree.h:51
Base class for tree items.
Definition: TreeItem.h:59
Base class for standard Tree widget.
Definition: widgets/Tree.h:75
virtual void onBranchOpened(TreeEventArgs &e)
Handler called internally when the user opens a branch of the tree.
void setItemSelectState(size_t item_index, bool state)
Set the select state of an attached TreeItem.
virtual void onVertScrollbarModeChanged(WindowEventArgs &e)
Handler called internally when the forced display of the vertical scroll bar setting changes.
void handleUpdatedItemData(void)
Causes the tree to update it's internal state after changes have been made to one or more attached Tr...
virtual void onBranchClosed(TreeEventArgs &e)
Handler called internally when the user closes a branch of the tree.
bool d_multiselect
true if multi-select is enabled
Definition: widgets/Tree.h:829
bool handle_scrollChange(const EventArgs &args)
Internal handler that is triggered when the user interacts with the scrollbars.
bool d_sorted
true if tree is sorted
Definition: widgets/Tree.h:827
bool handleFontRenderSizeChange(const EventArgs &args)
handler function for when font render size changes.
bool isTreeItemInList(const TreeItem *item) const
Return whether the specified TreeItem is in the tree.
size_t getSelectedCount(void) const
Return the number of selected items in the tree.
void setItemSelectState(TreeItem *item, bool state)
Set the select state of an attached TreeItem.
bool d_forceHorzScroll
true if horizontal scrollbar should always be displayed
Definition: widgets/Tree.h:833
void configureScrollbars(void)
display required integrated scroll bars according to current state of the tree and update their value...
bool d_forceVertScroll
true if vertical scrollbar should always be displayed
Definition: widgets/Tree.h:831
TreeItem * getLastSelectedItem(void) const
Return a pointer to the first selected item.
Definition: widgets/Tree.h:192
Scrollbar * d_vertScrollbar
vertical scroll-bar widget
Definition: widgets/Tree.h:837
float getWidestItemWidth(void) const
Return the width of the widest item.
virtual void onHorzScrollbarModeChanged(WindowEventArgs &e)
Handler called internally when the forced display of the horizontal scroll bar setting changes.
TreeItem * findFirstItemWithID(uint searchID)
Search the tree for an item with the specified text.
bool isSortEnabled(void) const
return whether tree sorting is enabled
Definition: widgets/Tree.h:226
TreeItem * getFirstSelectedItem(void) const
Return a pointer to the first selected item.
static const String EventSelectionChanged
Definition: widgets/Tree.h:101
static const String EventHorzScrollbarModeChanged
Definition: widgets/Tree.h:127
virtual void onListContentsChanged(WindowEventArgs &e)
Handler called internally when the tree contents are changed.
bool isVertScrollbarAlwaysShown(void) const
Return whether the vertical scroll bar is always shown.
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.
virtual void onSelectionChanged(TreeEventArgs &e)
Handler called internally when the currently selected item or items changes.
virtual Scrollbar * createVertScrollbar(const String &name) const
create and return a pointer to a Scrollbar widget for use as vertical scroll bar.
Definition: widgets/Tree.h:623
virtual void populateGeometryBuffer()
Update the rendering cache.
virtual void onSized(ElementEventArgs &e)
Handler called when the window's size changes.
virtual void onSortModeChanged(WindowEventArgs &e)
Handler called internally when the sort mode setting changes.
Scrollbar * d_horzScrollbar
horizontal scroll-bar widget
Definition: widgets/Tree.h:839
virtual Rectf getTreeRenderArea(void) const
Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used fo...
Definition: widgets/Tree.h:609
void ensureItemIsVisible(const TreeItem *item)
Ensure the item at the specified index is visible within the tree.
void addTreeEvents(void)
Add tree specific events.
void addItem(TreeItem *item)
Add the given TreeItem to the tree.
virtual void cacheTreeBaseImagery()
Perform caching of the widget control frame and other 'static' areas. This method should not render t...
Definition: widgets/Tree.h:650
static const String EventListContentsChanged
Definition: widgets/Tree.h:94
bool resetList_impl(void)
Remove all items from the tree.
void clearAllSelections(void)
Clear the selected state for all items.
bool isMultiselectEnabled(void) const
return whether multi-select is enabled
Definition: widgets/Tree.h:245
virtual void initialise(void)
Initialise the Window based object ready for use.
virtual void onMultiselectModeChanged(WindowEventArgs &e)
Handler called internally when the multi-select mode setting changes.
virtual ~Tree(void)
Destructor for Tree base class.
TreeItem * findFirstItemWithText(const String &text)
Search the tree for an item with the specified text.
void setShowVertScrollbar(bool setting)
Set whether the vertical scroll bar should always be shown.
size_t getItemCount(void) const
Return number of items attached to the tree.
Definition: widgets/Tree.h:161
Tree(const String &type, const String &name)
Constructor for Tree base class.
bool clearAllSelections_impl(void)
Clear the selected state for all items (implementation)
static const String EventVertScrollbarModeChanged
Definition: widgets/Tree.h:120
void resetList(void)
Remove all items from the tree.
static const String EventBranchOpened
Definition: widgets/Tree.h:134
TreeItem * d_lastSelected
holds pointer to the last selected item (used in range selections)
Definition: widgets/Tree.h:843
bool isHorzScrollbarAlwaysShown(void) const
Return whether the horizontal scroll bar is always shown.
static const String EventNamespace
Namespace for global events.
Definition: widgets/Tree.h:83
void insertItem(TreeItem *item, const TreeItem *position)
Insert an item into the tree after a specified item already in the tree.
static const String EventSortModeChanged
Definition: widgets/Tree.h:107
virtual void onMouseButtonDown(MouseEventArgs &e)
Handler called when a mouse button has been depressed within this window's area.
virtual void onMouseMove(MouseEventArgs &e)
Handler called when the mouse cursor has been moved within this window's area.
void setSortingEnabled(bool setting)
Set whether the tree should be sorted.
static const String EventBranchClosed
Definition: widgets/Tree.h:141
TreeItem * getNextSelected(const TreeItem *start_item) const
Return a pointer to the next selected item after item start_item.
virtual void setLookNFeel(const String &look)
Set the LookNFeel that shoule be used for this window.
static const String EventMultiselectModeChanged
Definition: widgets/Tree.h:113
bool d_itemTooltips
true if each item should have an individual tooltip
Definition: widgets/Tree.h:835
bool containsOpenItemRecursive(const LBItemList &itemList, TreeItem *item)
Checks if a tree item is visible (searches sub-items)
void setShowHorzScrollbar(bool setting)
Set whether the horizontal scroll bar should always be shown.
void removeItem(const TreeItem *item)
Removes the given item from the tree. If the item is has the auto delete state set,...
virtual void onMouseWheel(MouseEventArgs &e)
Handler called when the mouse wheel (z-axis) position changes within this window's area.
TreeItem * getItemAtPoint(const Vector2f &pt) const
Return the TreeItem under the given window local pixel co-ordinate.
bool getHeightToItemInList(const LBItemList &itemList, const TreeItem *treeItem, int itemDepth, float *height) const
Clear the selected state for all items (implementation)
virtual Scrollbar * createHorzScrollbar(const String &name) const
create and return a pointer to a Scrollbar widget for use as horizontal scroll bar.
Definition: widgets/Tree.h:637
LBItemList d_listItems
list of items in the tree.
Definition: widgets/Tree.h:841
void setMultiselectEnabled(bool setting)
Set whether the tree should allow multiple selections or just a single selection.
EventArgs based class that is used for objects passed to handlers triggered for events concerning som...
Definition: InputEvent.h:252
An abstract base class providing common functionality and specifying the required interface for deriv...
Definition: Window.h:151
Main namespace for Crazy Eddie's GUI Library.
Definition: arch_overview.dox:1
bool lbi_less(const ListboxItem *a, const ListboxItem *b)
Helper function used in sorting to compare two list box item text strings via the ListboxItem pointer...
bool lbi_greater(const ListboxItem *a, const ListboxItem *b)
Helper function used in sorting to compare two list box item text strings via the ListboxItem pointer...