guiTabBookCtrl.h

Public Functions

DefineEnumType(GuiTabPosition )

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23#ifndef _GUI_TABBOOKCTRL_H_
 24#define _GUI_TABBOOKCTRL_H_
 25
 26#ifndef _GUICONTAINER_H_
 27   #include "gui/containers/guiContainer.h"
 28#endif
 29#ifndef _GUITABPAGECTRL_H_
 30   #include "gui/controls/guiTabPageCtrl.h"
 31#endif
 32
 33
 34/// Tab Book Control for creation of tabbed dialogs
 35///
 36/// @see GUI for an overview of the Torque GUI system.
 37///
 38/// @section GuiTabBookCtrl_Intro Introduction
 39///
 40/// GuiTabBookCtrl is a container class that holds children of type GuiTabPageCtrl
 41///
 42/// GuiTabBookCtrl creates an easy to work with system for creating tabbed dialogs
 43/// allowing for creation of dialogs that store a lot of information in a small area
 44/// by separating the information into pages which are changeable by clicking their
 45/// page title on top or bottom of the control
 46///
 47/// tabs may be aligned to be on top or bottom of the book and are changeable while
 48/// the GUI editor is open for quick switching between pages allowing multi-page dialogs
 49/// to be edited quickly and easily.
 50///
 51/// The control may only contain children of type GuiTabPageCtrl.
 52/// If a control is added to the Book that is not of type GuiTabPageCtrl, it will be
 53/// removed and relocated to the currently active page of the control.
 54/// If there is no active page in the book, the child control will be relocated to the
 55/// parent of the book.
 56///
 57/// @ref GUI has an overview of the GUI system.
 58///
 59/// @nosubgrouping
 60class GuiTabBookCtrl : public GuiContainer
 61{
 62   public:
 63   
 64      typedef GuiContainer Parent;
 65      
 66      enum TabPosition
 67      {
 68         AlignTop,   ///< Align the tabs on the top of the tab book control
 69         AlignBottom ///< Align the tabs on the bottom of the tab book control
 70      };
 71
 72      struct TabHeaderInfo
 73      {
 74         GuiTabPageCtrl *Page;
 75         S32             TextWidth;
 76         S32             TabRow;
 77         S32             TabColumn;
 78         RectI           TabRect;
 79      };
 80
 81   private:
 82
 83      static bool _setSelectedPage( void *object, const char *index, const char *data );
 84
 85   protected:
 86
 87      RectI                   mPageRect;        ///< Rectangle of the tab page portion of the control
 88      RectI                   mTabRect;         ///< Rectangle of the tab portion of the control
 89      Vector<TabHeaderInfo>   mPages;           ///< Vector of pages contained by the control
 90      GuiTabPageCtrl*         mActivePage;      ///< Pointer to the active (selected) tab page child control
 91      GuiTabPageCtrl*         mHoverTab;        ///< Pointer to the tab page that currently has the mouse positioned ontop of its tab
 92      S32                     mMinTabWidth;     ///< Minimum Width a tab will display as.
 93      TabPosition             mTabPosition;     ///< Current tab position (see alignment)
 94      S32                     mTabHeight;       ///< Current tab height
 95      S32                     mTabMargin;       ///< Margin left/right of tab text in tab
 96      S32                     mSelectedPageNum; ///< Current selected tab position
 97      S32                     mDefaultPageNum;  ///< Page to select on first wake.
 98      bool                    mAllowReorder;    ///< Allow the user to reorder tabs by dragging them
 99      S32                     mFrontTabPadding; ///< Padding to the Left of the first Tab
100      bool                    mDraggingTab;
101      bool                    mDraggingTabRect;
102      bool                    mIsFirstWake;
103
104      enum
105      {
106         TabSelected = 0,     ///< Index of selected tab texture
107         TabNormal,           ///< Index of normal tab texture
108         TabHover,            ///< Index of hover tab texture
109         TabEnds,             ///< Index of end lines for horizontal tabs
110         NumBitmaps           ///< Number of bitmaps in this array
111      };
112      
113      bool  mHasTexture;   ///< Indicates whether we have a texture to render the tabs with
114      RectI *mBitmapBounds;///< Array of rectangles identifying textures for tab book
115      
116      /// @name Callbacks
117      /// @{
118      
119      DECLARE_CALLBACK( void, onTabSelected, ( const String& text, U32 index ) );
120      DECLARE_CALLBACK( void, onTabRightClick, ( const String& text, U32 index ) );
121      
122      /// @}
123      
124   public:
125
126      GuiTabBookCtrl();
127      
128      DECLARE_CONOBJECT(GuiTabBookCtrl);
129      DECLARE_DESCRIPTION( "A control that allows to select from a set of tabbed pages." );
130
131      static void initPersistFields();
132
133      /// @name Control Events
134      /// @{
135       
136      bool onWake();
137      void onRender( Point2I offset, const RectI &updateRect );
138      
139      /// @}
140
141      /// @name Child events
142      /// @{
143      
144      void onChildRemoved( GuiControl* child );
145      void onChildAdded( GuiControl *child );
146      bool reOrder(SimObject* obj, SimObject* target);
147      bool acceptsAsChild( SimObject* object ) const;
148      
149      /// @}
150
151      /// @name Rendering methods
152      /// @{
153
154      /// Tab rendering routine, iterates through all tabs rendering one at a time
155      /// @param   offset   the render offset to accomodate global coords
156      /// @param   tabRect  the Rectangle in which these tabs are to be rendered
157      void renderTabs( const Point2I &offset, const RectI &tabRect );
158
159      /// Tab rendering subroutine, renders one tab with specified options
160      /// @param   tabRect   the rectangle to render the tab into
161      /// @param   tab   pointer to the tab page control for which to render the tab
162      void renderTab(const RectI& tabRect, GuiTabPageCtrl* tab);
163
164      /// @}
165
166      /// @name Page Management
167      /// @{
168
169      /// Create a new tab page child in the book
170      ///
171      /// Pages created are not titled and appear with no text on their tab when created.
172      /// This may change in the future.
173      ///
174      /// @param text Tab page header text.
175      void addNewPage( const char* text = NULL );
176
177      /// Select a tab page based on an index
178      /// @param   index   The index in the list that specifies which page to select
179      void selectPage( S32 index );
180
181      /// Select a tab page by a pointer to that page
182      /// @param   page   A pointer to the GuiTabPageCtrl to select.  This page must be a child of the tab book.
183      void selectPage( GuiTabPageCtrl *page );
184
185      /// Get the current selected tab number
186      S32 getSelectedPageNum(){ return mSelectedPageNum; };
187
188      /// Select the Next page in the tab book
189      void selectNextPage();
190
191      /// Select the Previous page in the tab book
192      void selectPrevPage();
193      
194      /// Make the page fill the entire page space.
195      void fitPage( GuiTabPageCtrl* page );
196      
197      /// Return the index for the given page.  -1 if not a page in this book.
198      S32 getPageNum( GuiTabPageCtrl* page ) const;
199
200      /// @}
201
202      /// @name Internal Utility Functions
203      /// @{
204
205      /// Update ourselves by hooking common GuiControl functionality.
206      void setUpdate();
207
208      /// Balance a top/bottom tab row
209      void balanceRow( S32 row, S32 totalTabWidth );
210
211      /// Balance a left/right tab column
212      void balanceColumn( S32 row, S32 totalTabWidth );
213
214      /// Calculate the tab width of a page, given it's caption
215      S32 calculatePageTabWidth( GuiTabPageCtrl *page );
216
217      /// Calculate Page Header Information
218      void calculatePageTabs();
219
220      /// Get client area of tab book
221      virtual const RectI getClientRect();
222
223      /// Find the tab that was hit by the current event, if any
224      /// @param   event   The GuiEvent that caused this function call
225      GuiTabPageCtrl *findHitTab( const GuiEvent &event );
226
227      /// Find the tab that was hit, based on a point
228      /// @param    hitPoint   A Point2I that specifies where to search for a tab hit
229      GuiTabPageCtrl *findHitTab( Point2I hitPoint );
230
231      /// @}
232
233      /// @name Sizing
234      /// @{
235
236      /// Rezize our control
237      /// This method is overridden so that we may handle resizing of our child tab
238      /// pages when we are resized.
239      /// This ensures we keep our sizing in sync when we are moved or sized.
240      ///
241      /// @param   newPosition   The new position of the control
242      /// @param   newExtent   The new extent of the control
243      bool resize(const Point2I &newPosition, const Point2I &newExtent);
244
245      /// Called when a child page is resized
246      /// This method is overridden so that we may handle resizing of our child tab
247      /// pages when one of them is resized.
248      /// This ensures we keep our sizing in sync when we our children are sized or moved.
249      ///
250      /// @param   child   A pointer to the child control that has been resized
251      void childResized(GuiControl *child);
252
253      /// @}
254
255      virtual bool onKeyDown(const GuiEvent &event);
256
257
258      /// @name Mouse Events
259      /// @{
260      
261      virtual void onMouseDown( const GuiEvent &event );
262      virtual void onMouseUp( const GuiEvent &event );
263      virtual void onMouseDragged( const GuiEvent &event );
264      virtual void onMouseMove( const GuiEvent &event );
265      virtual void onMouseLeave( const GuiEvent &event );
266      virtual bool onMouseDownEditor( const GuiEvent &event, Point2I offset );
267      virtual void onRightMouseUp( const GuiEvent& event );
268      
269      /// @}
270};
271
272typedef GuiTabBookCtrl::TabPosition GuiTabPosition;
273DefineEnumType( GuiTabPosition );
274
275#endif //_GUI_TABBOOKCTRL_H_
276