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 uSnapBackDur)
uint64_t	GetSnapBackDur () const
void	SetFrictionCoeff (float fFrictionCoefficient)
void	SetMaxVelocityCoeff (float fMaxVelocityCoefficient)
void	SetScrollListener (ScrollListener *pListener)
void	SetOutOfRangeListener (OutOfRangeListener *pListener)
void	GetDataRange (float *pStart, float *pSize) const
void	SetDataRange (float fDataStart, float fDataSize, bool bAnimate=true)
void	SetMagnetRules (bool bSnapBack, float fSnapBackStart, float fSnapBackEnd, float fMaxOutOfRangeStart, float fMaxOutOfRangeEnd)
void	SetCarousel (bool bCarousel)
void	MoveBy (float fDelta, float fEventPos=0, bool bAllowOutOfRange=false, bool bNotifyListener=true)
void	MoveByAnimate (float fDelta, uint64_t uDur, CYITimeInterpolator *pInterpolator=nullptr, bool bAllowOutOfRange=true)
void	MoveToPercentage (float fPercentage, bool bNotifyListener=true)
void	MoveToPercentageAnimate (float fPercentage, uint64_t uDur, 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 fPageSize, bool bAlwaysCenterOnPage=false, bool bSwipeToNextPage=false)
float	GetPageSize () const
bool	GetAlwaysCenterOnPage () const
int32_t	GetCurPage () const
int32_t	GetPageCount () const
float	CalculatePageOffset (int32_t nPage) const
float	CalculateOffsetToNearestPage (float fMoveBy) const
float	CalculateCenterOffset () const
virtual float	CalculateSnapBackOffset () const
void	GestureStart (float fPos, uint64_t uEventTimeMs)
void	GestureMove (float fPos, uint64_t uEventTimeMs)
void	GestureEnd (float fPos, uint64_t uEventTimeMs)
void	SetDecelerationDuration (uint32_t uDurationMs)
virtual uint32_t	GetDecelerationDuration () const
float	GetScrollDelta () const
float	GetCompletedScrollDelta () const
Public Member Functions inherited from CYIAnimation::Listener
virtual	~Listener ()
Public Member Functions inherited from CYIScriptableObject
	CYIScriptableObject ()
	CYIScriptableObject (const CYIScriptableObject &other)
CYIScriptableObject &	operator= (const CYIScriptableObject &other)
virtual	~CYIScriptableObject ()
CYIBindingImplementation *	GetBindingImplementation () const
void	SetBindingImplementation (CYIBindingImplementation *pBindingImplementation)
virtual const CYIRuntimeTypeInfo *	GetRuntimeTypeInfoForScriptObject () const

Protected Member Functions
virtual bool	AdjustMoveBy (float *pMoveBy, const float &fDataEnd) const
virtual bool	AdjustMoveByNoOutOfRange (float *pMoveBy) const
virtual bool	AdjustMoveByNoOutOfRangeDuringDecelerate (float *pMoveBy, int32_t nDir)
void	AnimateMoveBy (float fDelta, uint64_t uDur, bool bCanCancel, CYITimeInterpolator *pInterpolator=nullptr)
void	Decelerate ()
void	FinishMoveBy ()
bool	SnapBack (bool bAnimate=true)
virtual void	OnAnimate (CYIAnimation *pAnim, float fDataPosition) override
virtual void	OnAnimationBegin (CYIAnimation *pAnim) override
virtual void	OnAnimationEnd (CYIAnimation *pAnim) override
void	StartScroll (bool bAlreadyScrolling)
void	EndScroll ()
void	AutoScroll ()
float	GetDataEnd () const
bool	IsOutOfRange (float fOffset=0.0f) const
float	CalculateSnapBackOffset (float fDataStart) const

Protected Attributes
float	m_fDataStart
float	m_fDataSize
float	m_fAnticipatedDataStart
float	m_fAnticipatedDataEnd
float	m_fScrollStartPos
bool	m_bIsScrolling
int32_t	m_nOutOfRangeDirection
bool	m_bAlwaysCenterOnPage
bool	m_bSwipeToNextPage
bool	m_bSnapBack
float	m_fSnapBackStart
float	m_fSnapBackEnd
float	m_fMaxOutOfRangeStart
float	m_fMaxOutOfRangeEnd
float	m_fPageSize
bool	m_bCarousel
uint64_t	m_uSnapBackDur
float	m_fFrictionCoeff
uint32_t	m_uDecelerationDuration
bool	m_bGestureStarted
int32_t	m_nPageAtGestureStart
float	m_fGestureEndPos
CYIAnimation *	m_pMoveByAnim
float	m_fMoveByTarget
float	m_fMoveByDone
bool	m_bMoveByCanCancel
bool	m_bAllowOutOfRangeOnAnimateMoveBy
ScrollListener *	m_pScrollListener
OutOfRangeListener *	m_pOutOfRangeListener
CYIInputInterpreter *	m_pGestureData

Constructor & Destructor Documentation

CYIScrollController::CYIScrollController

(

)

virtual CYIScrollController::~CYIScrollController ( )

overridevirtual

Member Function Documentation

virtual bool CYIScrollController::AdjustMoveBy ( float *  pMoveBy, const float &  fDataEnd  ) 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. fDataEnd is the max out of range the scroll should go after the end of the data range.

See also

SetMagnetRules

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().

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

protectedvirtual

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

See also

AdjustMoveByNoOutOfRange

void CYIScrollController::AnimateMoveBy ( float  fDelta, uint64_t  uDur, bool  bCanCancel, CYITimeInterpolator *  pInterpolator = nullptr  )

protected

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

void CYIScrollController::AutoScroll ( )

protected

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

float CYIScrollController::CalculateCenterOffset

(

)

const

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

float CYIScrollController::CalculateOffsetToNearestPage

(

float

fMoveBy

)

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 fMoveBy. Returns 0.0f if paginated behaviour is not enabled.

See also

SetPageSize

float CYIScrollController::CalculatePageOffset

(

int32_t

nPage

)

const

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

See also

SetPageSize

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

float CYIScrollController::CalculateSnapBackOffset ( float  fDataStart ) const

protected

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

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.

void CYIScrollController::EndScroll ( )

protected

Finish any scroll in progress.

void CYIScrollController::FinishMoveBy ( )

protected

Finish the current snap back animation.

See also

SetMagnetRules

void CYIScrollController::GestureEnd	(	float	fPos,
		uint64_t	uEventTimeMs
	)

End a scroll gesture from position fPos and time uEventTimeMs in milliseconds.

void CYIScrollController::GestureMove	(	float	fPos,
		uint64_t	uEventTimeMs
	)

Update a scroll gesture with the movement position fPos at time uEventTimeMs in milliseconds.

void CYIScrollController::GestureStart	(	float	fPos,
		uint64_t	uEventTimeMs
	)

Start a scroll gesture at position fPos and time uEventTimeMs in milliseconds.

bool CYIScrollController::GetAlwaysCenterOnPage

(

)

const

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

See also

SetPageSize

float CYIScrollController::GetCompletedScrollDelta

(

)

const

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

int32_t CYIScrollController::GetCurPage

(

)

const

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

See also

SetPageSize

int64_t CYIScrollController::GetCurrentVelocity

(

)

const

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

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

float CYIScrollController::GetDataEnd ( ) const

protected

Returns the end position of the data range.

See also

SetDataRange

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.

float CYIScrollController::GetDataStart

(

)

const

Returns the position of the start of the data range.

See also

GetDataRange

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

int32_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

float CYIScrollController::GetPageSize

(

)

const

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

See also

SetPageSize

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.

float CYIScrollController::GetScrollDelta

(

)

const

Returns the delta that was set when calling AnimateMoveBy.

float CYIScrollController::GetScrollStartPos

(

)

const

Returns the position at the start of the last scroll.

uint64_t CYIScrollController::GetSnapBackDur

(

)

const

See also

SetSnapBackDur

bool CYIScrollController::IsOutOfRange ( float  fOffset = 0.0f ) const

protected

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

See also

SetMagnetRules

bool CYIScrollController::IsScrolling

(

)

const

Returns true if the controller is scrolling.

void CYIScrollController::MoveBy	(	float	fDelta,
		float	fEventPos = 0,
		bool	bAllowOutOfRange = false,
		bool	bNotifyListener = true
	)

Scroll by fDelta. The fEventPos will be added to YI_SCROLLED_INFO and passed to the ScrollListener. If bAllowOutOfRange is true the scroll will be permitted to move beyond the snap back range set by SetMagnetRules(). If bNotifyListener is true the scroll listener will be notified of the translation.

See also

SetScrollListener

void CYIScrollController::MoveByAnimate	(	float	fDelta,
		uint64_t	uDur,
		CYITimeInterpolator *	pInterpolator = nullptr,
		bool	bAllowOutOfRange = true
	)

Scroll by fDelta over uDur milliseconds.

When uDur 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 bAllowOutOfRange is true the scroll will be permitted to move beyond the snap back range set by SetMagnetRules().

See also

AnimateMoveBy

void CYIScrollController::MoveToPercentage	(	float	fPercentage,
		bool	bNotifyListener = true
	)

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

Note

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

See also

SetDataRange

SetMagnetRules

SetScrollListener

void CYIScrollController::MoveToPercentageAnimate	(	float	fPercentage,
		uint64_t	uDur,
		CYITimeInterpolator *	pInterpolator = nullptr
	)

Animates to the percentage fPercentage over uDur 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 uDur 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

virtual void CYIScrollController::OnAnimate ( CYIAnimation *  pAnim, float  fDataPosition  )

overrideprotectedvirtual

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

Reimplemented from CYIAnimation::Listener.

virtual void CYIScrollController::OnAnimationBegin ( CYIAnimation *  pAnim )

overrideprotectedvirtual

Called when an animated scroll begins.

Reimplemented from CYIAnimation::Listener.

virtual void CYIScrollController::OnAnimationEnd ( CYIAnimation *  pAnim )

overrideprotectedvirtual

Called when an animated scroll ends. Ends the scroll.

Reimplemented from CYIAnimation::Listener.

void CYIScrollController::Reset

(

)

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

See also

StopScrolling

void CYIScrollController::SetCarousel

(

bool

bCarousel

)

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

Note

When bCarousel 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.

void CYIScrollController::SetDataRange	(	float	fDataStart,
		float	fDataSize,
		bool	bAnimate = true
	)

Sets the data range starting at fDataStart with size fDataSize. If bAnimate 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 fDataSize is used.

void CYIScrollController::SetDecelerationDuration

(

uint32_t

uDurationMs

)

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

void CYIScrollController::SetFrictionCoeff

(

float

fFrictionCoefficient

)

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

void CYIScrollController::SetMagnetRules	(	bool	bSnapBack,
		float	fSnapBackStart,
		float	fSnapBackEnd,
		float	fMaxOutOfRangeStart,
		float	fMaxOutOfRangeEnd
	)

Configures a snap back range that starts at fSnapBackStart and ends at fSnapBackEnd. If bSnapBack is true the controller will snap back to the snap back range. fMaxOutOfRangeStart and fMaxOutOfRangeEnd define how far outside of the snap back range the scroll controller can scroll.

Note

fSnapBackStart and fMaxOutOfRangeStart are typically less than fSnapBackEnd and fMaxOutOfRangeEnd respectively.

void CYIScrollController::SetMaxVelocityCoeff

(

float

fMaxVelocityCoefficient

)

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

void CYIScrollController::SetOutOfRangeListener

(

OutOfRangeListener *

pListener

)

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

void CYIScrollController::SetPageSize	(	float	fPageSize,
		bool	bAlwaysCenterOnPage = false,
		bool	bSwipeToNextPage = false
	)

Sets the page size to fPageSize. If bAlwaysCenterOnPage 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 bSwipeToNextPage 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 bSwipeToNextPage to true only has effect if bAlwaysCenterOnPage is also true. If bAlwaysCenterOnPage is false, the controller will not snap to pages. Setting fPageSize to 0.0f disables the scroll controller's paginated behaviour. The default value is 0.0f.

Pages start at multiples of fPageSize, users can effectively offset the page positions by offseting the data range using SetDataRange() and the snap back range using SetMagnetRules().

void CYIScrollController::SetScrollListener

(

ScrollListener *

pListener

)

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

void CYIScrollController::SetSnapBackDur

(

uint64_t

uSnapBackDur

)

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.

bool CYIScrollController::SnapBack ( bool  bAnimate = 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

void CYIScrollController::StartScroll ( bool  bAlreadyScrolling )

protected

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

Note

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

void CYIScrollController::StopScrolling

(

)

Stop the current scroll.

Member Data Documentation

bool CYIScrollController::m_bAllowOutOfRangeOnAnimateMoveBy

protected

bool CYIScrollController::m_bAlwaysCenterOnPage

protected

bool CYIScrollController::m_bCarousel

protected

bool CYIScrollController::m_bGestureStarted

protected

bool CYIScrollController::m_bIsScrolling

protected

bool CYIScrollController::m_bMoveByCanCancel

protected

bool CYIScrollController::m_bSnapBack

protected

bool CYIScrollController::m_bSwipeToNextPage

protected

float CYIScrollController::m_fAnticipatedDataEnd

protected

float CYIScrollController::m_fAnticipatedDataStart

protected

float CYIScrollController::m_fDataSize

protected

float CYIScrollController::m_fDataStart

protected

float CYIScrollController::m_fFrictionCoeff

protected

float CYIScrollController::m_fGestureEndPos

protected

float CYIScrollController::m_fMaxOutOfRangeEnd

protected

float CYIScrollController::m_fMaxOutOfRangeStart

protected

float CYIScrollController::m_fMoveByDone

protected

float CYIScrollController::m_fMoveByTarget

protected

float CYIScrollController::m_fPageSize

protected

float CYIScrollController::m_fScrollStartPos

protected

float CYIScrollController::m_fSnapBackEnd

protected

float CYIScrollController::m_fSnapBackStart

protected

int32_t CYIScrollController::m_nOutOfRangeDirection

protected

int32_t CYIScrollController::m_nPageAtGestureStart

protected

CYIInputInterpreter* CYIScrollController::m_pGestureData

protected

CYIAnimation* CYIScrollController::m_pMoveByAnim

protected

OutOfRangeListener* CYIScrollController::m_pOutOfRangeListener

protected

ScrollListener* CYIScrollController::m_pScrollListener

protected

uint32_t CYIScrollController::m_uDecelerationDuration

protected

uint64_t CYIScrollController::m_uSnapBackDur

protected

---

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

• view/YiScrollController.h