You.i Engine
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:
  4. If the preload validation fails:
See also
CYIAbstractScreenViewController
CYIBundle
CYIScreenTransitionManager::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 size)
 
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 ()
 
CYIAbstractScreenViewControllerPeekScreen () const
 
CYIBundle PeekScreenBundle () const
 
- Public Member Functions inherited from CYISignalHandler
 CYISignalHandler ()
 
 CYISignalHandler (const CYISignalHandler &rSignalHandler)
 
virtual ~CYISignalHandler ()
 
CYISignalHandleroperator= (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 Attributes

CYISignal< const CYIPersistentStore &> TransitionStarted
 
CYISignal TransitionCompleted
 
CYISignal< const CYIBundle &> TransitionFailed
 

Protected Member Functions

size_t GetStackSize () const
 

Constructor & Destructor Documentation

◆ CYIScreenTransitionManager()

CYIScreenTransitionManager::CYIScreenTransitionManager ( )

◆ ~CYIScreenTransitionManager()

virtual CYIScreenTransitionManager::~CYIScreenTransitionManager ( )
virtual

Member Function Documentation

◆ AppSpecificLoadingComplete()

void CYIScreenTransitionManager::AppSpecificLoadingComplete ( )

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

See also
CYIScreenTransitionManager::ScreenTransitionDelegate::OnLoadingAnimationsStart()

◆ ClearScreenNavigationHistory()

void CYIScreenTransitionManager::ClearScreenNavigationHistory ( )

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

◆ Connect()

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.

◆ Disconnect()

bool CYIScreenTransitionManager::Disconnect ( CYIAbstractScreenViewController pScreen)

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

◆ GetStackSize()

size_t CYIScreenTransitionManager::GetStackSize ( ) const
protected

◆ IsTransitionActive()

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.

◆ PeekScreen()

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.

◆ PeekScreenBundle()

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

◆ PopAllScreens()

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.

◆ PopScreen()

bool CYIScreenTransitionManager::PopScreen ( )

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

◆ PushScreen() [1/3]

void CYIScreenTransitionManager::PushScreen ( CYIAbstractScreenViewController pScreen)

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

◆ PushScreen() [2/3]

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

Pushes pScreen onto the screen stack along with bundle data.

◆ PushScreen() [3/3]

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.

◆ SetMaxScreenStackSize()

void CYIScreenTransitionManager::SetMaxScreenStackSize ( uint32_t  size)

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

◆ SetTransitionDelegate()

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.

◆ UseTransition()

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

◆ TransitionCompleted

CYISignal CYIScreenTransitionManager::TransitionCompleted

◆ TransitionFailed

CYISignal<const CYIBundle & > CYIScreenTransitionManager::TransitionFailed

◆ TransitionStarted

CYISignal<const CYIPersistentStore & > CYIScreenTransitionManager::TransitionStarted

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