CYIScreenTransitionManager Class Reference

Detailed Description

Stores a stack of screen view controllers (referred to here for simplicity as "screens") to allow for forward and backward navigation between screens (including handling screen transitions) by using PushScreen() and PopScreen().

Each call to PushScreen() and PopScreen() initiates a screen transition. In the case of PushScreen(), it is a transition to the pushed screen. In the case of PopScreen(), it is a transition to the next screen in the stack. However, this transition does not take place if IsTransitionActive() returns true since there is already a transition taking place.

A CYIScreenTransition controls the transitions between the screens.

To listen for and respond to varous screen transition events, construct a class that implements CYIScreenTransitionManager::ScreenTransitionDelegate.

Use the struct CYIScreenTransitionManager::ScreenTransitionBundle to store extra data for individual screens. This struct is stored using PushScreen() and can be retrieved with PeekScreenBundle().

Steps to create a screen transition manager using a screen transition delegate for listening:

1. Create a class that implements CYIScreenTransitionManager::ScreenTransitionDelegate. Referred to in this example as AppScreenManager.
2. Add a CYIScreenTransitionManager to the AppScreenManager.
3. Call SetTransitionDelegate() with the AppScreenManager on the CYIScreenTransitionManager.
4. Call Connect() during initialization of the screens.
5. Call UseTransition() to set the transition used between screens.
6. When a new screen must be displayed, call PushScreen().
7. When a screen has to be removed or transitioned back to, call PopScreen().
8. Call Disconnect() on destruction of the screens.

Detailed description of the transition sequence when moving from one screen to the next:

1. The "AnimateOut + Screen Transition" effect is initiated on the "From Screen".
2. CYIAbstractScreenViewController::PreloadValidate() is called on the "To Screen".
3. If this method completes successfully:
   • The "From Screen" is unloaded using CYIAbstractScreenViewController::Unload().
   • When unload completes (there is no fail condition for unload) CYIAbstractScreenViewController::Preload() is called.
   • When both the animation effects and screen preloading has completed, CYIAbstractScreenViewController::Load() is called on the "To Screen".
4. If the preload validation fails:
   • The "From Screen" is re-displayed and ScreenTransitionDelegate::onTransitionError() is called with a new bundle that was provided by "To Screen".

See also

CYIAbstractScreenViewController

CYIBundle

ScreenTransitionDelegate

CYIScreenTransition

#include <screen/YiScreenTransitionManager.h>

Inheritance diagram for CYIScreenTransitionManager:

Classes
struct	ScreenTransitionBundle
	Contains optional data which can be stored on the screen stack with PushScreen() and retrieved using PeekScreenBundle(). More...
class	ScreenTransitionDelegate
	Listener interface for the CYIScreenTransitionManager events. More...

Public Member Functions
	CYIScreenTransitionManager ()
virtual	~CYIScreenTransitionManager ()
bool	Connect (CYIAbstractScreenViewController *pScreen)
bool	Disconnect (CYIAbstractScreenViewController *pScreen)
void	UseTransition (CYIScreenTransition *pTransition)
void	SetTransitionDelegate (ScreenTransitionDelegate *pScreenTransitionDelegate)
bool	IsTransitionActive () const
void	AppSpecificLoadingComplete ()
void	SetMaxScreenStackSize (uint32_t uSize)
void	PushScreen (CYIAbstractScreenViewController *pScreen)
void	PushScreen (CYIAbstractScreenViewController *pScreen, const CYIBundle &bundle)
void	PushScreen (CYIAbstractScreenViewController *pScreen, const CYIBundle &bundle, const std::vector< ScreenTransitionBundle > &historyScreens)
bool	PopScreen ()
void	PopAllScreens ()
void	ClearScreenNavigationHistory ()
CYIAbstractScreenViewController *	PeekScreen () const
CYIBundle	PeekScreenBundle () const
Public Member Functions inherited from CYISignalHandler
	CYISignalHandler ()
	CYISignalHandler (const CYISignalHandler &rSignalHandler)
virtual	~CYISignalHandler ()
CYISignalHandler &	operator= (const CYISignalHandler &rSignalHandler)
void	MoveToThread (CYIThread *pThread)
	This function allows the user to override the default thread affinity to any CYIThread that may or may not be running. More...
CYIThreadHandle	GetThreadAffinity () const
void	SetThreadAffinity (const CYIThreadHandle &rThreadAffinity)
virtual bool	IsConnected () const
virtual bool	IsConnected (const CYISignalBase &rSignal) const
void	Disconnect (CYISignalBase &rSignal)
void	DisconnectFromAllSignals ()
Public Member Functions inherited from CYIThread::Listener
	Listener ()
virtual	~Listener ()
virtual void	OnThreadStarted (CYIThread *)
virtual void	OnThreadTerminated (CYIThread *)
virtual void	OnThreadFinished (CYIThread *)
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

Public Attributes
CYISignal< const CYIPersistentStore & >	TransitionStarted
CYISignal	TransitionCompleted
CYISignal< const CYIBundle & >	TransitionFailed
	ScreenTransitionDelegate::onTransitionError. More...

Protected Member Functions
uint32_t	GetStackSize () const

Constructor & Destructor Documentation

CYIScreenTransitionManager::CYIScreenTransitionManager

(

)

virtual CYIScreenTransitionManager::~CYIScreenTransitionManager ( )

virtual

Member Function Documentation

void CYIScreenTransitionManager::AppSpecificLoadingComplete

(

)

Called from CYIScreenController to indicate that the application loading is complete.

See also

ScreenTransitionDelegate::OnLoadingAnimationsStart()

void CYIScreenTransitionManager::ClearScreenNavigationHistory

(

)

Clears the navigation history by removing all screens from the stack except the current screen.

bool CYIScreenTransitionManager::Connect

(

CYIAbstractScreenViewController *

pScreen

)

Connects the CYIAbstractScreenViewController signals to pScreen. Must be called before PushScreen(). Returns false and has no effect if pScreen is null.

bool CYIScreenTransitionManager::Disconnect

(

CYIAbstractScreenViewController *

pScreen

)

Disconnects the CYIAbstractScreenViewController signals from pScreen. Returns false and has no effect if pScreen is null.

uint32_t CYIScreenTransitionManager::GetStackSize ( ) const

protected

bool CYIScreenTransitionManager::IsTransitionActive

(

)

const

Returns whether or not there is a transition currently active.

A transition is active once a screen is pushed or popped until such time as the screen being navigated to loads or fails to load. If a screen fails to load it is due to an error in CYIAbstractScreenViewController::Preload().

The active state will persist throughout any screen in and out animations, becoming inactive only upon the completion of the animations.

CYIAbstractScreenViewController* CYIScreenTransitionManager::PeekScreen

(

)

const

Returns the next screen on the stack underneath the current screen. This is the screen that will be transitioned to with a call to PopScreen().

This method is useful for a variety of tasks. For example, it can be used to check if there are no more screens on the stack or to retrieve details about the prevous screen in order to perform particular actions before PopScreen() is called.

CYIBundle CYIScreenTransitionManager::PeekScreenBundle

(

)

const

Returns a copy of the bundle of the next screen on the stack underneath the current screen. This is the screen that will be transitioned to with a call to PopScreen().

void CYIScreenTransitionManager::PopAllScreens

(

)

Unloads the current screen controller on the stack and removes all the others leaving the stack empty. Initiates a screen transition to the last screen in the stack.

bool CYIScreenTransitionManager::PopScreen

(

)

Removes the screen that was last pushed from the screen stack and initiates a screen transition to that screen.

void CYIScreenTransitionManager::PushScreen

(

CYIAbstractScreenViewController *

pScreen

)

Pushes pScreen onto the screen stack which initiates a screen transition to that screen.

void CYIScreenTransitionManager::PushScreen	(	CYIAbstractScreenViewController *	pScreen,
		const CYIBundle &	bundle
	)

Pushes pScreen onto the screen stack along with bundle data.

void CYIScreenTransitionManager::PushScreen	(	CYIAbstractScreenViewController *	pScreen,
		const CYIBundle &	bundle,
		const std::vector< ScreenTransitionBundle > &	historyScreens
	)

Pushes pScreen onto the screen stack along with bundle data and a list of history screens.

Note

The history screens are pushed onto the stack in advance of pScreen.

void CYIScreenTransitionManager::SetMaxScreenStackSize

(

uint32_t

uSize

)

Assigns uSize as the maximum screen stack size. The default value is 0. A value of 0 indicates no stack size limit.

void CYIScreenTransitionManager::SetTransitionDelegate

(

ScreenTransitionDelegate *

pScreenTransitionDelegate

)

Assigns pScreenTransitionDelegate as the screen transition delegate which will be notified when various screen transition manager events occur. Only one ScreenTransitionDelegate can be set, and subsequent calls to this function will replace the active delegate. Use nullptr to remove a previously set ScreenTransitionDelegate.

Note

This class does not take ownership of pScreenTransitionDelegate. The caller must ensure that pScreenTransitionDelegate is valid for the lifetime of this classis deleted when no longer in use.

void CYIScreenTransitionManager::UseTransition

(

CYIScreenTransition *

pTransition

)

Sets the CYIScreenTransition to be used during screen navigation. Only one CYIScreenTransition can be used, and subsequent calls to this function will replace a previously set transition. Use nullptr to remove a previously set CYIScreenTransition.

Note

This class does not take ownership of pTransition. The caller must ensure that pTransition is valid for the lifetime of this class and is deleted when no longer in use.

Member Data Documentation

CYISignal CYIScreenTransitionManager::TransitionCompleted

See also

ScreenTransitionDelegate::onTransitionComplete

CYISignal<const CYIBundle &> CYIScreenTransitionManager::TransitionFailed

ScreenTransitionDelegate::onTransitionError.

CYISignal<const CYIPersistentStore &> CYIScreenTransitionManager::TransitionStarted

See also

ScreenTransitionDelegate::onTransitionStart

---

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

• screen/YiScreenTransitionManager.h