text: /***********************************************************************
      filename:   CEGUITree.h
      created:	5-13-07
      author:		Jonathan Welch (Based on Code by David Durant)
   *************************************************************************/
  /***************************************************************************
   *   Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team
   *
   *   Permission is hereby granted, free of charge, to any person obtaining
   *   a copy of this software and associated documentation files (the
   *   "Software"), to deal in the Software without restriction, including
   *   without limitation the rights to use, copy, modify, merge, publish,
   *   distribute, sublicense, and/or sell copies of the Software, and to
   *   permit persons to whom the Software is furnished to do so, subject to
   *   the following conditions:
   *
   *   The above copyright notice and this permission notice shall be
   *   included in all copies or substantial portions of the Software.
   *
   *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
   *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
   *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
   *   OTHER DEALINGS IN THE SOFTWARE.
   ***************************************************************************/
  #ifndef _CEGUITree_h_
  #define _CEGUITree_h_
  
  #include "../CEGUIBase.h"
  #include "../CEGUIWindow.h"
  #include "../CEGUIWindowManager.h"
  #include "CEGUITreeItem.h"
  #include "CEGUITreeProperties.h"
  #include <vector>
  
  #if defined(_MSC_VER)
  #	pragma warning(push)
  #	pragma warning(disable : 4251)
  #endif
  
  // Start of CEGUI namespace section
  namespace CEGUI
  {
  /*!
   \brief
      EventArgs based class that is used for objects passed to input event
      handlers concerning Tree events.
   */
  class CEGUIEXPORT TreeEventArgs : public WindowEventArgs
  {
  public:
      TreeEventArgs(Window* wnd) : WindowEventArgs(wnd)
          { treeItem = 0; }
  
      TreeItem *treeItem;
  };
  
  
  /*!
   \brief
      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.
      \par
      While no alternative currently exists, a superior, replacement tree widget
      will be provided prior to the final removal of the current implementation.
   */
  class CEGUIEXPORT Tree : public Window
  {
      friend class TreeItem;
      typedef	std::vector<TreeItem*>	LBItemList;
      
  public:
      //! Namespace for global events
      static const String EventNamespace;
      static const String WidgetTypeName;
      
      /*************************************************************************
          Constants
       *************************************************************************/
      // event names
      /** Event fired when the content of the tree is changed.
       * Handlers are passed a const WindowEventArgs reference with
       * WindowEventArgs::window set to the Tree whose content has changed.
       */
      static const String EventListContentsChanged;
      /** Event fired when there is a change to the currently selected item(s).
       * Handlers are passed a const TreeEventArgs reference with
       * WindowEventArgs::window set to the Tree whose item selection has changed,
       * and TreeEventArgs::treeItem is set to the (last) item to be selected, or
       * 0 if none.
       */
      static const String EventSelectionChanged;
      /** Event fired when the sort mode setting for the Tree is changed.
       * Handlers are passed a const WindowEventArgs reference with
       * WindowEventArgs::window set to the Tree whose sort mode has been
       * changed.
       */
      static const String EventSortModeChanged;
      /** Event fired when the multi-select mode setting for the Tree changes.
       * Handlers are passed a const TreeEventArgs reference with
       * WindowEventArgs::window set to the Tree whose setting has changed.
       * TreeEventArgs::treeItem is always set to 0.
       */
      static const String EventMultiselectModeChanged;
      /** Event fired when the mode setting that forces the display of the
       * vertical scroll bar for the tree is changed.
       * Handlers are passed a const WindowEventArgs reference with
       * WindowEventArgs::window set to the Tree whose vertical scrollbar mode has
       * been changed.
       */
      static const String EventVertScrollbarModeChanged;
      /** Event fired when the mode setting that forces the display of the
       * horizontal scroll bar for the tree is changed.
       * Handlers are passed a const WindowEventArgs reference with
       * WindowEventArgs::window set to the Tree whose horizontal scrollbar mode
       * has been changed.
       */
      static const String EventHorzScrollbarModeChanged;
      /** Event fired when a branch of the tree is opened by the user.
       * Handlers are passed a const TreeEventArgs reference with
       * WindowEventArgs::window set to the Tree containing the branch that has
       * been opened and TreeEventArgs::treeItem set to the TreeItem at the head
       * of the opened branch.
       */
      static const String EventBranchOpened;
      /** Event fired when a branch of the tree is closed by the user.
       * Handlers are passed a const TreeEventArgs reference with
       * WindowEventArgs::window set to the Tree containing the branch that has
       * been closed and TreeEventArgs::treeItem set to the TreeItem at the head
       * of the closed branch.
       */
      static const String EventBranchClosed;
  
      //Render the actual tree
      void doTreeRender()
          { populateGeometryBuffer(); }
  
      //UpdateScrollbars
      void doScrollbars()
          { configureScrollbars(); }
  
      /*************************************************************************
          Accessor Methods
       *************************************************************************/
      /*!
       \brief
          Return number of items attached to the tree
       
       \return
          the number of items currently attached to this tree.
       */
      size_t getItemCount(void) const
          { return d_listItems.size(); }
  
      /*!
       \brief
          Return the number of selected items in the tree.
       
       \return
          Total number of attached items that are in the selected state.
       */
      size_t getSelectedCount(void) const;
  
      /*!
       \brief
          Return a pointer to the first selected item.
       
       \return
          Pointer to a TreeItem based object that is the first selected item in
          the tree.  will return 0 if no item is selected.
       */
      TreeItem* getFirstSelectedItem(void) const;
          
      /*!
       \brief
          Return a pointer to the first selected item.
       
       \return
          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* getLastSelectedItem(void) const
          { return d_lastSelected; }
  
      /*!
       \brief
          Return a pointer to the next selected item after item \a start_item
       
       \param 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.
       
       \return
           Pointer to a TreeItem based object that is the next selected item in
           the tree after the item specified by \a start_item.  Will return 0 if
           no further items were selected.
       
       \exception	InvalidRequestException	thrown if \a start_item is not attached
          to this tree.
       */
      TreeItem* getNextSelected(const TreeItem* start_item) const;
      
      TreeItem* getNextSelectedItemFromList(const LBItemList &itemList,
                                            const TreeItem* start_item,
                                            bool& foundStartItem) const;
  
      /*!
       \brief
          return whether tree sorting is enabled
       
       \return
          - true if the tree is sorted
          - false if the tree is not sorted
       */
      bool isSortEnabled(void) const
          { return d_sorted; }
      
      void setItemRenderArea(Rect& r)
          { d_itemArea = r; }
      
      Scrollbar* getVertScrollbar()
          { return d_vertScrollbar; }
  
      Scrollbar* getHorzScrollbar()
          { return d_horzScrollbar; }
  
      /*!
       \brief
          return whether multi-select is enabled
       
       \return
          true if multi-select is enabled, false if multi-select is not enabled.
       */
      bool isMultiselectEnabled(void) const
          { return d_multiselect; }
      
      bool isItemTooltipsEnabled(void) const
          { return d_itemTooltips; }
  
      /*!
       \brief
          Search the tree for an item with the specified text
       
       \param text
          String object containing the text to be searched for.
       
       \param start_item
          TreeItem where the search is to begin, the search will not include \a
          item.  If \a item is 0, the search will begin from the first item in
          the tree.
       
       \return
          Pointer to the first TreeItem in the tree after \a item that has text
          matching \a text.  If no item matches the criteria, 0 is returned.
       
       \exception	InvalidRequestException	thrown if \a item is not attached to
          this tree.
       */
      TreeItem* findFirstItemWithText(const String& text);
  
      TreeItem* findNextItemWithText(const String& text,
                                     const TreeItem* start_item);
  
      TreeItem* findItemWithTextFromList(const LBItemList &itemList,
                                         const String& text,
                                         const TreeItem* start_item,
                                         bool foundStartItem);
  
      /*!
       \brief
          Search the tree for an item with the specified text
       
       \param text
          String object containing the text to be searched for.
       
       \param start_item
          TreeItem where the search is to begin, the search will not include
          \a item.  If \a item is 0, the search will begin from the first item in
          the tree.
       
       \return
          Pointer to the first TreeItem in the tree after \a item that has text
          matching \a text.  If no item matches the criteria 0 is returned.
       
       \exception	InvalidRequestException	thrown if \a item is not attached to
          this tree.
       */
      TreeItem* findFirstItemWithID(uint searchID);
      TreeItem* findNextItemWithID(uint searchID, const TreeItem* start_item);
      TreeItem* findItemWithIDFromList(const LBItemList &itemList, uint searchID,
                                       const TreeItem* start_item,
                                       bool foundStartItem);
  
      /*!
       \brief
          Return whether the specified TreeItem is in the tree
       
       \return
          - true if TreeItem \a item is in the tree
          - false if TreeItem \a item is not in the tree.
       */
      bool isTreeItemInList(const TreeItem* item) const;
  
      /*!
       \brief
          Return whether the vertical scroll bar is always shown.
       
       \return
           - 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 isVertScrollbarAlwaysShown(void) const;
  
      /*!
       \brief
          Return whether the horizontal scroll bar is always shown.
       
       \return
           - 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 isHorzScrollbarAlwaysShown(void) const;
  
      /*************************************************************************
          Manipulator Methods
       *************************************************************************/
      /*!
       \brief
          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.
  
       \return
          Nothing
       */
      virtual void initialise(void);
  
      /*!
       \brief
          Remove all items from the tree.
       
          Note that this will cause 'AutoDelete' items to be deleted.
       */
      void resetList(void);
  
      /*!
       \brief
          Add the given TreeItem to the tree.
       
       \param 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.
       
       \return
          Nothing.
       */
      void addItem(TreeItem* item);
  
      /*!
       \brief
          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.
       
       \param 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.
       
       \param position
           Pointer to a TreeItem that \a item is to be inserted after.  If this
           parameter is 0, the item is inserted at the start of the tree.
       
       \return
          Nothing.
       
       \exception InvalidRequestException	thrown if no TreeItem \a position is
          attached to this tree.
       */
      void insertItem(TreeItem* item, const TreeItem* position);
  
      /*!
       \brief
          Removes the given item from the tree.  If the item is has the auto
          delete state set, the item will be deleted.
       
       \param item
          Pointer to the TreeItem that is to be removed.  If \a item is not
          attached to this tree then nothing will happen.
       
       \return
          Nothing.
       */
      void removeItem(const TreeItem* item);
  
      /*!
       \brief
          Clear the selected state for all items.
       
       \return
          Nothing.
       */
      void clearAllSelections(void);
      bool clearAllSelectionsFromList(const LBItemList &itemList);
  
      /*!
       \brief
          Set whether the tree should be sorted.
       
       \param setting
          - true if the tree should be sorted
          - false if the tree should not be sorted.
       
       \return
          Nothing.
       */
      void setSortingEnabled(bool setting);
  
      /*!
       \brief
          Set whether the tree should allow multiple selections or just a single
          selection.
       
       \param  setting
           - true if the widget should allow multiple items to be selected
           - false if the widget should only allow a single selection.
  
       \return
          Nothing.
       */
      void setMultiselectEnabled(bool setting);
  
      /*!
       \brief
          Set whether the vertical scroll bar should always be shown.
       
       \param 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.
  
       \return
          Nothing.
       */
      void setShowVertScrollbar(bool setting);
  
      /*!
       \brief
          Set whether the horizontal scroll bar should always be shown.
       
       \param 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.
  
       \return
          Nothing.
       */
      void setShowHorzScrollbar(bool setting);
      
      void setItemTooltipsEnabled(bool setting);
  
      /*!
       \brief
          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.
       
       \param item
          The TreeItem to be affected.
          This item must be attached to the tree.
       
       \param state
          - true to select the item.
          - false to de-select the item.
       
       \return
          Nothing.
       
       \exception	InvalidRequestException	thrown if \a item is not attached to
          this tree.
       */
      void setItemSelectState(TreeItem* item, bool state);
  
      /*!
       \brief
          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.
       
       \param item_index
          The zero based index of the TreeItem to be affected.
          This must be a valid index (0 <= index < getItemCount())
  
       \param state
          - true to select the item.
          - false to de-select the item.
       
       \return
          Nothing.
       
       \exception	InvalidRequestException	thrown if \a item_index is out of range
          for the tree
       */
      void setItemSelectState(size_t item_index, bool state);
      
      /*!
       \brief
          Set the LookNFeel that shoule be used for this window.
       
       \param look
          String object holding the name of the look to be assigned to the window.
       
       \return
          Nothing.
       
       \exception UnknownObjectException
          thrown if the look'n'feel specified by \a look does not exist.
       
       \note
          Once a look'n'feel has been assigned it is locked - as in cannot be
          changed.
       */
      virtual void setLookNFeel(const String& look);
      
      /*!
       \brief
          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.
       
       \return
          Nothing.
       */
      void handleUpdatedItemData(void);
  
      /*!
       \brief
          Ensure the item at the specified index is visible within the tree.
       
       \param item
          Pointer to the TreeItem to be made visible in the tree.
       
       \return
          Nothing.
       
       \exception	InvalidRequestException	thrown if \a item is not attached to
          this tree.
       */
      void ensureItemIsVisible(const TreeItem* item);
      
      
      /*************************************************************************
       Construction and Destruction
       *************************************************************************/
      /*!
       \brief
          Constructor for Tree base class.
       */
      Tree(const String& type, const String& name);
  
      /*!
       \brief
          Destructor for Tree base class.
       */
      virtual ~Tree(void);
  
  protected:
      /*************************************************************************
          Abstract Implementation Functions (must be provided by derived class)
       *************************************************************************/
      /*!
       \brief
          Return a Rect object describing, in un-clipped pixels, the window
          relative area that is to be used for rendering tree items.
       
       \return
          Rect object describing the area of the Window to be used for rendering
          tree items.
       */
      virtual	Rect getTreeRenderArea(void) const
          { return d_itemArea; }
      
      /*!
       \brief
          create and return a pointer to a Scrollbar widget for use as vertical
          scroll bar.
       
       \param name
          String holding the name to be given to the created widget component.
       
       \return
          Pointer to a Scrollbar to be used for scrolling the tree vertically.
       */
      virtual Scrollbar* createVertScrollbar(const String& name) const
          { return (Scrollbar*)(WindowManager::getSingleton().getWindow(name)); }
  
      /*!
       \brief
          create and return a pointer to a Scrollbar widget for use as horizontal
          scroll bar.
       
       \param name
          String holding the name to be given to the created widget component.
       
       \return
          Pointer to a Scrollbar to be used for scrolling the tree horizontally.
       */
      virtual Scrollbar* createHorzScrollbar(const String& name) const
          { return (Scrollbar*)(WindowManager::getSingleton().getWindow(name)); }
  
      /*!
       \brief
           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.
       
       \return
          Nothing.
       */
      virtual	void cacheTreeBaseImagery()
      {}
      
      /*************************************************************************
          Implementation Functions
       *************************************************************************/
      /*!
       \brief
          Checks if a tree item is visible (searches sub-items)
      */
      bool containsOpenItemRecursive(const LBItemList& itemList, TreeItem* item);
  
      /*!
       \brief
          Add tree specific events
       */
      void addTreeEvents(void);
      
      
      /*!
       \brief
          display required integrated scroll bars according to current state of
          the tree and update their values.
       */
      void configureScrollbars(void);
      
      /*!
       \brief
          select all strings between positions \a start and \a end.  (inclusive)
          including \a end.
       */
      void selectRange(size_t start, size_t end);
      
      /*!
       \brief
          Return the sum of all item heights
       */
      float getTotalItemsHeight(void) const;
      void getTotalItemsInListHeight(const LBItemList &itemList,
                                      float *heightSum) const;
  
      /*!
       \brief
          Return the width of the widest item
       */
      float getWidestItemWidth(void) const;
      void getWidestItemWidthInList(const LBItemList &itemList, int itemDepth,
                                    float *widest) const;
      
      /*!
       \brief
          Clear the selected state for all items (implementation)
       
       \return
          - true if treeItem was found in the search.
          - false if it was not.
       */
      bool getHeightToItemInList(const LBItemList &itemList,
                                 const TreeItem *treeItem,
                                 int itemDepth,
                                 float *height) const;
  
      /*!
       \brief
          Clear the selected state for all items (implementation)
       
       \return
          - true if some selections were cleared
          - false nothing was changed.
       */
      bool clearAllSelections_impl(void);
  
      /*!
       \brief
          Return the TreeItem under the given window local pixel co-ordinate.
       
       \return
           TreeItem that is under window pixel co-ordinate \a pt, or 0 if no
           item is under that position.
       */
      TreeItem* getItemAtPoint(const Point& pt) const;
      TreeItem* getItemFromListAtPoint(const LBItemList &itemList, float *bottomY,
                                       const Point& pt) const;
  
      /*!
       \brief
          Remove all items from the tree.
       
       \note
          Note that this will cause 'AutoDelete' items to be deleted.
       
       \return
           - true if the tree contents were changed.
           - false if the tree contents were not changed (tree already empty).
       */
      bool resetList_impl(void);
  
      /*!
       \brief
          Return whether this window was inherited from the given class name at
          some point in the inheritance heirarchy.
       
       \param class_name
          The class name that is to be checked.
       
       \return
          true if this window was inherited from \a class_name. false if not.
       */
      virtual bool testClassName_impl(const String& class_name) const
      {
          if (class_name==(const utf8*)"Tree")
              return true;
  
          return Window::testClassName_impl(class_name);
      }
      
      /*!
       \brief
          Internal handler that is triggered when the user interacts with the
          scrollbars.
       */
      bool handle_scrollChange(const EventArgs& args);
      
       // overridden from Window base class.
       virtual void populateGeometryBuffer();
   
       void drawItemList(LBItemList& itemList, Rect& itemsArea, float widest,
                         Vector2& itemPos, GeometryBuffer& geometry, float alpha);
      
      /*************************************************************************
          New event handlers
       *************************************************************************/
      /*!
       \brief
          Handler called internally when the tree contents are changed
       */
      virtual	void onListContentsChanged(WindowEventArgs& e);
  
      /*!
       \brief
          Handler called internally when the currently selected item or items
          changes.
       */
      virtual	void onSelectionChanged(TreeEventArgs& e);
  
      /*!
       \brief
          Handler called internally when the sort mode setting changes.
       */
      virtual	void onSortModeChanged(WindowEventArgs& e);
  
      /*!
       \brief
          Handler called internally when the multi-select mode setting changes.
       */
      virtual	void onMultiselectModeChanged(WindowEventArgs& e);
  
      /*!
       \brief
          Handler called internally when the forced display of the vertical scroll
          bar setting changes.
       */
      virtual	void onVertScrollbarModeChanged(WindowEventArgs& e);
  
      /*!
       \brief
          Handler called internally when the forced display of the horizontal
          scroll bar setting changes.
       */
      virtual	void onHorzScrollbarModeChanged(WindowEventArgs& e);
      
      /*!
       \brief
          Handler called internally when the user opens a branch of the tree.
       */
      virtual	void onBranchOpened(TreeEventArgs& e);
      
      /*!
       \brief
          Handler called internally when the user closes a branch of the tree.
       */
      virtual	void onBranchClosed(TreeEventArgs& e);
      
      /*************************************************************************
          Overridden Event handlers
       *************************************************************************/
      virtual void onSized(WindowEventArgs& e);
      virtual void onMouseButtonDown(MouseEventArgs& e);
      virtual	void onMouseWheel(MouseEventArgs& e);
      virtual void onMouseMove(MouseEventArgs& e);
  
      /*************************************************************************
          Implementation Data
       *************************************************************************/
      //! true if tree is sorted
      bool d_sorted;
      //! true if multi-select is enabled
      bool d_multiselect;
      //! true if vertical scrollbar should always be displayed
      bool d_forceVertScroll;
      //! true if horizontal scrollbar should always be displayed
      bool d_forceHorzScroll;
      //! true if each item should have an individual tooltip
      bool d_itemTooltips;
      //! vertical scroll-bar widget
      Scrollbar* d_vertScrollbar;
      //! horizontal scroll-bar widget
      Scrollbar* d_horzScrollbar;
      //! list of items in the tree.
      LBItemList d_listItems;
      //! holds pointer to the last selected item (used in range selections)
      TreeItem* d_lastSelected;
      ImagerySection* d_openButtonImagery;
      ImagerySection* d_closeButtonImagery;
  
  private:
      /*************************************************************************
          Static Properties for this class
       *************************************************************************/
      static TreeProperties::Sort					d_sortProperty;
      static TreeProperties::MultiSelect			d_multiSelectProperty;
      static TreeProperties::ForceVertScrollbar	d_forceVertProperty;
      static TreeProperties::ForceHorzScrollbar	d_forceHorzProperty;
      static TreeProperties::ItemTooltips			d_itemTooltipsProperty;
      
      /*************************************************************************
          Private methods
       *************************************************************************/
      void addTreeProperties(void);
      Rect d_itemArea;
  };
  
  /*!
   \brief
      Helper function used in sorting to compare two tree item text strings
      via the TreeItem pointers and return if \a a is less than \a b.
   */
  bool lbi_less(const TreeItem* a, const TreeItem* b);
  
  
  /*!
   \brief
      Helper function used in sorting to compare two tree item text strings
      via the TreeItem pointers and return if \a a is greater than \a b.
   */
  bool lbi_greater(const TreeItem* a, const TreeItem* b);
  
  } // End of  CEGUI namespace section
  
  
  #if defined(_MSC_VER)
  #	pragma warning(pop)
  #endif
  
  #endif	// end of guard _CEGUITree_h_
  