You.i Engine
CYIScrollController Class Reference

Detailed Description

CYIScrollController provides scrolling behaviour to views.

A scroll controller takes input from GestureStart(), GestureMove(), and GestureEnd() and provides a ScrollListener and OutOfRangeListener with information about the resulting scroll. CYIScrollController can be configured with a snap back range and with a max out of range using SetMagnetRules(). CYIScrollController can be configured to provide paginated scrolling and snap back using SetPageSize(). Users of the scroll controller should provide all gesture inputs and ranges in the same coordinate system that they expect as output in the ScrollListener and OutOfRangeListener.

#include <view/YiScrollController.h>

Inheritance diagram for CYIScrollController:

Classes

class  OutOfRangeListener
 Provides a means of being notified when a scroll controller is outside of the snap back range. More...
 
class  ScrollListener
 

Public Member Functions

 CYIScrollController ()
 
virtual ~CYIScrollController () override
 
void SetSnapBackDur (uint64_t snapBackDur)
 
uint64_t GetSnapBackDur () const
 
void SetFrictionCoeff (float frictionCoefficient)
 
void SetMaxVelocityCoeff (float maxVelocityCoefficient)
 
void SetScrollListener (ScrollListener *pListener)
 
void SetOutOfRangeListener (OutOfRangeListener *pListener)
 
void GetDataRange (float *pStart, float *pSize) const
 
void SetDataRange (float dataStart, float dataSize, bool animate=true)
 
void SetMagnetRules (bool snapBack, float snapBackStart, float snapBackEnd, float maxOutOfRangeStart, float maxOutOfRangeEnd)
 
void SetCarousel (bool carousel)
 
void MoveBy (float delta, float eventPos=0, bool allowOutOfRange=false, bool notifyListener=true, bool skipIfAnimation=false)
 
void MoveByAnimate (float delta, uint64_t dur, CYITimeInterpolator *pInterpolator=nullptr, bool allowOutOfRange=true)
 
void UpdateMoveByAnimateDelta (float delta)
 
void MoveToPercentage (float percentage, bool notifyListener=true)
 
void MoveToPercentageAnimate (float percentage, uint64_t dur, CYITimeInterpolator *pInterpolator=nullptr)
 
void StopScrolling ()
 
bool IsScrolling () const
 
float GetPctPos () const
 
int64_t GetCurrentVelocity () const
 
void GetCurrentWindowPos (float *pStart, float *pEnd) const
 
float GetDataStart () const
 
float GetScrollStartPos () const
 
void Reset ()
 
void SetPageSize (float pageSize, bool alwaysCenterOnPage=false, bool swipeToNextPage=false)
 
float GetPageSize () const
 
bool GetAlwaysCenterOnPage () const
 
int32_t GetCurPage () const
 
size_t GetPageCount () const
 
float CalculatePageOffset (int32_t page) const
 
float CalculateOffsetToNearestPage (float moveBy) const
 
float CalculateCenterOffset () const
 
virtual float CalculateSnapBackOffset () const
 
void GestureStart (float pos, uint64_t eventTimeMs)
 
void GestureMove (float pos, uint64_t eventTimeMs)
 
void GestureEnd (float pos, uint64_t eventTimeMs)
 
void SetDecelerationDuration (uint32_t durationMs)
 
virtual uint32_t GetDecelerationDuration () const
 
float GetScrollDelta () const
 
float GetCompletedScrollDelta () const
 
- Public Member Functions inherited from CYIAnimation::Listener
virtual ~Listener ()
 

Protected Member Functions

virtual bool AdjustMoveBy (float *pMoveBy, const float &dataEnd) const
 
virtual bool AdjustMoveByNoOutOfRange (float *pMoveBy) const
 
virtual bool AdjustMoveByNoOutOfRangeDuringDecelerate (float *pMoveBy, int32_t dir)
 
void AnimateMoveBy (float delta, uint64_t dur, bool canCancel, CYITimeInterpolator *pInterpolator=nullptr)
 
void Decelerate ()
 
void FinishMoveBy ()
 
bool SnapBack (bool animate=true)
 
virtual void OnAnimate (CYIAnimation *pAnim, float dataPosition) override
 
virtual void OnAnimationBegin (CYIAnimation *pAnim) override
 
virtual void OnAnimationEnd (CYIAnimation *pAnim) override
 
void StartScroll (bool alreadyScrolling)
 
void EndScroll ()
 
void AutoScroll ()
 
float GetDataEnd () const
 
bool IsOutOfRange (float offset=0.0f) const
 
float CalculateSnapBackOffset (float dataStart) const
 

Protected Attributes

float m_dataStart
 
float m_dataSize
 
float m_anticipatedDataStart
 
float m_anticipatedDataEnd
 
float m_scrollStartPos
 
bool m_isScrolling
 
int32_t m_outOfRangeDirection
 
bool m_alwaysCenterOnPage
 
bool m_swipeToNextPage
 
bool m_snapBack
 
float m_snapBackStart
 
float m_snapBackEnd
 
float m_maxOutOfRangeStart
 
float m_maxOutOfRangeEnd
 
float m_pageSize
 
bool m_carousel
 
uint64_t m_snapBackDur
 
float m_frictionCoeff
 
uint32_t m_decelerationDuration
 
bool m_gestureStarted
 
int32_t m_pageAtGestureStart
 
float m_gestureEndPos
 
std::unique_ptr< CYIAnimationm_pMoveByAnim
 
float m_moveByTarget
 
float m_moveByDone
 
bool m_moveByCanCancel
 
bool m_allowOutOfRangeOnAnimateMoveBy
 
ScrollListenerm_pScrollListener
 
OutOfRangeListenerm_pOutOfRangeListener
 
std::unique_ptr< CYIInputInterpreter > m_pGestureData
 

Constructor & Destructor Documentation

◆ CYIScrollController()

CYIScrollController::CYIScrollController ( )

◆ ~CYIScrollController()

virtual CYIScrollController::~CYIScrollController ( )
overridevirtual

Member Function Documentation

◆ AdjustMoveBy()

virtual bool CYIScrollController::AdjustMoveBy ( float *  pMoveBy,
const float &  dataEnd 
) const
protectedvirtual

Called by MoveBy() this method makes necessary adjustments to pMoveBy. If snap back has been configured in SetMagnetRules() the default implementation prevents the move from going outside the max out of range. dataEnd is the max out of range the scroll should go after the end of the data range.

See also
SetMagnetRules

◆ AdjustMoveByNoOutOfRange()

virtual bool CYIScrollController::AdjustMoveByNoOutOfRange ( float *  pMoveBy) const
protectedvirtual

Called by MoveBy(). This method makes necessary adjustments to pMoveBy. The default implementation adjusts the move so that it does not go beyond the snap back range if snap back has been configured in SetMagnetRules().

◆ AdjustMoveByNoOutOfRangeDuringDecelerate()

virtual bool CYIScrollController::AdjustMoveByNoOutOfRangeDuringDecelerate ( float *  pMoveBy,
int32_t  dir 
)
protectedvirtual

Called by Decelerate(). This method allows subclasses to snap to a different position when scrolling. The default implementation calls AdjustMoveByNoOutOfRange().

See also
AdjustMoveByNoOutOfRange

◆ AnimateMoveBy()

void CYIScrollController::AnimateMoveBy ( float  delta,
uint64_t  dur,
bool  canCancel,
CYITimeInterpolator pInterpolator = nullptr 
)
protected

Scroll by delta over dur milliseconds using interpolator pInterpolator. If pInterpolator is null a QuadEaseOut interpolator will be used. If canCancel is false calling FinishMoveBy will cause the animated scroll to complete instead of being interrupted.

◆ AutoScroll()

void CYIScrollController::AutoScroll ( )
protected

Calls ScrollListener::OnScrollAuto if the scroll controller is scrolling.

◆ CalculateCenterOffset()

float CYIScrollController::CalculateCenterOffset ( ) const

Returns the offset to the center of the scroll controller's snap back range set in SetMagnetRules().

◆ CalculateOffsetToNearestPage()

float CYIScrollController::CalculateOffsetToNearestPage ( float  moveBy) const

Returns the offset from the center of the snap back range set in SetMagnetRules() to the nearest page if the scroll controller were to move by moveBy. Returns 0.0f if paginated behaviour is not enabled.

See also
SetPageSize

◆ CalculatePageOffset()

float CYIScrollController::CalculatePageOffset ( int32_t  page) const

Returns the offset from the center of the snap back range set in SetMagnetRules() to the page at index page. Returns 0.0f if paginated behaviour is not enabled.

See also
SetPageSize

◆ CalculateSnapBackOffset() [1/2]

virtual float CYIScrollController::CalculateSnapBackOffset ( ) const
virtual

Returns the amount the scroll controller would scroll if the scroll were to stop immediatly disregarding velocity. If the data range is smaller than the snap back range returns the offset to the start of the snap back range. If the scroll controller is outside of the snap back range set in SetMagnetRules() at the start or end returns the offset to the start or end of the snap back range respectively. If the scroll controller is not outside of range and has been configured to center on pages: returns the offset from CalculateOffsetToNearestPage().

See also
SetDataRange
SetPageSize

◆ CalculateSnapBackOffset() [2/2]

float CYIScrollController::CalculateSnapBackOffset ( float  dataStart) const
protected

Internal implementation of CalculateSnapBackOffset, generalized with a data start parameter.

◆ Decelerate()

void CYIScrollController::Decelerate ( )
protected

Calculates where the scroll controller will end scrolling based on the current velocity and starts animating to that position. The position will be within the data range.

◆ EndScroll()

void CYIScrollController::EndScroll ( )
protected

Finish any scroll in progress.

◆ FinishMoveBy()

void CYIScrollController::FinishMoveBy ( )
protected

Finish the current snap back animation.

See also
SetMagnetRules

◆ GestureEnd()

void CYIScrollController::GestureEnd ( float  pos,
uint64_t  eventTimeMs 
)

End a scroll gesture from position pos and time eventTimeMs in milliseconds.

◆ GestureMove()

void CYIScrollController::GestureMove ( float  pos,
uint64_t  eventTimeMs 
)

Update a scroll gesture with the movement position pos at time eventTimeMs in milliseconds.

◆ GestureStart()

void CYIScrollController::GestureStart ( float  pos,
uint64_t  eventTimeMs 
)

Start a scroll gesture at position pos and time eventTimeMs in milliseconds.

◆ GetAlwaysCenterOnPage()

bool CYIScrollController::GetAlwaysCenterOnPage ( ) const

Returns true if the scroll controller should center on a page.

See also
SetPageSize

◆ GetCompletedScrollDelta()

float CYIScrollController::GetCompletedScrollDelta ( ) const

Returns how much the scroll controller has scrolled by since calling AnimateMoveBy.

◆ GetCurPage()

int32_t CYIScrollController::GetCurPage ( ) const

Returns the current page of the scroll controller. Returns 0 if paginated behaviour is not enabled.

See also
SetPageSize

◆ GetCurrentVelocity()

int64_t CYIScrollController::GetCurrentVelocity ( ) const

Returns the current velocity of the scroll based on previous inputs to the scroll controller.

◆ GetCurrentWindowPos()

void CYIScrollController::GetCurrentWindowPos ( float *  pStart,
float *  pEnd 
) const

Populate pStart and pEnd with the start and end positions of the snap back range as a percentage of the data range. If the snap back start position is the start position of the data range the values range between 0.0f and 1.0.

See also
SetMagnetRules

◆ GetDataEnd()

float CYIScrollController::GetDataEnd ( ) const
protected

Returns the end position of the data range.

See also
SetDataRange

◆ GetDataRange()

void CYIScrollController::GetDataRange ( float *  pStart,
float *  pSize 
) const

Populates pStart and pSize with the start position and size of the data range respectively.

Note
The data range moves as the controller is scrolled.

◆ GetDataStart()

float CYIScrollController::GetDataStart ( ) const

Returns the position of the start of the data range.

See also
GetDataRange

◆ GetDecelerationDuration()

virtual uint32_t CYIScrollController::GetDecelerationDuration ( ) const
virtual

Returns the time over which the scroll controller will cease scrolling after the gesture has ended. This defaults to 1000 ms.

See also
CYIScrollController::ScrollListener::OnScrollEnded

◆ GetPageCount()

size_t CYIScrollController::GetPageCount ( ) const

Returns the number of pages in the data range. Returns 0 if paginated behaviour is not enabled.

See also
GetDataRange
SetPageSize

◆ GetPageSize()

float CYIScrollController::GetPageSize ( ) const

Returns the size of pages. The default is 0.0f.

See also
SetPageSize

◆ GetPctPos()

float CYIScrollController::GetPctPos ( ) const

If the snap back range is greater than or equal to the data range, returns 0. Otherwise returns the difference between the current position and the snap back start postition as a percentage of the data range less the snap back range. If the snap back start position is the start position of the data range the values range between 0.0f and 1.0.

◆ GetScrollDelta()

float CYIScrollController::GetScrollDelta ( ) const

Returns the delta that was set when calling AnimateMoveBy.

◆ GetScrollStartPos()

float CYIScrollController::GetScrollStartPos ( ) const

Returns the position at the start of the last scroll.

◆ GetSnapBackDur()

uint64_t CYIScrollController::GetSnapBackDur ( ) const
See also
SetSnapBackDur

◆ IsOutOfRange()

bool CYIScrollController::IsOutOfRange ( float  offset = 0.0f) const
protected

Returns true if the scroll controller is outside of the snap back range.

See also
SetMagnetRules

◆ IsScrolling()

bool CYIScrollController::IsScrolling ( ) const

Returns true if the controller is scrolling.

◆ MoveBy()

void CYIScrollController::MoveBy ( float  delta,
float  eventPos = 0,
bool  allowOutOfRange = false,
bool  notifyListener = true,
bool  skipIfAnimation = false 
)

Scroll by delta. The eventPos will be added to YI_SCROLLED_INFO and passed to the ScrollListener. If allowOutOfRange is true the scroll will be permitted to move beyond the snap back range set by SetMagnetRules(). If notifyListener is true the scroll listener will be notified of the translation.

See also
SetScrollListener

◆ MoveByAnimate()

void CYIScrollController::MoveByAnimate ( float  delta,
uint64_t  dur,
CYITimeInterpolator pInterpolator = nullptr,
bool  allowOutOfRange = true 
)

Scroll by delta over dur milliseconds.

When dur is non-0, pInterpolator can be used to specify an interpolator to use for the animation. If an interpolator is not provided, CYIInterpolateSigmoid is used. If allowOutOfRange is true the scroll will be permitted to move beyond the snap back range set by SetMagnetRules().

See also
AnimateMoveBy

◆ MoveToPercentage()

void CYIScrollController::MoveToPercentage ( float  percentage,
bool  notifyListener = true 
)

Move to the percentage percentage. The percentage is typically between 0.0 and 1.0f. The scroll listener will be notified of the change in position if notifyListener is true.

Note
The data range or snap back range must be set prior to calling this function.
See also
SetDataRange
SetMagnetRules
SetScrollListener

◆ MoveToPercentageAnimate()

void CYIScrollController::MoveToPercentageAnimate ( float  percentage,
uint64_t  dur,
CYITimeInterpolator pInterpolator = nullptr 
)

Animates to the percentage percentage over dur milliseconds. The percentage is typically between 0.0 and 1.0f.

Note
The data range or snap back range must be set prior to calling this function.

When dur is non-0, pInterpolator can be used to specify an interpolator to use for the animation. If an interpolator is not provided, CYIInterpolateSigmoid is used.

See also
SetDataRange
SetMagnetRules

◆ OnAnimate()

virtual void CYIScrollController::OnAnimate ( CYIAnimation pAnim,
float  dataPosition 
)
overrideprotectedvirtual

Called during animated scrolls. Used to capture scroll information and update the ScrollListener.

Reimplemented from CYIAnimation::Listener.

◆ OnAnimationBegin()

virtual void CYIScrollController::OnAnimationBegin ( CYIAnimation pAnim)
overrideprotectedvirtual

Called when an animated scroll begins.

Reimplemented from CYIAnimation::Listener.

◆ OnAnimationEnd()

virtual void CYIScrollController::OnAnimationEnd ( CYIAnimation pAnim)
overrideprotectedvirtual

Called when an animated scroll ends. Ends the scroll.

Reimplemented from CYIAnimation::Listener.

◆ Reset()

void CYIScrollController::Reset ( )

Stop any current scrolls and reset the data range size and position.

See also
StopScrolling

◆ SetCarousel()

void CYIScrollController::SetCarousel ( bool  carousel)

Sets the carousel rule to carousel. When carousel is true, the scroll controller is configured as an infinite 'loop'.

Note
When carousel is true, the 'snapback' magnet rule is ignored (since there is no longer a 'beginning' and 'end' to the data range). However, the 'snapback start' and 'snapback end' values are still taken into consideration. It is generally necessary to call
SetMagnetRules(false, 0.0f, 0.0f, 0.0f, 0.0f);
in order to reset the magnet rules.

◆ SetDataRange()

void CYIScrollController::SetDataRange ( float  dataStart,
float  dataSize,
bool  animate = true 
)

Sets the data range starting at dataStart with size dataSize. If animate is true, the movement to a new position will be animated if it would be out of range as a result of this function call. The data range is used in calculations throughout the scroll controller. While not required for scrolling behaviour, it is recommeded that a data range is set to the start position and size of the range being scrolled.

Note
The absolute value of dataSize is used.

◆ SetDecelerationDuration()

void CYIScrollController::SetDecelerationDuration ( uint32_t  durationMs)

Sets the time over which the scroll controller will cease scrolling after the gesture has ended. This defaults to 1000 ms.

See also
CYIScrollController::ScrollListener::OnScrollEnded

◆ SetFrictionCoeff()

void CYIScrollController::SetFrictionCoeff ( float  frictionCoefficient)

Sets a coefficient by which the velocity will be multipied when the gesture ends. The default value is 0.5f.

◆ SetMagnetRules()

void CYIScrollController::SetMagnetRules ( bool  snapBack,
float  snapBackStart,
float  snapBackEnd,
float  maxOutOfRangeStart,
float  maxOutOfRangeEnd 
)

Configures a snap back range that starts at snapBackStart and ends at snapBackEnd. If snapBack is true the controller will snap back to the snap back range. maxOutOfRangeStart and maxOutOfRangeEnd define how far outside of the snap back range the scroll controller can scroll.

Note
snapBackStart and maxOutOfRangeStart are typically less than snapBackEnd and maxOutOfRangeEnd respectively.

◆ SetMaxVelocityCoeff()

void CYIScrollController::SetMaxVelocityCoeff ( float  maxVelocityCoefficient)

Sets a coefficient for the max velocity. maxVelocityCoefficient is clamped to values >= 0.5f. The default value is 1.0f and the max velocity is 5000.

◆ SetOutOfRangeListener()

void CYIScrollController::SetOutOfRangeListener ( OutOfRangeListener pListener)

The controller does not take ownership of pListener. Setting an OutOfRangeListener overwrites the previous OutOfRangeListener.

◆ SetPageSize()

void CYIScrollController::SetPageSize ( float  pageSize,
bool  alwaysCenterOnPage = false,
bool  swipeToNextPage = false 
)

Sets the page size to pageSize. If alwaysCenterOnPage is set to true the scroll controller will snap to a position such that the closest page will be centered in the snap back range set by SetMagnetRules(). If swipeToNextPage is set to true the scroll controller will cause any velocity at the end of a gesture to scroll to either the page before or after the page at the start of the gesture.

Note
Setting swipeToNextPage to true only has effect if alwaysCenterOnPage is also true. If alwaysCenterOnPage is false, the controller will not snap to pages. Setting pageSize to 0.0f disables the scroll controller's paginated behaviour. The default value is 0.0f.
Pages start at multiples of pageSize, users can effectively offset the page positions by offseting the data range using SetDataRange() and the snap back range using SetMagnetRules().

◆ SetScrollListener()

void CYIScrollController::SetScrollListener ( ScrollListener pListener)

The controller does not take ownership of pListener. Setting a ScrollListener overwrites the previous ScrollListener.

◆ SetSnapBackDur()

void CYIScrollController::SetSnapBackDur ( uint64_t  snapBackDur)

Set the duration of the snap back in milliseconds. The default is 300. Snap backs can be configured using SetPageSize() and SetMagnetRules(). The snap back starts when a gesture ends.

◆ SnapBack()

bool CYIScrollController::SnapBack ( bool  animate = true)
protected

Causes the controller to snap to the nearest page offset. Returns true if the controller will scroll as a result of this call to SnapBack().

See also
CalculateSnapBackOffset

◆ StartScroll()

void CYIScrollController::StartScroll ( bool  alreadyScrolling)
protected

Called by GestureStart() to start a scroll. alreadyScrolling should be set to true if the controller is being animated.

Note
This function has no effect if the controller is already scrolling.

◆ StopScrolling()

void CYIScrollController::StopScrolling ( )

Stop the current scroll.

◆ UpdateMoveByAnimateDelta()

void CYIScrollController::UpdateMoveByAnimateDelta ( float  delta)

Updates the target scroll position of an in-progress scroll to be delta from the current scroll position. The amount of time remaining until the end of the scroll animation will be unchanged.

Member Data Documentation

◆ m_allowOutOfRangeOnAnimateMoveBy

bool CYIScrollController::m_allowOutOfRangeOnAnimateMoveBy
protected

◆ m_alwaysCenterOnPage

bool CYIScrollController::m_alwaysCenterOnPage
protected

◆ m_anticipatedDataEnd

float CYIScrollController::m_anticipatedDataEnd
protected

◆ m_anticipatedDataStart

float CYIScrollController::m_anticipatedDataStart
protected

◆ m_carousel

bool CYIScrollController::m_carousel
protected

◆ m_dataSize

float CYIScrollController::m_dataSize
protected

◆ m_dataStart

float CYIScrollController::m_dataStart
protected

◆ m_decelerationDuration

uint32_t CYIScrollController::m_decelerationDuration
protected

◆ m_frictionCoeff

float CYIScrollController::m_frictionCoeff
protected

◆ m_gestureEndPos

float CYIScrollController::m_gestureEndPos
protected

◆ m_gestureStarted

bool CYIScrollController::m_gestureStarted
protected

◆ m_isScrolling

bool CYIScrollController::m_isScrolling
protected

◆ m_maxOutOfRangeEnd

float CYIScrollController::m_maxOutOfRangeEnd
protected

◆ m_maxOutOfRangeStart

float CYIScrollController::m_maxOutOfRangeStart
protected

◆ m_moveByCanCancel

bool CYIScrollController::m_moveByCanCancel
protected

◆ m_moveByDone

float CYIScrollController::m_moveByDone
protected

◆ m_moveByTarget

float CYIScrollController::m_moveByTarget
protected

◆ m_outOfRangeDirection

int32_t CYIScrollController::m_outOfRangeDirection
protected

◆ m_pageAtGestureStart

int32_t CYIScrollController::m_pageAtGestureStart
protected

◆ m_pageSize

float CYIScrollController::m_pageSize
protected

◆ m_pGestureData

std::unique_ptr<CYIInputInterpreter> CYIScrollController::m_pGestureData
protected

◆ m_pMoveByAnim

std::unique_ptr<CYIAnimation> CYIScrollController::m_pMoveByAnim
protected

◆ m_pOutOfRangeListener

OutOfRangeListener* CYIScrollController::m_pOutOfRangeListener
protected

◆ m_pScrollListener

ScrollListener* CYIScrollController::m_pScrollListener
protected

◆ m_scrollStartPos

float CYIScrollController::m_scrollStartPos
protected

◆ m_snapBack

bool CYIScrollController::m_snapBack
protected

◆ m_snapBackDur

uint64_t CYIScrollController::m_snapBackDur
protected

◆ m_snapBackEnd

float CYIScrollController::m_snapBackEnd
protected

◆ m_snapBackStart

float CYIScrollController::m_snapBackStart
protected

◆ m_swipeToNextPage

bool CYIScrollController::m_swipeToNextPage
protected

The documentation for this class was generated from the following file: