CYIApp Class Reference

Detailed Description

The base class for all applications.

Typically, applications derive from the CYIApp base class and implement key methods. These methods are then called by the platform, which controls the lifecycle, timing and input for applications.

CYIApp::Init() is the entry point for the initialization process, this will trigger calls to UserInit() and UserStart() in which users can specify custom initialization steps.

CYIApp::UserUpdate() will be triggered on each application tick

#include <framework/YiApp.h>

Public Types
enum	MemoryLevel {   MemoryLevel::Moderate,   MemoryLevel::Low,   MemoryLevel::Critical }

Public Member Functions
	CYIApp ()
virtual	~CYIApp ()
bool	Init (IYIRenderer::Type rendererType=IYIRenderer::Type::Default)
bool	Init (std::unique_ptr< CYIFocusEngine > pFocusEngine, IYIRenderer::Type rendererType=IYIRenderer::Type::Default)
bool	IsInitialized () const
void	SetDefaultOrientation (CYIScreenProperty::Orientation orientation)
CYIScreenProperty::Orientation	GetDefaultOrientation () const
void	SetDefaultStatusBarVisibility (CYIScreenProperty::StatusBar statusbar)
CYIScreenProperty::StatusBar	GetDefaultStatusBarVisibility () const
void	SetDefaultNavigationBarVisibility (CYIScreenProperty::NavigationBar navigationBar)
CYIScreenProperty::NavigationBar	GetDefaultNavigationBarVisibility () const
void	HandleGraphicsContextGained ()
void	HandleGraphicsContextLost ()
CYIRenderingSurfaceInfo *	GetRenderingSurfaceInfo ()
const CYIRenderingSurfaceInfo *	GetRenderingSurfaceInfo () const
void	SurfaceWasResized (int32_t width, int32_t height, int32_t xDensity, int32_t yDensity)
void	SurfaceWasResized (int32_t width, int32_t height)
virtual CYIFrameworkConfiguration	UserConfiguration ()
virtual void	HandleKeyInputs (std::unique_ptr< CYIKeyEvent > pKeyEvent)
virtual void	HandleActionInputs (std::unique_ptr< CYIActionEvent > pActionEvent)
virtual void	HandleLowMemory (MemoryLevel memoryLevel)
bool	LoadFont (const CYIString &URI, ssize_t *pFontID, bool local=false)
bool	LoadFont (const uint8_t *pFontData, uint32_t dataSize, ssize_t *pFontID)
virtual CYISceneManager *	GetSceneManager () const
bool	PostEvent (std::unique_ptr< CYIEvent > pEvent, CYIEvent::Priority priority=CYIEvent::Priority::Default, bool bump=false)
bool	PostEvent (std::unique_ptr< CYIEvent > pEvent, CYIEventHandler *pDestination, CYIEvent::Priority priority=CYIEvent::Priority::Default, bool bump=false)
bool	SendEvent (std::unique_ptr< CYIEvent > pEvent)
bool	SendEvent (std::unique_ptr< CYIEvent > pEvent, CYIEventHandler *pDestination)
void	OnForegroundEntered ()
void	OnBackgroundEntered ()
void	Update (bool forceDirty=false, bool updateTime=true)
virtual bool	Draw ()
virtual void	OnPreDraw ()
virtual void	OnPostDraw ()
virtual void	Swap ()
void	SetHUDVisibility (bool visible)
bool	IsHUDVisible () const
CYIHud &	GetHUD ()
const CYIHud &	GetHUD () const
void	SetShowFPS (bool show)
bool	GetShowFPS () const
CYIDevPanel *	GetDevPanel () const
void	InitializeDevPanel ()
void	DestroyDevPanel ()
void	SetAssetsPath (const CYIString &assetsPath)
const CYIString &	GetAssetsPath () const
void	SetCachePath (const CYIString &cachePath)
const CYIString &	GetCachePath () const
void	SetPersistentPath (const CYIString &dataPath)
const CYIString &	GetPersistentPath () const
void	SetExternalPath (const CYIString &externalPath)
const CYIString &	GetExternalPath () const
void	SetVersion (const CYIString &version)
const CYIString &	GetVersion () const
void	SetMultiTouchEnabled (bool enabled)
bool	IsMultiTouchEnabled () const
void	SetBackgroundColor (const CYIColor &color)
const CYIColor &	GetBackgroundColor ()
void	SetRenderingThrottling (bool throttle)
bool	IsRenderingThrottled () const

Public Attributes
CYISignal< int32_t, int32_t, int32_t, int32_t >	SurfaceSizeChanged
CYISignal	ForegroundEntered
CYISignal	BackgroundEntered

Protected Member Functions
	CYIApp (CYIAppPriv *pPriv)
virtual bool	UserInit ()=0
virtual bool	UserStart ()=0
virtual void	UserUpdate ()
virtual void	OnSurfaceSizeChanged (int32_t width, int32_t height, int32_t xDensity, int32_t yDensity)

Protected Attributes
CYIAppPriv *	m_pPriv

Friends
class	CYIAppPriv

Member Enumeration Documentation

MemoryLevel

enum CYIApp::MemoryLevel

strong

Enumerator
Moderate
Low
Critical

Constructor & Destructor Documentation

CYIApp() [1/2]

CYIApp::CYIApp

(

)

~CYIApp()

virtual CYIApp::~CYIApp ( )

virtual

CYIApp() [2/2]

CYIApp::CYIApp ( CYIAppPriv *  pPriv )

protected

Member Function Documentation

DestroyDevPanel()

void CYIApp::DestroyDevPanel

(

)

Destroys the dev panel, if one exists.

Note

Use of this function requires that the debug-tools optional module be included in the app.

Draw()

virtual bool CYIApp::Draw ( )

virtual

This function draws the results of the previous Update() to the screen. If nothing has been updated, the screen buffer will not be drawn.

Returns true if a draw occurred.

GetAssetsPath()

const CYIString& CYIApp::GetAssetsPath

(

)

const

Retrieve the asset location. The data within this path should be considered read-only.

See also

SetAssetsPath

GetBackgroundColor()

const CYIColor& CYIApp::GetBackgroundColor

(

)

Returns the current app background color.

See also

SetBackgroundColor

GetCachePath()

const CYIString& CYIApp::GetCachePath

(

)

const

Retrieve the cache location. This location generally persists for the install life of the application, but the data may be cleared between application launches. Frequent writes to this location are permitted.

See also

SetCachePath

GetDefaultNavigationBarVisibility()

CYIScreenProperty::NavigationBar CYIApp::GetDefaultNavigationBarVisibility

(

)

const

GetDefaultOrientation()

CYIScreenProperty::Orientation CYIApp::GetDefaultOrientation

(

)

const

GetDefaultStatusBarVisibility()

CYIScreenProperty::StatusBar CYIApp::GetDefaultStatusBarVisibility

(

)

const

GetDevPanel()

CYIDevPanel* CYIApp::GetDevPanel

(

)

const

Returns the instance of the dev panel. May return null if such an instance doesn't exist.

Note

This function typically returns nullptr for Release builds, unless the InitializeDevPanel function has explicitly been called.

Use of this function requires that the debug-tools optional module be included in the app.

GetExternalPath()

const CYIString& CYIApp::GetExternalPath

(

)

const

Get the external storage location. This location generally persists beyond the install life of the application.

Note

The WRITE_EXTERNAL_STORAGE permission is required to read or write to this path on Android.

See also

SetExternalPath

GetHUD() [1/2]

CYIHud& CYIApp::GetHUD

(

)

Returns the CYIHud instance used by this app.

Note

Use of this function requires that the debug-tools optional module be included in the app.

GetHUD() [2/2]

const CYIHud& CYIApp::GetHUD

(

)

const

Returns the CYIHud instance used by this app.

Note

Use of this function requires that the debug-tools optional module be included in the app.

GetPersistentPath()

const CYIString& CYIApp::GetPersistentPath

(

)

const

Retrieve the data location. This location generally persists for the install life of the application.

Warning

Repeated writes to this location should be avoided if possible. Some platforms restrict how often writes can be made to the data path, and apps that write too often may fail certification. Applications that don't need truly persistent storage can use GetCachePath() instead.

See also

SetPersistentPath

GetRenderingSurfaceInfo() [1/2]

CYIRenderingSurfaceInfo* CYIApp::GetRenderingSurfaceInfo

(

)

Returns the rendering surface info object owned by this app.

GetRenderingSurfaceInfo() [2/2]

const CYIRenderingSurfaceInfo* CYIApp::GetRenderingSurfaceInfo

(

)

const

GetSceneManager()

virtual CYISceneManager* CYIApp::GetSceneManager ( ) const

virtual

Returns the scene manager for this application. The scene manager is the entry point for interacting with a 3D scene

GetShowFPS()

bool CYIApp::GetShowFPS

(

)

const

Returns true if FPS rendering is enabled, false otherwise

Deprecated:

This function has been deprecated and may be removed in a future release. IsHUDVisible should be used instead.

GetVersion()

const CYIString& CYIApp::GetVersion

(

)

const

Returns the application version string for this application object.

HandleActionInputs()

virtual void CYIApp::HandleActionInputs ( std::unique_ptr< CYIActionEvent >  pActionEvent )

virtual

Handles action input events, posting them to the event queue to be processed. If the surface is not available, no event will be posted.

Pass in the x and y coordinates of the event along with the event type, the pointer id (if applicable) and the hover flag (if applicable).

Applicable event types are: CYIEvent::Type::ActionDown CYIEvent::Type::ActionMove CYIEvent::Type::ActionUp CYIEvent::Type::ActionWheel CYIEvent::Type::ActionWheelHorizontal CYIEvent::Type::ActionWheelVertical

HandleGraphicsContextGained()

void CYIApp::HandleGraphicsContextGained

(

)

Updates the app in response to a new graphics context. Must be called by the platform implementation when the graphics context is gained and the application can begin rendering, such as when a window has been created.

Note

Calling this function redundantly, or at times besides when a new graphics context is gained, may lead to resource leaks or undefined behaviour.

HandleGraphicsContextLost()

void CYIApp::HandleGraphicsContextLost

(

)

Updates the app in response to the loss of the graphics context. Must be called by the platform implementation when the graphics context is lost and the application can no longer render, such as in the case of the window being closed or when notified by the operating system.

HandleKeyInputs()

virtual void CYIApp::HandleKeyInputs ( std::unique_ptr< CYIKeyEvent >  pKeyEvent )

virtual

Handles key input events, posting them to the event queue to be processed.

HandleLowMemory()

virtual void CYIApp::HandleLowMemory ( MemoryLevel  memoryLevel )

virtual

This may be called by the platform during low-memory conditions.

Init() [1/2]

bool CYIApp::Init

(

IYIRenderer::Type

rendererType = IYIRenderer::Type::Default

)

This function must be called by the user in the Drawing context. This function will initialize the user application along with the You.i Engine framework. This functions has hooks to UserInit() and UserStart() to allow the user insert application specific behaviour.

Init() [2/2]

bool CYIApp::Init	(	std::unique_ptr< CYIFocusEngine >	pFocusEngine,
		IYIRenderer::Type	rendererType = IYIRenderer::Type::Default
	)

This function must be called by the user in the Drawing context. This function will initialize the user application along with the You.i Engine framework. This functions has hooks to UserInit() and UserStart() to allow the user insert application specific behaviour.

InitializeDevPanel()

void CYIApp::InitializeDevPanel

(

)

Constructs an instance of the dev panel, if one doesn't exist already.

Note

Use of this function requires that the debug-tools optional module be included in the app.

IsHUDVisible()

bool CYIApp::IsHUDVisible

(

)

const

Returns true if the HUD is visible, false otherwise.

IsInitialized()

bool CYIApp::IsInitialized

(

)

const

Returns true if the application has already been initialized. On some platforms, and application can receive an event prior to You.i Engine being initialized.

IsMultiTouchEnabled()

bool CYIApp::IsMultiTouchEnabled

(

)

const

Return true if multi-touch events are being sent to the application.

IsRenderingThrottled()

bool CYIApp::IsRenderingThrottled

(

)

const

Returns true if rendering is throttled.

See also

SetRenderingThrottling

LoadFont() [1/2]

bool CYIApp::LoadFont	(	const CYIString &	URI,
		ssize_t *	pFontID,
		bool	local = false
	)

Load a font, located at the specified URI into the text engine. The font's id will be stored in pFontID. local indicates whether the path is a local path

LoadFont() [2/2]

bool CYIApp::LoadFont	(	const uint8_t *	pFontData,
		uint32_t	dataSize,
		ssize_t *	pFontID
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This function loads binary font data into the text engine.

OnBackgroundEntered()

void CYIApp::OnBackgroundEntered

(

)

Indicates that the application has entered the background. Causes the CYIApp::BackgroundEntered CYISignal to be emitted.

OnForegroundEntered()

void CYIApp::OnForegroundEntered

(

)

Indicates that the application has entered the foreground. Causes the CYIApp::ForegroundEntered CYISignal to be emitted.

OnPostDraw()

virtual void CYIApp::OnPostDraw ( )

inlinevirtual

Optional method to allow the app to draw things after You.i Engine renders, but before it swaps. This can be used to render debug information on top of everything.

This is called right after Draw()

OnPreDraw()

virtual void CYIApp::OnPreDraw ( )

inlinevirtual

Optional method to allow the app to prepare or render things before You.i Engine renders. This could be useful for example on platforms that need to render a video before everything else.

This is called before CYISceneManager::Draw(). Event processing will be complete prior to this call.

OnSurfaceSizeChanged()

virtual void CYIApp::OnSurfaceSizeChanged ( int32_t  width, int32_t  height, int32_t  xDensity, int32_t  yDensity  )

protectedvirtual

Function will be called when the surface size changes. Subclasses can use this to update their views based on the new size.

Note

Overriding without calling the base implementation will prevent the scene manager from updating for the surface size change. When the scene manager does not update for a surface size change scenes in the scene manager and the scene manager background will not ube updated to be consistent with the new surface size.

See also

CYISceneManager::OnSurfaceSizeChanged

CYISceneManager::UpdateAllScenes

CYISceneManager::UpdateBackground

PostEvent() [1/2]

bool CYIApp::PostEvent	(	std::unique_ptr< CYIEvent >	pEvent,
		CYIEvent::Priority	priority = CYIEvent::Priority::Default,
		bool	bump = false
	)

Posts an event to the event dispatcher with priority priority. If bump is true, then the event will be pushed to the top of the event queue.

PostEvent() [2/2]

bool CYIApp::PostEvent	(	std::unique_ptr< CYIEvent >	pEvent,
		CYIEventHandler *	pDestination,
		CYIEvent::Priority	priority = CYIEvent::Priority::Default,
		bool	bump = false
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SendEvent() [1/2]

bool CYIApp::SendEvent

(

std::unique_ptr< CYIEvent >

pEvent

)

Immediately dispatch an event

SendEvent() [2/2]

bool CYIApp::SendEvent	(	std::unique_ptr< CYIEvent >	pEvent,
		CYIEventHandler *	pDestination
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SetAssetsPath()

void CYIApp::SetAssetsPath

(

const CYIString &

assetsPath

)

Specify the location from which application assets will be loaded, this is generally a read-only location and will be treated as such.

Note

This function may only be called by platform implementations.

SetBackgroundColor()

void CYIApp::SetBackgroundColor

(

const CYIColor &

color

)

Sets the background color for the app which will be visible behind the bottom-most scene if it has a transparent background.

The default app background color is CYIColor::Named().Black.

SetCachePath()

void CYIApp::SetCachePath

(

const CYIString &

cachePath

)

Specify the location to which the application can cache files, the app needs write permissions to this location. The path should point to a directory that will be destroyed upon uninstallation. The data written to the specified path must persistent as long as the application is running, but may be deleted between launches if necessary. Frequent writes to this location must be permitted.

Note

This function may only be called by platform implementations.

SetDefaultNavigationBarVisibility()

void CYIApp::SetDefaultNavigationBarVisibility

(

CYIScreenProperty::NavigationBar

navigationBar

)

SetDefaultOrientation()

void CYIApp::SetDefaultOrientation

(

CYIScreenProperty::Orientation

orientation

)

SetDefaultStatusBarVisibility()

void CYIApp::SetDefaultStatusBarVisibility

(

CYIScreenProperty::StatusBar

statusbar

)

SetExternalPath()

void CYIApp::SetExternalPath

(

const CYIString &

externalPath

)

Specify the location to which the application can place persistent files. The path should point to a directory that is not destroyed upon uninstallation.

Note

This function may only be called by platform implementations.

SetHUDVisibility()

void CYIApp::SetHUDVisibility

(

bool

visible

)

Sets the visibility of the HUD.

Note

Use of this function requires that the debug-tools optional module be included in the app.

See also

CYIHud

SetMultiTouchEnabled()

void CYIApp::SetMultiTouchEnabled

(

bool

enabled

)

Specify if the application will be notified of multi-touch events. Multi touch events are disabled by default.

SetPersistentPath()

void CYIApp::SetPersistentPath

(

const CYIString &

dataPath

)

Specify the location to which the application can store files, the app needs write permissions to this location. The path should point to a directory that will be destroyed upon uninstallation. The data written to the specified path should persist between app launches. Applications will minimize writes to this location.

Note

This function may only be called by platform implementations.

SetRenderingThrottling()

void CYIApp::SetRenderingThrottling

(

bool

throttle

)

Sets whether rendering should be throttled. When throttled, the renderer will sleep to avoid exceeding 60fps.

Note

Some platforms internally limit the framerate, making throttling unnecessary.

Warning

Disabling throttling may result in higher-than-normal CPU usage.

SetShowFPS()

void CYIApp::SetShowFPS

(

bool

show

)

Enable FPS rendering

Deprecated:

This function has been deprecated and may be removed in a future release. SetHUDVisibility should be used instead.

Note

Use of this function requires that the debug-tools optional module be included in the app.

SetVersion()

void CYIApp::SetVersion

(

const CYIString &

version

)

Sets the application version string for this application object.

SurfaceWasResized() [1/2]

void CYIApp::SurfaceWasResized	(	int32_t	width,
		int32_t	height,
		int32_t	xDensity,
		int32_t	yDensity
	)

Handles available suface size changed notification. This will update the CYIRenderingSurfaceInfo and pass the notification along to the user.

See also

OnSurfaceSizeChanged

SurfaceWasResized() [2/2]

void CYIApp::SurfaceWasResized	(	int32_t	width,
		int32_t	height
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Note

This overload can used in cases where changes to surface density are not applicable. The surface density will be treated as unchanged.

Swap()

virtual void CYIApp::Swap ( )

virtual

This function will swap the contents of the back and front buffers and throttle the application's rendering to 60 frames per second. For double buffered rendering, this operation must be performed after drawing is complete. A typical frame will consist of an Update(), a Draw(), and a Swap() in that order.

Update()

void CYIApp::Update	(	bool	forceDirty = false,
		bool	updateTime = true
	)

This function updates all of the application logic and the scene tree. Rendering occurs in Draw().

forceDirty can be set to true to force a draw. This should only be done when absolutely necessary updateTime can be set to false to avoid a time update; this can be useful when an update cycle is desirable, but a time advance is not.

UserConfiguration()

virtual CYIFrameworkConfiguration CYIApp::UserConfiguration ( )

virtual

Function will be called before initialization.

The user must implement the UserConfiguration() function and return a CYIFrameworkConfiguration object in order to set any configurable pre-initialization settings.

UserInit()

virtual bool CYIApp::UserInit ( )

protectedpure virtual

This function will be called during app initialization.

UserStart()

virtual bool CYIApp::UserStart ( )

protectedpure virtual

This is guaranteed to execute as the last component after all initializations are complete, including UserInit().

UserUpdate()

virtual void CYIApp::UserUpdate ( )

inlineprotectedvirtual

Can be overridden by the user that will be called every time the application is updating its internal timers, animations and the scene tree.

Friends And Related Function Documentation

CYIAppPriv

friend class CYIAppPriv

friend

Member Data Documentation

BackgroundEntered

CYISignal CYIApp::BackgroundEntered

Emitted when the app is no longer visible to the user, generally this occurs when the user has selected another application. On most platforms after this signal is emitted the application processing is paused and no further event processing or signals will be provided to the application until it comes back in the foreground.

ForegroundEntered

CYISignal CYIApp::ForegroundEntered

Emitted when the app has come into the foreground, generally this occurs when the user has selected this application after using another. On most platforms after this signal is emitted application processing is resumed and any queued events or signals will be provided to the application.

m_pPriv

CYIAppPriv* CYIApp::m_pPriv

protected

SurfaceSizeChanged

CYISignal<int32_t , int32_t , int32_t , int32_t > CYIApp::SurfaceSizeChanged

---

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

• framework/YiApp.h