Engine directory for ticket #1

Engine/source/gui/controls/guiTreeViewCtrl.h

@@ -0,0 +1,606 @@
+//-----------------------------------------------------------------------------
+// Copyright (c) 2012 GarageGames, LLC
+//
+// 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 OR COPYRIGHT HOLDERS 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 _GUI_TREEVIEWCTRL_H
+#define _GUI_TREEVIEWCTRL_H
+
+#include "core/bitSet.h"
+#include "math/mRect.h"
+#include "gfx/gFont.h"
+#include "gui/core/guiControl.h"
+#include "gui/core/guiArrayCtrl.h"
+
+
+class GuiTextEditCtrl;
+
+//------------------------------------------------------------------------------
+
+class GuiTreeViewCtrl : public GuiArrayCtrl
+{
+   private:
+      typedef GuiArrayCtrl Parent;
+
+   public:
+      /// @section GuiControl_Intro Introduction
+      /// @nosubgrouping
+
+      ///
+      class Item
+      {
+         public:
+
+            enum ItemState
+            {
+               Selected       = BIT( 0 ),
+               Expanded       = BIT( 1 ),
+               Marked         = BIT( 2 ), ///< Marked items are drawn with a border around them. This is
+                                        ///  different than "Selected" because it can only be set by script.
+               Filtered       = BIT( 3 ), ///< Whether the item is currently filtered out.
+               MouseOverBmp   = BIT( 4 ),
+               MouseOverText  = BIT( 5 ),
+               MouseOverIcon  = BIT( 6 ),
+               InspectorData  = BIT( 7 ), ///< Set if we're representing some inspector
+                                        /// info (ie, use mInspectorInfo, not mScriptInfo)
+
+               VirtualParent  = BIT( 8 ), ///< This indicates that we should be rendered as
+                                        ///  a parent even though we don't have any children.
+                                        ///  This is useful for preventing scenarios where
+                                        ///  we might want to create thousands of
+                                        ///  Items that might never be shown (for instance
+                                        ///  if we're browsing the object hierarchy in
+                                        ///  Torque, which might have thousands of objects).
+
+               RebuildVisited    = BIT( 9 ), ///< Rebuild traversal for virtual parents has visited and validated this item.
+               
+               ShowObjectId      = BIT( 10 ),
+               ShowClassName     = BIT( 11 ),
+               ShowObjectName    = BIT( 12 ),
+               ShowInternalName  = BIT( 13 ),
+               ShowClassNameForUnnamed = BIT( 14 )
+            };
+
+            GuiTreeViewCtrl* mParentControl;
+            BitSet32 mState;
+            SimObjectPtr< GuiControlProfile > mProfile;
+            S16 mId;
+            U16 mTabLevel;
+            Item* mParent;
+            Item* mChild;
+            Item* mNext;
+            Item* mPrevious;
+            String mTooltip;
+            S32 mIcon; //stores the icon that will represent the item in the tree
+            S32 mDataRenderWidth; /// this stores the pixel width needed
+                                  /// to render the item's data in the 
+                                  /// onRenderCell function to optimize
+                                  /// for speed.
+
+            Item( GuiTreeViewCtrl* parent, GuiControlProfile *pProfile );
+            ~Item();
+
+            struct ScriptTag
+            {
+               S8 mNormalImage;
+               S8 mExpandedImage;
+               StringTableEntry mText;
+               StringTableEntry mValue;
+            } mScriptInfo;
+            struct InspectorTag
+            {
+               SimObjectPtr<SimObject> mObject;
+            } mInspectorInfo;
+
+            /// @name Get Methods
+            /// @{
+
+            ///
+            S8 getNormalImage() const;
+            S8 getExpandedImage() const;
+            StringTableEntry getText();
+            StringTableEntry getValue();
+            inline const S16 getID() const { return mId; };
+            SimObject *getObject();
+            U32 getDisplayTextLength();
+            S32 getDisplayTextWidth(GFont *font);
+            void getDisplayText(U32 bufLen, char *buf);
+            bool hasObjectBasedTooltip();
+            void getTooltipText(U32 bufLen, char *buf);
+
+            /// @}
+
+
+            /// @name Set Methods
+            /// @{
+
+            /// Set whether an item is expanded or not (showing children or having them hidden)
+            void setExpanded( const bool f = true );
+            /// Set the image to display when an item IS expanded
+            void setExpandedImage(const S8 id);
+            /// Set the image to display when an item is NOT expanded
+            void setNormalImage(const S8 id);
+            /// Assign a SimObject pointer to an inspector data item
+            void setObject(SimObject *obj);
+            /// Set the items displayable text (caption)
+            void setText(StringTableEntry txt);
+            /// Set the items script value (data)
+            void setValue(StringTableEntry val);
+            /// Set the items virtual parent flag
+            void setVirtualParent( bool value );
+            /// Set whether the item is filtered out or not.
+            void setFiltered( bool value ) { mState.set( Filtered ); }
+
+            /// @}
+
+
+            /// @name State Retrieval
+            /// @{
+
+            /// Returns true if this item is expanded. For
+            /// inspector objects, the expansion is stored
+            /// on the SimObject, for other things we use our
+            /// bit vector.
+            bool isExpanded() const;
+
+            /// Return whether the item is current filtered out or not.
+            /// @note Parent items may be filtered and yet still be visible if they have
+            ///   children that are not filtered.
+            bool isFiltered() const { return mState.test( Filtered ); }
+
+            /// Returns true if an item is inspector data
+            /// or false if it's just an item.
+            bool isInspectorData() const { return mState.test(InspectorData); };
+
+            /// Returns true if we should show the expand art
+            /// and make the item interact with the mouse as if
+            /// it were a parent.
+            bool isParent() const;
+            
+            /// Return true if text label for inspector item should include internal name only.
+            bool showInternalNameOnly() const { return mState.test( ShowInternalName ) && !mState.test( ShowObjectName | ShowClassName | ShowObjectId ); }
+
+            /// Return true if text label for inspector item should include object name only.
+            bool showObjectNameOnly() const { return mState.test( ShowObjectName ) && !mState.test( ShowInternalName | ShowClassName | ShowObjectId ); }
+
+            /// @}
+
+            /// @name Searching Methods
+            /// @{
+            
+            /// Find a regular data item by it's script name.
+            Item* findChildByName( const char* name );
+
+            /// Find an inspector data item by it's SimObject pointer
+            Item* findChildByValue(const SimObject *obj);
+
+            /// Find a regular data item by it's script value
+            Item* findChildByValue(StringTableEntry Value);
+
+            /// @}
+            
+            /// Sort the childs of the item by their text.
+            ///
+            /// @param caseSensitive If true, sorting is case-sensitive.
+            /// @param traverseHierarchy If true, also triggers a sort() on all child items.
+            /// @param parentsFirst If true, parents are grouped before children in the resulting sort.
+            void sort( bool caseSensitive = true, bool traverseHierarchy = false, bool parentsFirst = false );
+
+         private:
+            void _connectMonitors();
+            void _disconnectMonitors();
+      };
+
+      friend class Item; // _onInspectorSetObjectModified
+
+      /// @name Enums
+      /// @{
+
+      ///
+      enum TreeState
+      {
+         RebuildVisible    = BIT(0), ///< Temporary flag, we have to rebuild the tree.
+         IsInspector       = BIT(1), ///< We are mapping a SimObject hierarchy.
+         IsEditable        = BIT(2), ///< We allow items to be moved around.
+         ShowTreeLines     = BIT(3), ///< Should we render tree lines or just icons?
+         BuildingVisTree   = BIT(4), ///< We are currently building the visible tree (prevent recursion)
+      };
+
+   protected:
+
+  		enum
+		{
+         MaxIcons = 32,
+		};
+
+      enum Icons
+      {
+         Default1 = 0,
+         SimGroup1,
+         SimGroup2,
+         SimGroup3,
+         SimGroup4,         
+         Hidden,         
+         Lock1,
+         Lock2,         
+         Default,
+         Icon31,
+         Icon32
+      };
+
+      enum mDragMidPointFlags
+      {
+            NomDragMidPoint,
+            AbovemDragMidPoint,
+            BelowmDragMidPoint
+      };
+
+      ///
+      enum HitFlags
+      {
+         OnIndent       = BIT(0),
+         OnImage        = BIT(1),
+         OnIcon         = BIT(2),
+         OnText         = BIT(3),         
+         OnRow          = BIT(4),
+      };
+
+      ///
+      enum BmpIndices
+      {
+         BmpFirstChild,
+         BmpLastChild,
+         BmpChild,
+         BmpExp,
+         BmpExpN,
+         BmpExpP,
+         BmpExpPN,
+         BmpCon,
+         BmpConN,
+         BmpConP,
+         BmpConPN,
+         BmpLine,
+         BmpGlow,
+      };
+
+      /// @}
+
+      /// @name Callbacks
+      /// @{
+
+      DECLARE_CALLBACK( bool, onDeleteObject, ( SimObject* object ) );
+      DECLARE_CALLBACK( bool, isValidDragTarget, ( S32 id, const char* value ) );
+      DECLARE_CALLBACK( void, onDefineIcons, () );
+      DECLARE_CALLBACK( void, onAddGroupSelected, ( SimGroup* group ) );
+      DECLARE_CALLBACK( void, onAddSelection, ( S32 itemOrObjectId, bool isLastSelection ) );
+      DECLARE_CALLBACK( void, onSelect, ( S32 itemOrObjectId ) );
+      DECLARE_CALLBACK( void, onInspect, ( S32 itemOrObjectId ) );
+      DECLARE_CALLBACK( void, onRemoveSelection, ( S32 itemOrObjectId ) );
+      DECLARE_CALLBACK( void, onUnselect, ( S32 itemOrObjectId ) );
+      DECLARE_CALLBACK( void, onDeleteSelection, () );
+      DECLARE_CALLBACK( void, onObjectDeleteCompleted, () );
+      DECLARE_CALLBACK( void, onKeyDown, ( S32 modifier, S32 keyCode ) );
+      DECLARE_CALLBACK( void, onMouseUp, ( S32 hitItemId, S32 mouseClickCount ) );
+      DECLARE_CALLBACK( void, onMouseDragged, () );
+      DECLARE_CALLBACK( void, onRightMouseDown, ( S32 itemId, const Point2I& mousePos, SimObject* object = NULL ) );
+      DECLARE_CALLBACK( void, onRightMouseUp, ( S32 itemId, const Point2I& mousePos, SimObject* object = NULL ) );
+      DECLARE_CALLBACK( void, onBeginReparenting, () );
+      DECLARE_CALLBACK( void, onEndReparenting, () );
+      DECLARE_CALLBACK( void, onReparent, ( S32 itemOrObjectId, S32 oldParentItemOrObjectId, S32 newParentItemOrObjectId ) );
+      DECLARE_CALLBACK( void, onDragDropped, () );
+      DECLARE_CALLBACK( void, onAddMultipleSelectionBegin, () );
+      DECLARE_CALLBACK( void, onAddMultipleSelectionEnd, () );
+      DECLARE_CALLBACK( bool, canRenameObject, ( SimObject* object ) );
+      DECLARE_CALLBACK( bool, handleRenameObject, ( const char* newName, SimObject* object ) );
+      DECLARE_CALLBACK( void, onClearSelection, () );
+
+      /// @}
+
+      ///
+      Vector<Item*> mItems;
+      Vector<Item*> mVisibleItems;
+      Vector<Item*> mSelectedItems;
+
+      /// Used for tracking stuff that was selected, but may not have been
+      /// created at time of selection.
+      Vector<S32> mSelected;
+
+      S32 mItemCount;
+
+      /// We do our own free list, as we we want to be able to recycle
+      /// item ids and do some other clever things.
+      Item* mItemFreeList;
+
+      Item* mRoot;
+      S32 mMaxWidth;
+      S32 mSelectedItem;
+      S32 mDraggedToItem;
+      S32 mStart;      
+
+      /// A combination of TreeState flags.
+      BitSet32 mFlags;
+
+      Item* mPossibleRenameItem;
+      Item* mRenamingItem;
+		Item* mTempItem;
+      GuiTextEditCtrl* mRenameCtrl;
+
+      /// Current filter that determines which items in the tree are displayed and which are hidden.
+      String mFilterText;
+
+      /// If true, a trace of actions taken by the control is logged to the console.  Can
+      /// be turned on with the setDebug() script method.
+      bool mDebug;
+
+      GFXTexHandle mIconTable[MaxIcons];
+
+      S32 mTabSize;
+      S32 mTextOffset;
+      bool mFullRowSelect;
+      S32 mItemHeight;
+      bool mDestroyOnSleep;
+      bool mSupportMouseDragging;
+      bool mMultipleSelections;
+      bool mDeleteObjectAllowed;
+      bool mDragToItemAllowed;
+      bool mClearAllOnSingleSelection;   ///< When clicking on an already selected item, clear all other selections
+      bool mCompareToObjectID;
+      
+      /// Used to hide the root tree element, defaults to true.
+      bool mShowRoot;
+      
+      /// If true, object IDs will be included in inspector tree item labels.
+      bool mShowObjectIds;
+      
+      /// If true, class names will be included in inspector tree item labels.
+      bool mShowClassNames;
+      
+      /// If true, object names will be included in inspector tree item labels.
+      bool mShowObjectNames;
+      
+      /// If true, internal names will be included in inspector tree item labels.
+      bool mShowInternalNames;
+
+      /// If true, class names will be used as object names for unnamed objects.
+      bool mShowClassNameForUnnamedObjects;
+
+      /// If true then tooltips will be automatically
+      /// generated for all Inspector items
+      bool mUseInspectorTooltips;
+
+      /// If true then only render item tooltips if the item
+      /// extends past the displayable width
+      bool mTooltipOnWidthOnly;
+
+      /// If true clicking on a selected item ( that is an object )
+      /// will allow you to rename it.
+      bool mCanRenameObjects;
+      
+      /// If true then object renaming operates on the internalName rather than
+      /// the object name.
+      bool mRenameInternal;
+      
+      S32 mCurrentDragCell;
+      S32 mPreviousDragCell;
+      S32 mDragMidPoint;
+      bool mMouseDragged;
+      bool mDragStartInSelection;
+      Point2I mMouseDownPoint;
+
+      StringTableEntry mBitmapBase;
+      GFXTexHandle mTexRollover;
+      GFXTexHandle mTexSelected;
+
+      ColorI mAltFontColor;
+      ColorI mAltFontColorHL;
+      ColorI mAltFontColorSE;
+
+      SimObjectPtr<SimObject> mRootObject;
+
+      void _destroyChildren( Item* item, Item* parent, bool deleteObjects=true);
+      void _destroyItem( Item* item, bool deleteObject=true);
+      void _destroyTree();
+
+      void _deleteItem(Item* item);
+
+      void _buildItem(Item* item, U32 tabLevel, bool bForceFullUpdate = false);
+
+      Item* _findItemByAmbiguousId( S32 itemOrObjectId, bool buildVirtual = true );
+
+      void _expandObjectHierarchy( SimGroup* group );
+
+      bool _hitTest(const Point2I & pnt, Item* & item, BitSet32 & flags);
+
+      S32 getInspectorItemIconsWidth(Item* & item);
+
+      virtual bool onVirtualParentBuild(Item *item, bool bForceFullUpdate = false);
+      virtual bool onVirtualParentExpand(Item *item);
+      virtual bool onVirtualParentCollapse(Item *item);
+      virtual void onItemSelected( Item *item );
+      virtual void onRemoveSelection( Item *item );
+      virtual void onClearSelection() {};
+
+      Item* addInspectorDataItem(Item *parent, SimObject *obj);
+      
+      virtual bool isValidDragTarget( Item* item );
+      
+      bool _isRootLevelItem( Item* item ) const
+      {
+         return ( item == mRoot && mShowRoot ) || ( item->mParent == mRoot && !mShowRoot );
+      }
+
+      /// For inspector tree views, this is hooked to the SetModificationSignal of sets
+      /// so that the tree view knows when it needs to refresh.
+      void _onInspectorSetObjectModified( SetModification modification, SimSet* set, SimObject* object );
+
+   public:
+      GuiTreeViewCtrl();
+      virtual ~GuiTreeViewCtrl();
+
+      /// Used for syncing the mSelected and mSelectedItems lists.
+      void syncSelection();
+
+      void lockSelection(bool lock);
+      void hideSelection(bool hide);
+      void toggleLockSelection();
+      void toggleHideSelection();
+      virtual bool canAddSelection( Item *item ) { return true; };
+      void addSelection(S32 itemId, bool update = true, bool isLastSelection = true);
+      const Vector< Item* >& getSelectedItems() const { return mSelectedItems; }
+      const Vector< S32 >& getSelected() const { return mSelected; }
+
+      bool isSelected(S32 itemId)
+      {
+         return isSelected( getItem( itemId ) );
+      }
+      bool isSelected(Item *item)
+      {
+         if ( !item )
+            return false;
+         return mSelectedItems.contains( item );   
+      }
+
+      void setDebug( bool value ) { mDebug = value; }
+
+      /// Should use addSelection and removeSelection when calling from script
+      /// instead of setItemSelected. Use setItemSelected when you want to select
+      /// something in the treeview as it has script call backs.
+      void removeSelection(S32 itemId);
+
+      /// Sets the flag of the item with the matching itemId.
+      bool setItemSelected(S32 itemId, bool select);
+      bool setItemExpanded(S32 itemId, bool expand);
+      bool setItemValue(S32 itemId, StringTableEntry Value);
+
+      const char * getItemText(S32 itemId);
+      const char * getItemValue(S32 itemId);
+      StringTableEntry getTextToRoot(S32 itemId, const char *delimiter = "");
+
+      Item* getRootItem() const { return mRoot; }
+      Item * getItem(S32 itemId) const;
+      Item * createItem(S32 icon);
+      bool editItem( S32 itemId, const char* newText, const char* newValue );
+
+      bool markItem( S32 itemId, bool mark );
+      
+      bool isItemSelected( S32 itemId );
+
+      // insertion/removal
+      void unlinkItem(Item * item);
+      S32 insertItem(S32 parentId, const char * text, const char * value = "", const char * iconString = "", S16 normalImage = 0, S16 expandedImage = 1);
+      bool removeItem(S32 itemId, bool deleteObjects=true);
+      void removeAllChildren(S32 itemId); // Remove all children of the given item
+
+      bool buildIconTable(const char * icons);
+
+      bool setAddGroup(SimObject * obj);
+
+      S32 getIcon(const char * iconString);
+
+      // tree items
+      const S32 getFirstRootItem() const;
+      S32 getChildItem(S32 itemId);
+      S32 getParentItem(S32 itemId);
+      S32 getNextSiblingItem(S32 itemId);
+      S32 getPrevSiblingItem(S32 itemId);
+      S32 getItemCount();
+      S32 getSelectedItem();
+      S32 getSelectedItem(S32 index); // Given an item's index in the selection list, return its itemId
+      S32 getSelectedItemsCount() {return mSelectedItems.size();} // Returns the number of selected items
+      void moveItemUp( S32 itemId );
+      void moveItemDown( S32 itemId );
+
+      // misc.
+      bool scrollVisible( Item *item );
+      bool scrollVisible( S32 itemId );
+      bool scrollVisibleByObjectId( S32 objID );
+      
+      void deleteSelection();
+      void clearSelection();
+
+      S32 findItemByName(const char *name);
+      S32 findItemByValue(const char *name);
+      S32 findItemByObjectId(S32 iObjId);
+
+      void sortTree( bool caseSensitive, bool traverseHierarchy, bool parentsFirst );
+
+      /// @name Filtering
+      /// @{
+
+      /// Get the current filter expression.  Only tree items whose text matches this expression
+      /// are displayed.  By default, the expression is empty and all items are shown.
+      const String& getFilterText() const { return mFilterText; }
+
+      /// Set the pattern by which to filter items in the tree.  Only items in the tree whose text
+      /// matches this pattern are displayed.
+      void setFilterText( const String& text );
+
+      /// Clear the current item filtering pattern.
+      void clearFilterText() { setFilterText( String::EmptyString ); }
+
+      /// @}
+
+      // GuiControl
+      bool onAdd();
+      bool onWake();
+      void onSleep();
+      void onPreRender();
+      bool onKeyDown( const GuiEvent &event );
+		void onMouseDown(const GuiEvent &event);
+      void onMiddleMouseDown(const GuiEvent &event);
+      void onMouseMove(const GuiEvent &event);
+      void onMouseEnter(const GuiEvent &event);
+      void onMouseLeave(const GuiEvent &event);
+      void onRightMouseDown(const GuiEvent &event);
+      void onRightMouseUp(const GuiEvent &event);
+      void onMouseDragged(const GuiEvent &event);
+      virtual void onMouseUp(const GuiEvent &event);
+
+      /// Returns false if the object is a child of one of the inner items.
+      bool childSearch(Item * item, SimObject *obj, bool yourBaby);
+
+      /// Find immediately available inspector items (eg ones that aren't children of other inspector items)
+      /// and then update their sets
+      void inspectorSearch(Item * item, Item * parent, SimSet * parentSet, SimSet * newParentSet);
+
+		/// Find the Item associated with a sceneObject, returns true if it found one
+		bool objectSearch( const SimObject *object, Item **item );
+
+      // GuiArrayCtrl
+      void onRenderCell(Point2I offset, Point2I cell, bool, bool);
+      void onRender(Point2I offset, const RectI &updateRect);
+      
+      bool renderTooltip( const Point2I &hoverPos, const Point2I& cursorPos, const char* tipText );
+
+      static void initPersistFields();
+
+      void inspectObject(SimObject * obj, bool okToEdit);
+      void buildVisibleTree(bool bForceFullUpdate = false);
+
+      void cancelRename();
+      void onRenameValidate();
+      void showItemRenameCtrl( Item* item );
+
+      DECLARE_CONOBJECT(GuiTreeViewCtrl);
+      DECLARE_CATEGORY( "Gui Lists" );
+      DECLARE_DESCRIPTION( "Hierarchical list of text items with optional icons.\nCan also be used to inspect SimObject hierarchies." );
+};
+
+#endif