You.i Engine
CYIAbstractScreenViewController Class Referenceabstract

Detailed Description

The CYIAbstractScreenViewController serves as the base to create application screen view controllers.

Typically, the application will create a subclass from CYIAbstractScreenViewController and implement app specific behavior. These screen controllers are used in conjunction with a CYIScreenTransitionManager. CYIScreenTransitionManager will execute the flow of loading / unloading the screen controllers as they are pushed and popped.

The following list of functions can be overloaded by CYIAbstractScreenViewController derived classes to implement screen specific behaviour. They are listed in order of their execution:

OnInitScreen() OnPreloadValidateScreen() OnPreloadScreen() OnStageScreen() OnLoadScreen()

OnUnstageScreen() OnUnloadScreen()

Warning
If a screen transition fails from this controller and this controller CYIViewController::ShouldClearFocus() then focus will be cleared, and no view will have focus.

#include <screen/YiAbstractScreenViewController.h>

Inheritance diagram for CYIAbstractScreenViewController:

Public Types

enum  NavigationHistoryRule {
  NavigationHistoryRule::All,
  NavigationHistoryRule::Last,
  NavigationHistoryRule::None
}
 

Public Member Functions

 CYIAbstractScreenViewController ()
 
 CYIAbstractScreenViewController (CYISceneManager *pSceneManager, CYIApp *pApplication)
 
void SetTitle (const CYIString &title)
 
CYIString GetTitle () const
 
virtual void Init () override
 
void PreloadValidate (CYIBundle bundle)
 
void Preload (CYIBundle bundle, const CYIPersistentStore &StateData)
 
void Load (const CYIPersistentStore &StateData)
 
void StartLoadAnimations ()
 
void StartUnloadAnimations ()
 
void Unload (CYIPersistentStore &StateData)
 
bool IsLoaded () const
 
bool IsInitialized () const
 
void SetBackNavigationEnabled (bool enabled)
 
bool IsBackNavigationEnabled () const
 
void SetInboundActivityIndicatorEnabled (bool enabled)
 
bool IsInboundActivityIndicatorEnabled () const
 
void SetOrientation (CYIScreenProperty::Orientation orientation)
 
CYIScreenProperty::Orientation GetOrientation () const
 
void SetNavigationHistoryRule (NavigationHistoryRule rule)
 
NavigationHistoryRule GetNavigationHistoryRule () const
 
void SetClearNavigationHistory (bool clear)
 
bool ShouldClearNavigationHistory () const
 
void SetStatusBarVisibility (CYIScreenProperty::StatusBar visibility)
 
CYIScreenProperty::StatusBar GetStatusBarVisibility () const
 
void SetNavigationBarVisibility (CYIScreenProperty::NavigationBar visibility)
 
CYIScreenProperty::NavigationBar GetNavigationBarVisibility () const
 
- Public Member Functions inherited from CYIViewController
 CYIViewController (CYISceneManager *pSceneManager)
 
 CYIViewController (CYISceneManager *pSceneManager, CYISceneView *pView)
 
virtual ~CYIViewController ()
 
virtual void UpdateView ()
 
virtual void Begin ()
 
virtual void End ()
 
void SetViewLoaded (bool isLoaded)
 
virtual bool IsViewLoaded () const
 
void SetClearFocus (bool clearFocus)
 
bool ShouldClearFocus () const
 
virtual CYISceneNodeGetSceneRoot () 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< CYIAbstractScreenViewController * > LoadingAnimationCompleted
 
CYISignal< CYIAbstractScreenViewController * > UnloadingAnimationCompleted
 
CYISignal< CYIAbstractScreenViewController * > UnloadCompleted
 
CYISignal< CYIAbstractScreenViewController * > PreloadFinished
 
CYISignal< CYIAbstractScreenViewController * > PreloadValidateSucceeded
 
CYISignal< CYIAbstractScreenViewController *, CYIBundlePreloadValidateFailed
 

Protected Member Functions

void SetScreenLoaded (bool isLoaded)
 
void SetInitialized (bool isInitialized)
 
virtual void OnInitScreen ()
 
virtual void OnPreloadValidateScreen (CYIBundle bundle)
 
virtual void OnPreloadScreen (CYIBundle bundle, const CYIPersistentStore &StateData)
 
virtual void OnLoadScreen (const CYIPersistentStore &StateData)
 
virtual void OnUnloadScreen (CYIPersistentStore &StateData)
 
virtual void OnStageScreen ()=0
 
virtual void OnUnstageScreen ()=0
 
- Protected Member Functions inherited from CYIViewController
virtual void BuildTimelines ()
 
void SetBeginAnimation (CYIAbstractTimeline *pAnimation, TimelineHelper::AnimationDirection direction)
 
void SetEndAnimation (CYIAbstractTimeline *pAnimation, TimelineHelper::AnimationDirection direction)
 

Additional Inherited Members

- Protected Attributes inherited from CYIViewController
CYISceneManagerm_pSceneManager
 
CYISceneViewm_pView
 
CYIAbstractTimelinem_pAnimationIn
 
CYIAbstractTimelinem_pAnimationOut
 

Member Enumeration Documentation

◆ NavigationHistoryRule

Enumerator
All 

Store all entries of this screen in the navigation history as 'back navigable'.

Last 

Only store the last consecutive "visit" to this screen as 'back navigable'.

None 

Never store this screen as 'back navigable'.

Constructor & Destructor Documentation

◆ CYIAbstractScreenViewController() [1/2]

CYIAbstractScreenViewController::CYIAbstractScreenViewController ( )

◆ CYIAbstractScreenViewController() [2/2]

CYIAbstractScreenViewController::CYIAbstractScreenViewController ( CYISceneManager pSceneManager,
CYIApp pApplication 
)

Constructs a CYIAbstractScreenViewController using the default orientation, status bar visibility and navigation bar visibility of pApplication.

See also
SetOrientation
SetStatusBarVisibility
SetNavigationBarVisibility

Member Function Documentation

◆ GetNavigationBarVisibility()

CYIScreenProperty::NavigationBar CYIAbstractScreenViewController::GetNavigationBarVisibility ( ) const

◆ GetNavigationHistoryRule()

NavigationHistoryRule CYIAbstractScreenViewController::GetNavigationHistoryRule ( ) const

◆ GetOrientation()

CYIScreenProperty::Orientation CYIAbstractScreenViewController::GetOrientation ( ) const

◆ GetStatusBarVisibility()

CYIScreenProperty::StatusBar CYIAbstractScreenViewController::GetStatusBarVisibility ( ) const

◆ GetTitle()

CYIString CYIAbstractScreenViewController::GetTitle ( ) const

Returns the title for the screen.

See also
SetTitle()

◆ Init()

virtual void CYIAbstractScreenViewController::Init ( )
overridevirtual

This function can be called anytime after the object is created. It calls CYIViewController::Init(), which requires the user to implement BuildView(). Init() is therefore potentially not very light-weight. It is important to decide when Init() should be called.

IsInitialized() will return true after this is called. If the initialized state of the screen is set to true, calls to this function will have no effect.

CYIScreenTransitionManager automatically calls Init() on the screen it is transitioning to.

Note
The user can optionally implement OnInitScreen() for additional initialization work.
See also
CYIViewController::Init()
OnInitScreen()

Reimplemented from CYIViewController.

◆ IsBackNavigationEnabled()

bool CYIAbstractScreenViewController::IsBackNavigationEnabled ( ) const

Returns true if back navigation should be enabled on the screen.

See also
SetBackNavigationEnabled()

◆ IsInboundActivityIndicatorEnabled()

bool CYIAbstractScreenViewController::IsInboundActivityIndicatorEnabled ( ) const

◆ IsInitialized()

bool CYIAbstractScreenViewController::IsInitialized ( ) const

Returns true if the screen has been initialized.

See also
SetInitialized()

The return value of this function will change if SetInitialized() is called to explicitly change the initialized state.

◆ IsLoaded()

bool CYIAbstractScreenViewController::IsLoaded ( ) const

Returns true if the screen has been loaded.

See also
SetScreenLoaded()

The return value of this function will change if SetScreenLoaded() is called to explicitly change the loaded state.

◆ Load()

void CYIAbstractScreenViewController::Load ( const CYIPersistentStore StateData)

Called by CYIScreenTransitionManager once the screen's begin animation has completed and the CYIScreenTransitionManager::ScreenTransitionDelegate has called CYIScreenTransitionManager::AppSpecificLoadingComplete(). This function calls OnLoadScreen(). IsLoaded() will return true after this is called.

Any state saved to CYIPersistentStore in Unload() when navigating away from this screen is made available when restoring this screen from the navigation history.

See also
CYIViewController::SetBeginAnimation()

◆ OnInitScreen()

virtual void CYIAbstractScreenViewController::OnInitScreen ( )
inlineprotectedvirtual

Allows the subclass to add additional initialization code. This is called by Init() after CYIViewController::Init().

Screens should avoid performing lengthy operations in this function.

◆ OnLoadScreen()

virtual void CYIAbstractScreenViewController::OnLoadScreen ( const CYIPersistentStore StateData)
inlineprotectedvirtual

Allows the subclass to perform operations to be done once the screen is shown. This is called once the begin animation has completed.

Any state saved to CYIPersistentStore in OnUnloadScreen() from navigating to a new screen is made available here when restoring this screen from the navigation history.

See also
CYIViewController::SetBeginAnimation()

◆ OnPreloadScreen()

virtual void CYIAbstractScreenViewController::OnPreloadScreen ( CYIBundle  bundle,
const CYIPersistentStore StateData 
)
inlineprotectedvirtual

Allows the subclass to perform any operations which need to be done before the screen is shown, such as setting the initial focus for the screen, or performing any loading required for the screen to be shown. When overriding this function, CYIAbstractScreenViewController::PreloadFinished must be emitted once preloading is complete.

The CYIBundle passed to CYIScreenTransitionManager::PushScreen() is passed to this function. The bundle is a copy of the original bundle. Any state saved to CYIPersistentStore in OnUnloadScreen() from navigating to a new screen is made available here when restoring this screen from the navigation history.

◆ OnPreloadValidateScreen()

virtual void CYIAbstractScreenViewController::OnPreloadValidateScreen ( CYIBundle  bundle)
inlineprotectedvirtual

Allows the subclass to perform its own validation before transitioning to this screen. This is called when a transition to this screen is initiated. When overriding this function, CYIAbstractScreenViewController::PreloadValidateSucceeded or CYIAbstractScreenViewController::PreloadValidateFailed must be emitted to indicate whether the screen should be transitioned to.

The CYIBundle passed to CYIScreenTransitionManager::PushScreen() is passed to this function. The bundle is a copy of the original bundle.

Screens should only perform operations related to validation in this function.

◆ OnStageScreen()

virtual void CYIAbstractScreenViewController::OnStageScreen ( )
protectedpure virtual

This is called immediately after unstaging the screen transition. The screen must use this function to stage itself.

Example:

void ScreenViewController::OnStageScreen()
{
m_pSceneManager->StageScene(SCREEN_NAME);
}
Note
If a view must have focus when the screen is shown users should call CYISceneView::RequestFocus on that view in OnPreloadScreen().

◆ OnUnloadScreen()

virtual void CYIAbstractScreenViewController::OnUnloadScreen ( CYIPersistentStore StateData)
inlineprotectedvirtual

Allows the subclass to perform operations to be done when navigating away from the screen. This is called if and when preload validation succeeds for the screen being navigated to. The screen will not be visible when this is called.

If the screen needs to be restored to some state when navigating back to this screen through the navigation history, any required state can be stored in StateData. The data will be made available in OnPreloadScreen() and OnLoadScreen() when navigating back to this screen.

◆ OnUnstageScreen()

virtual void CYIAbstractScreenViewController::OnUnstageScreen ( )
protectedpure virtual

This is called immediately after the end animation for this screen has finished. The screen must use this function to unstage itself.

Example:

void ScreenViewController::OnUnstageScreen()
{
}

◆ Preload()

void CYIAbstractScreenViewController::Preload ( CYIBundle  bundle,
const CYIPersistentStore StateData 
)

Called by CYIScreenTransitionManager once the CYIAbstractScreenViewController::PreloadValidateSucceeded signal is emitted. This function calls OnPreloadScreen() to allow the screen to perform any operations which need to be done before the screen is shown.

The CYIBundle passed to CYIScreenTransitionManager::PushScreen() is passed to this function. The bundle is a copy of the original bundle. Any state saved to CYIPersistentStore in Unload() when navigating away from this screen is made available when restoring this screen from the navigation history.

◆ PreloadValidate()

void CYIAbstractScreenViewController::PreloadValidate ( CYIBundle  bundle)

Called by CYIScreenTransitionManager when a transition to this screen is initiated. This function calls OnPreloadValidateScreen() to allow the screen to validate whether it is safe to transition to it.

The CYIBundle passed to CYIScreenTransitionManager::PushScreen() is passed to this function. The bundle is a copy of the original bundle.

◆ SetBackNavigationEnabled()

void CYIAbstractScreenViewController::SetBackNavigationEnabled ( bool  enabled)

Sets whether back navigation should be enabled on this screen. This is only provided as a means for the application to query this property on a per screen basis. It is not used by You.i Engine.

The default value is false.

◆ SetClearNavigationHistory()

void CYIAbstractScreenViewController::SetClearNavigationHistory ( bool  clear)

Controls whether or not the navigation history should be cleared after navigation to this screen. Setting to true will clear the navigation history after this screen has been loaded.

The default value is false.

◆ SetInboundActivityIndicatorEnabled()

void CYIAbstractScreenViewController::SetInboundActivityIndicatorEnabled ( bool  enabled)

Controls whether the activity indicator is enabled for inbound transitions to this screen. If enabled, users will see an activity indicator until this screen has completely loaded.

The presence of an "outbound" activity indicator is dictated by the corresponding setting on the screen to which the user is transitioning.

The default value is true.

◆ SetInitialized()

void CYIAbstractScreenViewController::SetInitialized ( bool  isInitialized)
protected

Sets the initialized state of the screen.

A screen can be implemented to "uninitialize" itself when it is navigated away from. Such an implementation should call this function with false so that the screen can automatically be initialized again when it is navigated to.

See also
Init()

◆ SetNavigationBarVisibility()

void CYIAbstractScreenViewController::SetNavigationBarVisibility ( CYIScreenProperty::NavigationBar  visibility)

Screens may overwrite the applications default navigation bar visibility. When a new screen is navigated to, the navigation bar visibility setting for the screen is given to the delegate for processing.

By default, the navigation bar visibility for the screen is the application's default navigation bar visibility.

See also
CYIApp::GetDefaultNavigationBarVisibility()
CYIScreenTransitionManager::ScreenTransitionDelegate::onSurfaceChangeRequested()
CYIScreenTransitionManager::ScreenTransitionDelegate::onSurfaceReady()

◆ SetNavigationHistoryRule()

void CYIAbstractScreenViewController::SetNavigationHistoryRule ( NavigationHistoryRule  rule)

Controls how this screen is stored in the navigation history.

See also
NavigationHistoryRule

◆ SetOrientation()

void CYIAbstractScreenViewController::SetOrientation ( CYIScreenProperty::Orientation  orientation)

Sets the orientation that the screen will be presented to the user in. When a new screen is navigated to, the orientation setting for the screen is given to the screen transition delegate for processing.

By default, the orientation for the screen is the application's default orientation.

See also
CYIApp::GetDefaultOrientation()
CYIScreenTransitionManager::ScreenTransitionDelegate::onSurfaceChangeRequested()
CYIScreenTransitionManager::ScreenTransitionDelegate::onSurfaceReady()

◆ SetScreenLoaded()

void CYIAbstractScreenViewController::SetScreenLoaded ( bool  isLoaded)
protected

Set whether this screen is loaded.

See also
Load()
Unload()
IsLoaded()

◆ SetStatusBarVisibility()

void CYIAbstractScreenViewController::SetStatusBarVisibility ( CYIScreenProperty::StatusBar  visibility)

Screens may overwrite the application's default status bar visibility. When a new screen is navigated to, the status bar visibility setting for the screen is given to the delegate for processing.

By default, the status bar visibility for the screen is the application's default status bar visibility.

See also
CYIApp::GetDefaultStatusBarVisibility()
CYIScreenTransitionManager::ScreenTransitionDelegate::onSurfaceChangeRequested()
CYIScreenTransitionManager::ScreenTransitionDelegate::onSurfaceReady()

◆ SetTitle()

void CYIAbstractScreenViewController::SetTitle ( const CYIString title)

Sets the title for the screen. This is only to allow an app to identify its own screens.

◆ ShouldClearNavigationHistory()

bool CYIAbstractScreenViewController::ShouldClearNavigationHistory ( ) const

◆ StartLoadAnimations()

void CYIAbstractScreenViewController::StartLoadAnimations ( )

Called by CYIScreenTransition once the screen transition has completed its animation. This function calls OnStageScreen() and Begin().

See also
CYIViewController::SetBeginAnimation()

◆ StartUnloadAnimations()

void CYIAbstractScreenViewController::StartUnloadAnimations ( )

Called by CYIScreenTransition when initiating a transition away from this screen. This function calls End().

See also
CYIViewController::SetEndAnimation()

◆ Unload()

void CYIAbstractScreenViewController::Unload ( CYIPersistentStore StateData)

Called by CYIScreenTransitionManager when transitioning away from this screen and preload validation succeeds for the screen being transitioned to. This function calls OnUnloadScreen() and emits CYIAbstractScreenViewController::UnloadCompleted before returning. IsLoaded() will return false after this is called.

If the screen needs to be restored to some state when navigating back to this screen through the navigation history, any required state can be stored in StateData.

Member Data Documentation

◆ LoadingAnimationCompleted

CYISignal<CYIAbstractScreenViewController *> CYIAbstractScreenViewController::LoadingAnimationCompleted

Emitted once the begin animation for the screen has completed.

This is used by CYIScreenTransitionManager.

See also
CYIViewController::SetBeginAnimation()

◆ PreloadFinished

CYISignal<CYIAbstractScreenViewController *> CYIAbstractScreenViewController::PreloadFinished

Should be emitted once a screen has finished its preload, including any dependent asynchronous tasks. If OnPreloadScreen() is overridden, the user has to emit this signal.

This is used by CYIScreenTransitionManager.

◆ PreloadValidateFailed

CYISignal<CYIAbstractScreenViewController *, CYIBundle> CYIAbstractScreenViewController::PreloadValidateFailed

Should be emitted if a screen is unable to complete its preload validation. If OnPreloadValidateScreen() is overridden, the user must emit this signal or CYIAbstractScreenViewController::PreloadValidateSucceeded.

This is used by CYIScreenTransitionManager.

◆ PreloadValidateSucceeded

CYISignal<CYIAbstractScreenViewController *> CYIAbstractScreenViewController::PreloadValidateSucceeded

Should be emitted if the screen successfully completed its preload validation. If OnPreloadValidateScreen() is overridden, the user has to emit this signal or CYIAbstractScreenViewController::PreloadValidateFailed

This is used by CYIScreenTransitionManager.

◆ UnloadCompleted

CYISignal<CYIAbstractScreenViewController *> CYIAbstractScreenViewController::UnloadCompleted

Emitted once the screen has finished unloading.

This is used by CYIScreenTransitionManager.

See also
Unload()

◆ UnloadingAnimationCompleted

CYISignal<CYIAbstractScreenViewController *> CYIAbstractScreenViewController::UnloadingAnimationCompleted

Emitted once the end animation for the screen has completed.

This is used by CYIScreenTransitionManager.

See also
CYIViewController::SetEndAnimation()

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