guiScrollCtrl.h

Public Functions

DefineEnumType(GuiScrollBarBehavior )

  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
 24#ifndef _GUISCROLLCTRL_H_
 25#define _GUISCROLLCTRL_H_
 26
 27#ifndef _GUICONTAINER_H_
 28   #include "gui/containers/guiContainer.h"
 29#endif
 30
 31
 32/// A control providing a window inside a larger client area which can be
 33/// scrolled using scrollbars.
 34///
 35class GuiScrollCtrl : public GuiContainer
 36{
 37   public:
 38
 39      typedef GuiContainer Parent;
 40
 41      enum Region
 42      {
 43         UpArrow,
 44         DownArrow,
 45         LeftArrow,
 46         RightArrow,
 47         UpPage,
 48         DownPage,
 49         LeftPage,
 50         RightPage,
 51         VertThumb,
 52         HorizThumb,
 53         None
 54      };
 55      
 56      enum ScrollBarBehavior
 57      {
 58         ScrollBarAlwaysOn = 0,
 59         ScrollBarAlwaysOff = 1,
 60         ScrollBarDynamic = 2
 61      };
 62
 63   protected:
 64
 65      // the scroll control uses a bitmap array to draw all its
 66      // graphics... these are the bitmaps it needs:
 67      enum BitmapIndices
 68      {
 69         BmpUp,
 70         BmpDown,
 71         BmpVThumbTopCap,
 72         BmpVThumb,
 73         BmpVThumbBottomCap,
 74         BmpVPage,
 75         BmpLeft,
 76         BmpRight,
 77         BmpHThumbLeftCap,
 78         BmpHThumb,
 79         BmpHThumbRightCap,
 80         BmpHPage,
 81         BmpResize,
 82
 83         BmpCount
 84      };
 85
 86      enum BitmapStates
 87      {
 88         BmpDefault = 0,
 89         BmpHilite,
 90         BmpDisabled,
 91
 92         BmpStates
 93      };
 94      
 95      RectI *mBitmapBounds;  //bmp is [3*n], bmpHL is [3*n + 1], bmpNA is [3*n + 2]
 96      GFXTexHandle mTextureObject;
 97
 98      S32     mBorderThickness;           // this gets set per class in the constructor
 99      Point2I mChildMargin;               // the thickness of the margin around the child controls
100
101      // note - it is implicit in the scroll view that the buttons all have the same
102      // arrow length and that horizontal and vertical scroll bars have the
103      // same thickness
104
105      S32 mScrollBarThickness;        // determined by the width of the vertical page bmp
106      S32 mScrollBarArrowBtnLength;   // determined by the height of the up arrow
107      S32 mScrollBarDragTolerance;    // maximal distance from scrollbar at which a scrollbar drag is still valid
108
109      bool mHBarEnabled;
110      bool mVBarEnabled;
111      bool mHasHScrollBar;
112      bool mHasVScrollBar;
113
114      Point2I mContentPos;  // the position of the content region in the control's coord system
115      Point2I mContentExt;  // the extent of the content region
116
117      Point2I mChildPos;   // the position of the upper left corner of the child control(s)
118      Point2I mChildExt;
119
120      Point2I mChildRelPos; // the relative position of the upper left content corner in
121                            // the child's coordinate system - 0,0 if scrolled all the way to upper left.
122
123      //--------------------------------------
124      // for mouse dragging the thumb
125      Point2I mChildRelPosAnchor; // the original childRelPos when scrolling started
126      S32 mThumbMouseDelta;
127
128      S32 mLastUpdated;
129
130      S32 mHThumbSize;
131      S32 mHThumbPos;
132
133      S32 mVThumbSize;
134      S32 mVThumbPos;
135
136      S32 mBaseThumbSize;
137
138      RectI mUpArrowRect;
139      RectI mDownArrowRect;
140      RectI mLeftArrowRect;
141      RectI mRightArrowRect;
142      RectI mHTrackRect;
143      RectI mVTrackRect;
144
145      //--------------------------------------
146      // for determining hit area
147
148      bool mStateDepressed; ///< Is the mouse currently depressed on a scroll region
149      Region mHitRegion;    ///< Which region is hit by the mouse
150
151      S32 mForceHScrollBar; ///< Force showing the Horizontal scrollbar
152      S32 mForceVScrollBar; ///< Force showing the Vertical scrollbar
153      bool mLockHorizScroll; ///< Is horizontal scrolling disabled
154      bool mLockVertScroll; ///< Is vertical scrolling disabled
155
156      bool mUseConstantHeightThumb;
157      bool mWillFirstRespond;     // for automatically handling arrow keys
158
159      /// Used internally to prevent infinite recursion.
160      bool mIgnoreChildResized;   
161
162      /// MouseWheel scroll animation
163      /// @{
164
165      /// Is currently performing a scroll animation.
166      bool mAnimating; 
167
168      /// Pixels moved per tick when performing a scroll animation.
169      S32 mScrollAnimSpeed; 
170
171      /// The target position when performing a scroll animation.
172      Point2I mScrollTargetPos;
173
174      /// Platform time of the last call to onPreRender
175      S32 mLastPreRender;
176
177      /// @}
178      
179      /// @name Callbacks
180      /// @{
181      
182      DECLARE_CALLBACK( void, onScroll, () );
183      
184      /// @}
185
186      Region findHitRegion(const Point2I &);
187
188      virtual bool calcChildExtents();
189      virtual void calcScrollRects(void);
190      void calcThumbs();
191      void scrollByRegion(Region reg);
192      void scrollByMouseWheel( const GuiEvent &event );
193      
194      /// Tell the kids that the mouse moved (relatively)
195      void updateChildMousePos();
196      
197      ///
198      void _onMouseDown( const GuiEvent& event, bool lockMouse );
199
200   public:
201   
202      GuiScrollCtrl();
203                                 
204      void autoScroll(Region reg);
205
206      void scrollDeltaAnimate(S32 x, S32 y);
207      void scrollTo(S32 x, S32 y);
208      void scrollToObject(GuiControl *targetControl);
209      void scrollDelta(S32 x, S32 y);
210      void scrollRectVisible(RectI rect);
211
212      /// Is the given client space rect completely visible within the actual
213      /// visible area, or is some of it clipped.  Returns true if it is
214      /// completely visible.
215      bool isRectCompletelyVisible(const RectI& rect);
216      bool isPointVisible( const Point2I& point );
217
218      void computeSizes();
219
220      // you can change the bitmap array dynamically.
221      void loadBitmapArray();
222
223      void addObject(SimObject *obj);
224      bool resize(const Point2I &newPosition, const Point2I &newExtent);
225      void childResized(GuiControl *child);
226      Point2I getChildPos() { return mChildPos; }
227      Point2I getChildRelPos() { return mChildRelPos; };
228      Point2I getChildExtent() { return mChildExt; }
229      Point2I getContentExtent() { return mContentExt; }
230      Point2I getChildMargin() { return mChildMargin; } //  Added to aid in sizing calculations
231      S32 getBorderThickness(void) { return mBorderThickness; }
232      S32 scrollBarThickness() const                        { return(mScrollBarThickness); }
233      S32 scrollBarArrowBtnLength() const                   { return(mScrollBarArrowBtnLength); }
234      bool hasHScrollBar() const                            { return(mHasHScrollBar); }
235      bool hasVScrollBar() const                            { return(mHasVScrollBar); }
236      bool enabledHScrollBar() const                        { return(mHBarEnabled); }
237      bool enabledVScrollBar() const                        { return(mVBarEnabled); }
238
239      bool isScrolledToBottom() { return mChildPos.y + mChildExt.y <= mContentPos.y + mContentExt.y; }
240
241      bool wantsTabListMembership();
242      bool becomeFirstResponder();
243      bool loseFirstResponder();
244
245      Region getCurHitRegion(void) { return mHitRegion; }
246
247      // GuiControl
248      virtual bool onKeyDown(const GuiEvent &event);
249      virtual void onMouseDown(const GuiEvent &event);
250      virtual bool onMouseDownEditor( const GuiEvent& event, Point2I offset );
251      virtual void onMouseUp(const GuiEvent &event);
252      virtual void onMouseDragged(const GuiEvent &event);
253      virtual bool onMouseWheelUp(const GuiEvent &event);
254      virtual bool onMouseWheelDown(const GuiEvent &event);
255
256      virtual bool onWake();
257      virtual void onSleep();
258
259      virtual void onPreRender();
260      virtual void onRender(Point2I offset, const RectI &updateRect);
261      virtual void drawBorder(const Point2I &offset, bool isFirstResponder);
262      virtual void drawVScrollBar(const Point2I &offset);
263      virtual void drawHScrollBar(const Point2I &offset);
264      virtual void drawScrollCorner(const Point2I &offset);
265      virtual GuiControl* findHitControl(const Point2I &pt, S32 initialLayer = -1);
266
267      static void initPersistFields();
268
269      DECLARE_CONOBJECT(GuiScrollCtrl);
270      DECLARE_DESCRIPTION( "A container that allows to view a larger GUI control inside its smaller area "
271                           "by providing horizontal and/or vertical scroll bars." );
272};
273
274typedef GuiScrollCtrl::ScrollBarBehavior GuiScrollBarBehavior;
275DefineEnumType( GuiScrollBarBehavior );
276
277#endif //_GUI_SCROLL_CTRL_H
278