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()
#include <screen/YiAbstractScreenViewController.h>
Public Types | |
enum | NavigationHistoryRule { NavigationHistoryRule::All, NavigationHistoryRule::Last, NavigationHistoryRule::None } |
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 |
![]() | |
virtual void | BuildTimelines () |
void | SetBeginAnimation (CYIAbstractTimeline *pAnimation, TimelineHelper::AnimationDirection direction) |
void | SetEndAnimation (CYIAbstractTimeline *pAnimation, TimelineHelper::AnimationDirection direction) |
Additional Inherited Members | |
![]() | |
CYISceneManager * | m_pSceneManager |
CYISceneView * | m_pView |
CYIAbstractTimeline * | m_pAnimationIn |
CYIAbstractTimeline * | m_pAnimationOut |
CYIAbstractScreenViewController::CYIAbstractScreenViewController | ( | ) |
Constructs a CYIAbstractScreenViewController using the CYIApp and CYISceneManager from the current context.
CYIAbstractScreenViewController::CYIAbstractScreenViewController | ( | CYISceneManager * | pSceneManager, |
CYIApp * | pApplication | ||
) |
Constructs a CYIAbstractScreenViewController using the default orientation, status bar visibility and navigation bar visibility of pApplication.
CYIScreenProperty::NavigationBar CYIAbstractScreenViewController::GetNavigationBarVisibility | ( | ) | const |
NavigationHistoryRule CYIAbstractScreenViewController::GetNavigationHistoryRule | ( | ) | const |
CYIScreenProperty::Orientation CYIAbstractScreenViewController::GetOrientation | ( | ) | const |
CYIScreenProperty::StatusBar CYIAbstractScreenViewController::GetStatusBarVisibility | ( | ) | const |
CYIString CYIAbstractScreenViewController::GetTitle | ( | ) | const |
Returns the title for the screen.
|
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.
Reimplemented from CYIViewController.
bool CYIAbstractScreenViewController::IsBackNavigationEnabled | ( | ) | const |
Returns true if back navigation should be enabled on the screen.
bool CYIAbstractScreenViewController::IsInboundActivityIndicatorEnabled | ( | ) | const |
bool CYIAbstractScreenViewController::IsInitialized | ( | ) | const |
Returns true if the screen has been initialized.
The return value of this function will change if SetInitialized() is called to explicitly change the initialized state.
bool CYIAbstractScreenViewController::IsLoaded | ( | ) | const |
Returns true if the screen has been loaded.
The return value of this function will change if SetScreenLoaded() is called to explicitly change the loaded state.
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.
|
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.
|
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.
|
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.
|
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.
|
protectedpure virtual |
This is called immediately after unstaging the screen transition. The screen must use this function to stage itself.
Example:
|
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.
|
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 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.
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.
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.
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.
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.
|
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.
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.
void CYIAbstractScreenViewController::SetNavigationHistoryRule | ( | NavigationHistoryRule | rule | ) |
Controls how this screen is stored in the navigation history.
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.
|
protected |
Set whether this screen is loaded.
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.
void CYIAbstractScreenViewController::SetTitle | ( | const CYIString & | title | ) |
Sets the title for the screen. This is only to allow an app to identify its own screens.
bool CYIAbstractScreenViewController::ShouldClearNavigationHistory | ( | ) | const |
void CYIAbstractScreenViewController::StartLoadAnimations | ( | ) |
Called by CYIScreenTransition once the screen transition has completed its animation. This function calls OnStageScreen() and Begin().
void CYIAbstractScreenViewController::StartUnloadAnimations | ( | ) |
Called by CYIScreenTransition when initiating a transition away from this screen. This function calls End().
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.
CYISignal<CYIAbstractScreenViewController *> CYIAbstractScreenViewController::LoadingAnimationCompleted |
Emitted once the begin animation for the screen has completed.
This is used by CYIScreenTransitionManager.
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.
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.
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.
CYISignal<CYIAbstractScreenViewController *> CYIAbstractScreenViewController::UnloadCompleted |
Emitted once the screen has finished unloading.
This is used by CYIScreenTransitionManager.
CYISignal<CYIAbstractScreenViewController *> CYIAbstractScreenViewController::UnloadingAnimationCompleted |
Emitted once the end animation for the screen has completed.
This is used by CYIScreenTransitionManager.