You.i Engine
CYIApp Class Referenceabstract

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 ()
 
bool Init (std::unique_ptr< CYIFocusEngine > pFocusEngine)
 
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 ()
 
void SetSurface (CYISurface *pSurface)
 
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 CYISceneManagerGetSceneManager () 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 ()
 
bool Update (bool forceDirty=false, bool updateTime=true)
 
virtual void Draw ()
 
virtual void OnPreDraw ()
 
virtual void OnPostDraw ()
 
virtual void Swap ()
 
void SetHUDVisibility (bool visible)
 
bool IsHUDVisible () const
 
CYIHudGetHUD ()
 
const CYIHudGetHUD () const
 
void SetShowFPS (bool show)
 
bool GetShowFPS () const
 
CYIDevPanelGetDevPanel () const
 
void InitializeDevPanel ()
 
void DestroyDevPanel ()
 
void SetAssetsPath (const CYIString &assetsPath)
 
const CYIStringGetAssetsPath () const
 
void SetCachePath (const CYIString &cachePath)
 
const CYIStringGetCachePath () const
 
void SetDataPath (const CYIString &dataPath)
 
const CYIStringGetDataPath () const
 
void SetExternalPath (const CYIString &externalPath)
 
const CYIStringGetExternalPath () const
 
void SetVersion (const CYIString &version)
 
const CYIStringGetVersion () const
 
void SetMultiTouchEnabled (bool enabled)
 
bool IsMultiTouchEnabled () const
 
void SetBackgroundColor (const CYIColor &color)
 
const CYIColorGetBackgroundColor ()
 
void SetRenderingThrottling (bool bThrottle)
 
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

CYIAppPrivm_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 void 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 re-drawn.

◆ GetAssetsPath()

const CYIString& CYIApp::GetAssetsPath ( ) const

Retrieve the asset location. This location is generally 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. The data path will be returned if no cache path has been set, or has been set to an empty string. See also SetCachePath and SetDataPath.

◆ GetDataPath()

const CYIString& CYIApp::GetDataPath ( ) const

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

◆ 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. See also SetExternalPath

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

◆ 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.

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

◆ HandleGraphicsContextLost()

void CYIApp::HandleGraphicsContextLost ( )

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

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)

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.

◆ 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.

◆ SetDataPath()

void CYIApp::SetDataPath ( 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.

◆ 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.

◆ 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.

◆ SetRenderingThrottling()

void CYIApp::SetRenderingThrottling ( bool  bThrottle)

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.

◆ SetSurface()

void CYIApp::SetSurface ( CYISurface pSurface)

◆ 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 CYISurface 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()

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

This function updates all of the application logic and the scene tree. Rendering occurs in Draw(). Returns true if a redraw is required following the update.

forceDirty can be set to true to force a re-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: