CYIAbstractScreenViewController Class Reference

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 CYISceneNode *	GetSceneRoot () 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 Attributes
CYISignal< CYIAbstractScreenViewController * >	LoadingAnimationCompleted
CYISignal< CYIAbstractScreenViewController * >	UnloadingAnimationCompleted
CYISignal< CYIAbstractScreenViewController * >	UnloadCompleted
CYISignal< CYIAbstractScreenViewController * >	PreloadFinished
CYISignal< CYIAbstractScreenViewController * >	PreloadValidateSucceeded
CYISignal< CYIAbstractScreenViewController *, CYIBundle >	PreloadValidateFailed

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
CYISceneManager *	m_pSceneManager
CYISceneView *	m_pView
CYIAbstractTimeline *	m_pAnimationIn
CYIAbstractTimeline *	m_pAnimationOut

Member Enumeration Documentation

NavigationHistoryRule

enum CYIAbstractScreenViewController::NavigationHistoryRule

strong

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

(

)

Constructs a CYIAbstractScreenViewController using the CYIApp and CYISceneManager from the current context.

See also

CYIAppContext::GetApp

CYIApp::GetSceneManager

CYIAbstractScreenViewController(CYISceneManager *pSceneManager, CYIApp *pApplication)

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

See also

SetNavigationBarVisibility(CYIScreenProperty::NavigationBar)

GetNavigationHistoryRule()

NavigationHistoryRule CYIAbstractScreenViewController::GetNavigationHistoryRule

(

)

const

See also

SetNavigationHistoryRule(NavigationHistoryRule)

GetOrientation()

CYIScreenProperty::Orientation CYIAbstractScreenViewController::GetOrientation

(

)

const

See also

SetOrientation(CYIScreenProperty::Orientation)

GetStatusBarVisibility()

CYIScreenProperty::StatusBar CYIAbstractScreenViewController::GetStatusBarVisibility

(

)

const

See also

SetStatusBarVisibility(CYIScreenProperty::StatusBar)

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

See also

SetInboundActivityIndicatorEnabled(bool)

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()
{
    m_pSceneManager->UnstageScene(SCREEN_NAME);
}

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

See also

SetClearNavigationHistory(bool)

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:

• screen/YiAbstractScreenViewController.h