guiAutoScrollCtrl.cpp

Public Functions

ConsoleDocClass(GuiAutoScrollCtrl , "@brief A container that scrolls its child <a href="/coding/file/guieditctrl_8cpp/#guieditctrl_8cpp_1abb04e3738c4c5a96b3ade6fa47013a6c">control</a> up over <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">time.\n\n</a>" "This container can be used <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> scroll <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> single child <a href="/coding/file/guieditctrl_8cpp/#guieditctrl_8cpp_1abb04e3738c4c5a96b3ade6fa47013a6c">control</a> in either of the four <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">directions.\n\n</a>" "@<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">tsexample\n</a>" "// Create <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/class/classguiautoscrollctrl/">GuiAutoScrollCtrl</a> that scrolls <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> long text of <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">credits.\n</a>" "<a href="/coding/file/tmm__on_8h/#tmm__on_8h_1a1ac41480eb2e4aadd52252ee550b630a">new</a> <a href="/coding/class/classguiautoscrollctrl/">GuiAutoScrollCtrl</a>( CreditsScroller )\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "{\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "   position = \"0 0\";\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "   extent = Canvas.extent.x SPC Canvas.extent.y;\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "   scrollDirection = \"Up\"; // Scroll <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">upwards.\n</a>" "   startDelay = 4; // Wait 4 seconds before starting <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">scroll.\n</a>" "   isLooping = false; // Don'<a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1aded116371789db1fd63c90ef00c95a3d">t</a> loop the <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">credits.\n</a>" "   scrollOutOfSight = true; // Scroll up <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">fully.\n</a>" "\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "   <a href="/coding/file/tmm__on_8h/#tmm__on_8h_1a1ac41480eb2e4aadd52252ee550b630a">new</a> <a href="/coding/class/classguimltextctrl/">GuiMLTextCtrl</a>()\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "   {\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "      text = $CREDITS;\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "   };\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "};\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "function CreditsScroller::onComplete( %this )\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "{\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "   // Switch back <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> <a href="/coding/file/x86unixmain_8cpp/#x86unixmain_8cpp_1a217dbf8b442f20279ea00b898af96f52">main</a> menu after credits have <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">rolled.\n</a>" "   Canvas.setContent( MainMenu );\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "}\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "// Start rolling <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">credits.\n</a>" "Canvas.setContent( CreditsScroller );\<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">n</a>" "@<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">endtsexample\n\n</a>" "@note Only the first child will be <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">scrolled.\n\n</a>" "@ingroup GuiContainers" )

DefineEngineMethod(GuiAutoScrollCtrl , reset , void , () , "Reset scrolling." )

IMPLEMENT_CALLBACK(GuiAutoScrollCtrl , onComplete , void , () , () , "Called when the child <a href="/coding/file/guieditctrl_8cpp/#guieditctrl_8cpp_1abb04e3738c4c5a96b3ade6fa47013a6c">control</a> has been scrolled in entirety." )

IMPLEMENT_CALLBACK(GuiAutoScrollCtrl , onReset , void , () , () , "Called when the child <a href="/coding/file/guieditctrl_8cpp/#guieditctrl_8cpp_1abb04e3738c4c5a96b3ade6fa47013a6c">control</a> is reset <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> its initial position and the cycle starts again." )

IMPLEMENT_CALLBACK(GuiAutoScrollCtrl , onStart , void , () , () , "Called when the <a href="/coding/file/guieditctrl_8cpp/#guieditctrl_8cpp_1abb04e3738c4c5a96b3ade6fa47013a6c">control</a> starts <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> scroll." )

IMPLEMENT_CALLBACK(GuiAutoScrollCtrl , onTick , void , () , () , "Called every 32ms on the control." )

IMPLEMENT_CONOBJECT(GuiAutoScrollCtrl )

ImplementEnumType(GuiAutoScrollDirection , "Direction in which <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> scroll the child <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">control.\n\n</a>" "@ingroup GuiContainers" )

  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#include "gui/containers/guiAutoScrollCtrl.h"
 25#include "console/consoleTypes.h"
 26#include "console/engineAPI.h"
 27
 28
 29IMPLEMENT_CONOBJECT( GuiAutoScrollCtrl );
 30
 31ConsoleDocClass( GuiAutoScrollCtrl,
 32   "@brief A container that scrolls its child control up over time.\n\n"
 33   
 34   "This container can be used to scroll a single child control in either of the four directions.\n\n"
 35   
 36   "@tsexample\n"
 37   "// Create a GuiAutoScrollCtrl that scrolls a long text of credits.\n"
 38   "new GuiAutoScrollCtrl( CreditsScroller )\n"
 39   "{\n"
 40   "   position = \"0 0\";\n"
 41   "   extent = Canvas.extent.x SPC Canvas.extent.y;\n"
 42   "\n"
 43   "   scrollDirection = \"Up\"; // Scroll upwards.\n"
 44   "   startDelay = 4; // Wait 4 seconds before starting to scroll.\n"
 45   "   isLooping = false; // Don't loop the credits.\n"
 46   "   scrollOutOfSight = true; // Scroll up fully.\n"
 47   "\n"
 48   "   new GuiMLTextCtrl()\n"
 49   "   {\n"
 50   "      text = $CREDITS;\n"
 51   "   };\n"
 52   "};\n"
 53   "\n"
 54   "function CreditsScroller::onComplete( %this )\n"
 55   "{\n"
 56   "   // Switch back to main menu after credits have rolled.\n"
 57   "   Canvas.setContent( MainMenu );\n"
 58   "}\n"
 59   "\n"
 60   "// Start rolling credits.\n"
 61   "Canvas.setContent( CreditsScroller );\n"
 62   "@endtsexample\n\n"
 63   
 64   "@note Only the first child will be scrolled.\n\n"
 65   
 66   "@ingroup GuiContainers"
 67);
 68
 69
 70IMPLEMENT_CALLBACK( GuiAutoScrollCtrl, onTick, void, (), (),
 71   "Called every 32ms on the control." );
 72IMPLEMENT_CALLBACK( GuiAutoScrollCtrl, onStart, void, (), (),
 73   "Called when the control starts to scroll." );
 74IMPLEMENT_CALLBACK( GuiAutoScrollCtrl, onComplete, void, (), (),
 75   "Called when the child control has been scrolled in entirety." );
 76IMPLEMENT_CALLBACK( GuiAutoScrollCtrl, onReset, void, (), (),
 77   "Called when the child control is reset to its initial position and the cycle starts again." );
 78
 79
 80ImplementEnumType( GuiAutoScrollDirection,
 81   "Direction in which to scroll the child control.\n\n"
 82   "@ingroup GuiContainers" )
 83   { GuiAutoScrollCtrl::Up, "Up", "Scroll from bottom towards top." },
 84   { GuiAutoScrollCtrl::Down, "Down", "Scroll from top towards bottom." },
 85   { GuiAutoScrollCtrl::Left, "Left", "Scroll from right towards left." },
 86   { GuiAutoScrollCtrl::Right, "Right", "Scroll from left towards right." },
 87EndImplementEnumType;
 88
 89//-----------------------------------------------------------------------------
 90
 91GuiAutoScrollCtrl::GuiAutoScrollCtrl()
 92   : mDirection( Up ),
 93     mIsLooping( true ),
 94     mCurrentPhase( GuiAutoScrollCtrl::PhaseComplete ),
 95     mCurrentTime( 0.f ),
 96     mCompleteTime(F32_MAX),
 97     mCurrentPosition(0.0f),
 98     mStartDelay( 3.f ),
 99     mResetDelay( 5.f ),
100     mChildBorder( 10 ),
101     mScrollOutOfSight( false ),
102     mScrollSpeed( 1.f )
103{
104   mIsContainer = true;
105}
106
107//-----------------------------------------------------------------------------
108
109void GuiAutoScrollCtrl::initPersistFields()
110{
111   addGroup( "Scrolling" );
112   
113      addField( "scrollDirection", TYPEID< Direction >(), Offset( mDirection, GuiAutoScrollCtrl ),
114         "Direction in which the child control is moved." );
115      addField( "startDelay", TypeF32, Offset( mStartDelay, GuiAutoScrollCtrl ),
116         "Seconds to wait before starting to scroll." );
117      addField( "resetDelay", TypeF32, Offset( mResetDelay, GuiAutoScrollCtrl ),
118         "Seconds to wait after scrolling completes before resetting and starting over.\n\n"
119         "@note Only takes effect if #isLooping is true." );
120      addField( "childBorder", TypeS32, Offset( mChildBorder, GuiAutoScrollCtrl ),
121         "Padding to put around child control (in pixels)." );
122      addField( "scrollSpeed", TypeF32, Offset( mScrollSpeed, GuiAutoScrollCtrl ),
123         "Scrolling speed in pixels per second." );
124      addField( "isLooping", TypeBool, Offset( mIsLooping, GuiAutoScrollCtrl ),
125         "If true, the scrolling will reset to the beginning once completing a cycle." );
126      addField( "scrollOutOfSight", TypeBool, Offset( mScrollOutOfSight, GuiAutoScrollCtrl ),
127         "If true, the child control will be completely scrolled out of sight; otherwise it will only scroll "
128         "until the other end becomes visible." );
129         
130   endGroup( "Scrolling" );
131
132   Parent::initPersistFields();
133}
134
135//-----------------------------------------------------------------------------
136
137bool GuiAutoScrollCtrl::onWake()
138{
139   if( !Parent::onWake() )
140      return false;
141      
142   setProcessTicks( true );
143   return true;
144}
145
146//-----------------------------------------------------------------------------
147
148void GuiAutoScrollCtrl::onSleep()
149{
150   setProcessTicks( false );
151   Parent::onSleep();
152}
153
154//-----------------------------------------------------------------------------
155
156void GuiAutoScrollCtrl::onChildAdded( GuiControl* control )
157{
158   _reset( control );
159   Parent::onChildAdded( control );
160}
161
162//-----------------------------------------------------------------------------
163
164void GuiAutoScrollCtrl::onChildRemoved( GuiControl* control )
165{
166   mCurrentPhase = PhaseComplete;
167   Parent::onChildRemoved( control );
168}
169
170//-----------------------------------------------------------------------------
171
172bool GuiAutoScrollCtrl::_isScrollComplete() const
173{
174   if( empty() )
175      return true;
176      
177   GuiControl* control = static_cast< GuiControl* >( at( 0 ) );
178   U32 axis = _getScrollAxis();
179   F32 amount = _getScrollAmount();
180   
181   if( mScrollOutOfSight )
182   {
183      // If scrolling out of sight, scrolling is complete when the control's rectangle
184      // does not intersect our own rectangle anymore.
185      
186      RectI thisRect( Point2I( 0, 0 ), getExtent() );
187      return !( thisRect.overlaps( control->getBounds() ) );
188   }
189   else
190   {
191      if( amount < 0 )
192         return ( control->getPosition()[ axis ] + control->getExtent()[ axis ] ) < ( getExtent()[ axis ] - mChildBorder );
193      else
194         return ( control->getPosition()[ axis ] >= mChildBorder );
195   }
196}
197
198//-----------------------------------------------------------------------------
199
200void GuiAutoScrollCtrl::_reset( GuiControl* control )
201{
202   U32 axis = _getScrollAxis();
203   U32 counterAxis = ( axis == 1 ? 0 : 1 );
204
205   Point2I newPosition( mChildBorder, mChildBorder );
206   Point2I newExtent = control->getExtent();
207   
208   // Fit control on axis that is not scrolled.
209   newExtent[ counterAxis ] = getExtent()[ counterAxis ] - mChildBorder * 2;
210   
211   // For the right and down scrolls, position the control away from the
212   // right/bottom edge of our control.
213   
214   if( mDirection == Right )
215      newPosition.x = - ( newExtent.x - getExtent().x + mChildBorder );
216   else if( mDirection == Down )
217      newPosition.y = - ( newExtent.y - getExtent().y + mChildBorder );
218      
219   // Set the child geometry.
220      
221   control->setPosition( newPosition );
222   control->setExtent( newExtent );   
223   
224   // Reset counters.
225
226   mCurrentTime = 0.0f;
227   mCurrentPhase = PhaseInitial;
228   mCurrentPosition = control->getPosition()[ axis ];
229}
230
231//-----------------------------------------------------------------------------
232
233void GuiAutoScrollCtrl::reset()
234{
235   if( !empty() )
236      _reset( static_cast< GuiControl* >( at( 0 ) ) );
237}
238
239//-----------------------------------------------------------------------------
240
241bool GuiAutoScrollCtrl::resize( const Point2I &newPosition, const Point2I &newExtent )
242{
243   if( !Parent::resize( newPosition, newExtent ) )
244      return false;
245
246   for( iterator i = begin(); i != end(); ++ i )
247   {
248      GuiControl* control = static_cast< GuiControl* >( *i );
249      if( control )
250         _reset( control );
251   }
252
253   return true;
254}
255
256//-----------------------------------------------------------------------------
257
258void GuiAutoScrollCtrl::childResized( GuiControl* child )
259{
260   Parent::childResized( child );
261   _reset(child);
262}
263
264//-----------------------------------------------------------------------------
265
266void GuiAutoScrollCtrl::processTick()
267{
268   onTick_callback();
269}
270
271//-----------------------------------------------------------------------------
272
273void GuiAutoScrollCtrl::advanceTime( F32 timeDelta )
274{
275   if( mCurrentPhase == PhaseComplete )
276      return;
277      
278   // Wait out initial delay.
279            
280   if( ( mCurrentTime + timeDelta ) < mStartDelay)
281   {
282      mCurrentTime += timeDelta;
283      return;
284   }
285   
286   // Start scrolling if we haven't already.
287   
288   if( mCurrentPhase == PhaseInitial )
289   {
290      onStart_callback();
291      mCurrentPhase = PhaseScrolling;
292   }
293
294   GuiControl* control = static_cast< GuiControl* >( at( 0 ) );
295   if( !control ) // Should not happen.
296      return;
297
298   // If not yet complete, scroll some more.
299   
300   if( !_isScrollComplete() )
301   {
302      U32 axis = _getScrollAxis();
303      F32 amount = _getScrollAmount();
304      
305      mCurrentPosition += amount * timeDelta;
306      Point2I newPosition = control->getPosition();
307      newPosition[ axis ] = mCurrentPosition;
308      
309      control->setPosition( newPosition );
310   }
311   else
312   {
313      mCurrentTime += timeDelta;
314      
315      if( mCurrentPhase != PhaseComplete && mCurrentPhase != PhaseWait )
316      {
317         if( mCurrentPhase != PhaseWait )
318         {
319            onComplete_callback();
320            mCurrentPhase = PhaseComplete;
321         }
322         
323         mCompleteTime = mCurrentTime;
324      }
325      
326      // Reset, if looping.
327      
328      if( mIsLooping )
329      {
330         // Wait out reset time and restart.
331         
332         mCurrentPhase = PhaseWait;
333         if( mCurrentTime > ( mCompleteTime + mResetDelay ) )
334         {
335            onReset_callback();
336            _reset( control );
337         }
338      }
339   }
340}
341
342//-----------------------------------------------------------------------------
343
344void GuiAutoScrollCtrl::inspectPostApply()
345{
346   Parent::inspectPostApply();
347   reset();
348}
349
350//=============================================================================
351//    API.
352//=============================================================================
353// MARK: ---- API ----
354
355//-----------------------------------------------------------------------------
356
357DefineEngineMethod( GuiAutoScrollCtrl, reset, void, (),,
358   "Reset scrolling." )
359{
360   object->reset();
361}
362