CzApp acts as a controller for the whole game or app. You should derive your own version of this class. More...

#include <CzApp.h>

Inheritance diagram for CzApp:

Public Types
enum	eSysArrayIndex { SYS_SCREEN_WIDTH = 0, SYS_SCREEN_HEIGHT = 1, SYS_SCREEN_MODE = 2, SYS_SCREEN_SIZE_HINT = 3, SYS_DEVICE_TYPE = 4, SYS_HAS_MULTITOUCH = 5, SYS_HAS_ACCELEROMETER = 6, SYS_HAS_COMPASS = 7, SYS_HAS_KEYS = 8, SYS_HAS_POINTER = 9, SYS_LAST_PURCHASE_ID = 10, SYS_SCREEN_ORIENTATION = 11, SYS_MAX = 12 }
	Indices into the XOML system array. More...
enum	eSysTouchesArrayIndex { TOUCH_POS_X0 = 0, TOUCH_POS_Y0 = 1, TOUCH_STATE0 = 2, TOUCH_POS_X1 = 3, TOUCH_POS_Y1 = 4, TOUCH_STATE1 = 5, TOUCH_POS_X2 = 6, TOUCH_POS_Y2 = 7, TOUCH_STATE2 = 8, TOUCH_POS_X3 = 9, TOUCH_POS_Y3 = 10, TOUCH_STATE3 = 11, TOUCH_POS_X4 = 12, TOUCH_POS_Y4 = 13, TOUCH_STATE4 = 14, TOUCH_MAX = 15 }
	Indices into the XOML touches system array. More...
typedef CzVector< CzScene * > ::iterator	_Iterator
Public Member Functions
_Iterator	begin ()
_Iterator	end ()
void	addScene (CzScene *scene, bool bring_to_front=true)
	Adds a scene to the app.
void	removeScene (CzScene *scene)
	Removes the scene.
void	removeScene (unsigned int name_hash)
	Removes the named scene.
void	removeAllScenes (const CzVector< CzScene * > &exclude_scenes)
	Removes all scenes except those specified.
int	findScenesOfType (int type, CzVector< CzScene * > &scenes)
	builds a list of scenes of the specified type.
CzScene *	findScene (unsigned int name_hash)
	Searches the app for a named scene.
CzScene *	findScene (const char *name)
	Searches the app for a named scene.
CzScene *	findScene (int type)
	Searches for the first scene of the specified type.
CzScene *	getScene (int index)
	Gets a scene.
void	clearScenes ()
void	changeScene (CzScene *new_scene)
	Change current scene.
bool	changeScene (unsigned int name_hash)
	Change current scene.
CzScene *	getCurrentScene ()
void	setTouchFocus (int index, CzActor *focus)
CzActor *	getTouchFocus (int index)
void	releaseTouchFocus (int index, int x, int y, bool allow_bubble=true)
	Releases the touch focus.
CzActor *	getLastTappedActor (int index)
void	setKeyFocus (CzUIBase *actor)
CzUIBase *	getKeyFocus ()
void	setTouchPanEnabled (bool enabled)
bool	isTouchPanEnabled () const
void	setMaxTouches (int max)
int	getMaxTouches () const
void	setGLCompatible (bool enable)
bool	getGLCompatible () const
const CzIVec2 &	getScreenSize () const
int	getScreenOrientation () const
float	getFrameRate () const
unsigned int	getTotalFrames () const
void	setTimePaused (bool paused)
	Pauses or un-pauses time.
bool	isTimePaused () const
virtual void	Init (bool enable_http=false, bool gl_conmpatible=false)
	Initialises the app.
virtual void	Release ()
	Releases the app.
virtual bool	Update ()
	Updates the app.
virtual void	Draw ()
	Draws the app.
virtual void	PostDraw ()
	Carries out post drawing.
virtual void	Save ()
virtual void	Load ()
void	SetBackgroundColour (uint8 r, uint8 g, uint8 b, uint8 a)
	Sets background colour.
void	BringSceneToFront (CzScene *scene)
	Bring scene to front of scene chain.
void	DisableFocus ()
	Disables focus for all scenes.
void	SetAllTimelines (CzAnimTimeline *timeline)
	Sets the timeline of all scenes.
int	LoadFromXoml (IzXomlResource parebt, bool load_children, CzXmlNode node)
virtual void	NotifyOrientationChanged ()
	Notifies scenes that the screen orientation changed.
virtual void	NotifySizeChanged ()
	Notifies scnes that the screen size changed.
Protected Member Functions
void	CreateSystemArray ()
	Creates the system XOML array.
void	ProcessTouch (int touch)
	Process a touch.
void	ProcessEvents (CzScene *scane)
	Processes key and touch events.
CzActor *	FindTappedActor (int x, int y)
	Searches for the first tapped actor.
void	UpdateSystemTouches ()
	Updates the system touches XOML array.
void	GetAppEasySettings ()
Protected Attributes
CzIVec2	ScreenSize
	Native screen size.
int	ScreenOrientation
	Orientation of screen in degrees.
CzScene *	CurrentScene
	Scene that has current input focus.
CzScene *	NextScene
	Scene that we wish to switch focus to.
CzVector< CzScene * >	Scenes
	A collection of game scenes.
CzActor *	TouchFocus [CZ_MAX_TOUCHES]
	Actor that has the current touch focus.
CzActor *	LastTappedActor [CZ_MAX_TOUCHES]
	Actor that was last tapped.
CzUIBase *	KeyFocus
	Actor that has the current key focus.
CzColour	BackgroundColour
	Background clear colour.
bool	TouchPanEnabled
	Global touch pan enabled.
int	MaxTouches
	Maximum number of tuoches to support.
bool	GLCompatible
	Determine if this game should be compatible with OpenGL commands.
float	FrameRate
	Estimated frame rate in frames per second.
unsigned int	TotalFrames
	Total number of frames that have been processed since the app began.
bool	TimePaused
	Pauses time of set to true.
CzList< CzScene * >	SceneRemovals
uint64	LastFrameTime
CzSlotArray< CzScene * >	SceneList

Detailed Description

CzApp acts as a controller for the whole game or app. You should derive your own version of this class.

Introduction

CzApp represents your app and manages all of the internals for you including the following:

Like Scenes manage Actors the CzApp class manages scenes
Managing and updating hardware sub systems such as user input, http, audio etc..
Managing and updating global resources
Stabilising frame rate
Watching for and notifying scenes about screen orientation / size change events
Layering and drawing scenes

czApp is also a singleton so you can only ever have one instance of CzApp created and running at one time during your apps life time. It also makes it accessible from anywhere within your app.

When you first begin using AppEasy Core your first job will be to create your own class that is derived from CzApp and implement the following methods:

Init() - App initialisation
Release() - App cleanup
Update() - Per frame app update
Draw() - Per frame app rendering

Creating our own App

Here is a short example showing how to derive your own CzApp Class:

App.h

class App : public CzApp
{
    CDEFINE_SINGLETON(App)

public:
    void            Init(bool enable_http);
    void            Release();
    bool            Update();
    void            Draw();
};

App.cpp

#include "App.h"

#define APP App::getInstance()  // Macros is used to provide more efficient access to the app singleton

CDECLARE_SINGLETON(App)

void App::Init(bool enable_http)
{
    CzApp::Init(enable_http);   // Init base
}

void App::Release()
{
    CzApp::Release();   // Release
}

bool App::Update()
{
    if (!CzApp::Update())   // Update the app
        return false;

    return true;
}

void App::Draw()
{
    CzApp::Draw();  // Draw the app
}

And finally we create a main.cpp that creates and runs our app:

Main.cpp

// App headers
#include "App.h"

// Include platform
#include "CzPlatform.h"

int main()
{
    CzPlatform_Create();    // Init platform

    App::Create();          // Init App
    APP->Init(true);

    while (!PLATFORM_SYS->CheckAppQuit())   // Main Loop
    {
        if (!APP->Update()) // Update App
            break;

        APP->Draw();        // Draw App
    }

    APP->Release();         // Shut down App
    App::Destroy();

    CzPlatform_Destroy();   // Shut down platform

    return 0;
}

This style of init, update, draw, cleanup is used throughuot all AppEasy Core examples.

System Variables

CzApp handles all global resources as well as the global system variables which include:

system - System related variables sych as screen height and width
touches - Touch info for each available screen touch

The system variables array is a special XOML array that contains information about the device that your app is running on. The array supports querying of the following information:

0 - Display width
1 - Display height
2 - Size hint - This is a hint that can be used to separate resources into groups that can be used across different sized screens. The calculation is based on (width + height ) / 400
3 - Standard graphics display mode name, for example HVGA, QXGVA etc..
4 - Device type
- Unsupported = -1
- iPhone = 0
- iPad = 1
- Android = 2
- Bada = 3
- QNX = 4
- Symbian = 5
- WinMobile = 6
- WebOS = 7
- Windows = 8
- OSX = 9
5 - Multi-touch - If set to 1 then device supports multi-touch
6 - Accelerometer - If set to 1 then device supports accelerometer
7 - Compass - If set to 1 then device supports compass
8 - Keys - If set to 1 then device supports keyboard
9 - HasPointer - If set to 1 then the device has touch screen / pointer support
10 – Last purchase ID – Contains the ID of the last item purchased via the Market, -1 for none

Using the system array you can style your app to fit different device configurations.

The system touches variables array is a special array that contains information about the position and state of up to 5 touches on the device. The array supports querying of the following information:

0 – Touch 1 position x
1 – Touch 1 position y
2 – Touch 1 status (1 for touching, 0 for not touching)
3 – Touch 2 position x
4 – Touch 2 position y
5 – Touch 2 status (1 for touching, 0 for not touching)
6 – Touch 3 position x
7 – Touch 3 position y
8 – Touch 3 status (1 for touching, 0 for not touching)
9 – Touch 4 position x
10 – Touch 4 position y
11 – Touch 4 status (1 for touching, 0 for not touching)
12 – Touch 5 position x
13 – Touch 5 position y
14 – Touch 5 status (1 for touching, 0 for not touching)

An example condition that checks for touch 1:

 <Variable Name="Touched1" Type="condition" Value="touches:2 == 1" />

In this example Touched1 will evaluate to true if the user touches the screen

System variables provide an easy way for XOML to change layouts and behaviours based on different system configurations.

Member Typedef Documentation

typedef CzVector<CzScene*>::iterator CzApp::_Iterator

Member Enumeration Documentation

enum CzApp::eSysArrayIndex

Indices into the XOML system array.

Enumerator:

SYS_SCREEN_WIDTH	Current screen width.
SYS_SCREEN_HEIGHT	Current screen height.
SYS_SCREEN_MODE	Graphics mode, see CzUtils.cpp for list of modes.
SYS_SCREEN_SIZE_HINT	Screen size hint (banded using (width + height) / 400 calculation to give rough idea of what size components such as fonts to use)
SYS_DEVICE_TYPE	Device type, see CzUtils.h for list of types.
SYS_HAS_MULTITOUCH	Supports multi-touch.
SYS_HAS_ACCELEROMETER	Supports accelerometer.
SYS_HAS_COMPASS	Supports compass.
SYS_HAS_KEYS	Supports keys.
SYS_HAS_POINTER	Supports pointer.
SYS_LAST_PURCHASE_ID	ID of last purchase attempt.
SYS_SCREEN_ORIENTATION	Screen orientation in degrees.
SYS_MAX	Maximum array indices.

enum CzApp::eSysTouchesArrayIndex

Indices into the XOML touches system array.

Enumerator:

TOUCH_POS_X0	Touch x-position 0.
TOUCH_POS_Y0	Touch y-position 0.
TOUCH_STATE0	Touch state 0.
TOUCH_POS_X1	Touch x-position 0.
TOUCH_POS_Y1	Touch y-position 0.
TOUCH_STATE1	Touch state 1.
TOUCH_POS_X2	Touch x-position 0.
TOUCH_POS_Y2	Touch y-position 0.
TOUCH_STATE2	Touch state 2.
TOUCH_POS_X3	Touch x-position 0.
TOUCH_POS_Y3	Touch y-position 0.
TOUCH_STATE3	Touch state 3.
TOUCH_POS_X4	Touch x-position 0.
TOUCH_POS_Y4	Touch y-position 0.
TOUCH_STATE4	Touch state 4.
TOUCH_MAX	Maximum array indices.

Member Function Documentation

void CzApp::addScene	(	CzScene *	scene,
		bool	bring_to_front = `true`
	)

Adds a scene to the app.

Adds the supplied scene to the app. If bring_to_front is true then the scene will be brought to the front of the scene stack (does not change layer ordering).

Parameters:

[in]	scene	If non-null, the scene.
	bring_to_front	true to bring scene to front.

_Iterator CzApp::begin ( ) [inline]

void CzApp::BringSceneToFront ( CzScene * scene )

Bring scene to front of scene chain.

In apps that do not use layers for ordering, its useful to be able to bring a scene to the front of the scene chain displaying it on top of all other scenes.

Parameters:

[in] scene If non-null, the scene.

void CzApp::changeScene ( CzScene * new_scene )

Change current scene.

Tells the app to change the current scene to the supplied scene on its next update.

Parameters:

[in] new_scene If non-null, the new scene.

bool CzApp::changeScene ( unsigned int name_hash )

Change current scene.

Tells the app to change the current scene to the named scene on its next update.

Parameters:

name_hash The scenes name as a string hash.

Returns:: true if it succeeds, false if it fails.

void CzApp::clearScenes ( )

void CzApp::CreateSystemArray ( ) [protected]

Creates the system XOML array.

The system XOML array is accessible from XOML. The system variables array is a special XOML array that contains information about the device that your app is running on.

void CzApp::DisableFocus ( )

Disables focus for all scenes.

Prevents all scenes from receiving input focus. This can be useful if you want to temporarily prevent user input to all scenes.

void CzApp::Draw ( ) [virtual]

Draws the app.

Renders all scenes and their contents that are currently visible. lso performs post draw update, display buffer swapping and OS yielding.

_Iterator CzApp::end ( ) [inline]

CzScene * CzApp::findScene ( unsigned int name_hash )

Searches the app for a named scene.

Parameters:

name_hash The scene name as a string hash.

Returns:: null if it fails, else the found scene.

CzScene * CzApp::findScene ( const char * name )

Searches the app for a named scene.

Parameters:

name	The scene name.

Returns:: null if it fails, else the found scene.

CzScene * CzApp::findScene ( int type )

Searches for the first scene of the specified type.

Searches for the first scene of the specified type. Its often useful to be able to search for as scene by its type, especially if you do not know its name.

Parameters:

type	The scene type.

Returns:: null if it fails, else the found scene.

int CzApp::findScenesOfType	(	int	type,
		CzVector< CzScene * > &	scenes
	)

builds a list of scenes of the specified type.

Parameters:

	type	The scene type.
[out]	scenes	[out] If non-null, the scenes list.

Returns:: Number of found scenes.

CzActor * CzApp::FindTappedActor	(	int	x,
		int	y
	)		`[protected]`

Searches for the first tapped actor.

Searches the current scene and all scenes that are allowed to receive focus to see if the supplied point lies within the boundaries of an actor. If one is found then it is returned. Actors on higher layers will be chosen over actors on lower layers.

Parameters:

x	The x screen coordinate to test.
y	The y screen coordinate to test.

Returns:: null if none fails, else the found tapped actor.

void CzApp::GetAppEasySettings ( ) [protected]

CzScene* CzApp::getCurrentScene ( ) [inline]

float CzApp::getFrameRate ( ) const [inline]

bool CzApp::getGLCompatible ( ) const [inline]

CzUIBase* CzApp::getKeyFocus ( ) [inline]

CzActor* CzApp::getLastTappedActor ( int index ) [inline]

int CzApp::getMaxTouches ( ) const [inline]

CzScene * CzApp::getScene ( int index )

Gets a scene.

Returns the scene at the specified index.

Parameters:

index Index of the scene.

Returns:: null if it fails, else the scene.

int CzApp::getScreenOrientation ( ) const [inline]

const CzIVec2& CzApp::getScreenSize ( ) const [inline]

unsigned int CzApp::getTotalFrames ( ) const [inline]

CzActor* CzApp::getTouchFocus ( int index ) [inline]

void CzApp::Init	(	bool	enable_http = `false`,
		bool	gl_conmpatible = `false`
	)		`[virtual]`

Initialises the app.

Init carries out many app start up tasks and is the first method that is called after the singleton has been instantiated. Tasks that Init() carries out include:

Sets device callbacks
Loads any AppEasy settings located in the AppEasy.xml config file
Initialises the AppEasy hardware interface sub systems
Initialises global resources system
Initialises XOML system
Creates the system XOML arrays

Parameters:

enable_http	true to enable, false to disable http support.
gl_conmpatible	true to enable, false to disable open GL compatibility mode (not used).

bool CzApp::isTimePaused ( ) const [inline]

bool CzApp::isTouchPanEnabled ( ) const [inline]

virtual void CzApp::Load ( ) [inline, virtual]

int CzApp::LoadFromXoml	(	IzXomlResource *	parebt,
		bool	load_children,
		CzXmlNode *	node
	)		`[virtual]`

Implements IzXomlResource.

void CzApp::NotifyOrientationChanged ( ) [virtual]

Notifies scenes that the screen orientation changed.

This method is called by app update when it detects a screen size / orientation change. This method notify all scenes about the event.

void CzApp::NotifySizeChanged ( ) [virtual]

Notifies scnes that the screen size changed.

This method is called by app update when it detects a screen size change. This method notify all scenes about the event.

void CzApp::PostDraw ( ) [virtual]

Carries out post drawing.

void CzApp::ProcessEvents ( CzScene * scene ) [protected]

Processes key and touch events.

Processes key events for the supplied scene. Also processes touch events for all scenes.

Parameters:

[in] scene If non-null, the scene.

void CzApp::ProcessTouch ( int index ) [protected]

Process a touch.

Processes the specified touch. if the touch has just happened then the actor that was touched will be notified via its CzActor::NotifyBeginTouch() handler. If the touch was actually a release (user taking their finger off the screen) then the focus actor will be notified via its CzActor::NotifyEndTouch() handler. If the user released the touch on an actor then the actor will be notified that the user tapped it via its CzActor::NotifyTapped() handler.

Parameters:

index Touch index.

void CzApp::Release ( ) [virtual]

Releases the app.

Release the app, shutting dowen all sub systems, deletnig all scenes etc.. but does not delete the app singelton. To delete the app object call Destroy()

void CzApp::releaseTouchFocus	(	int	index,
		int	x,
		int	y,
		bool	allow_bubble = `true`
	)

Releases the touch focus.

Release the apps current touch focus. When an actor is touched it is said to have the touch focus. Ordinarily this focus is maintained until the user lifts their finger or drags too far from the actor. Calling this method will cause the touch focus to be released and the actor that had touch focus to be notified that it should release touch focus via its CzActor::NotifyEndTouch() handler.

Parameters:

index	Touch index.
x	The x coordinate.
y	The y coordinate.
allow_bubble	true to allow, false to deny event bubbling.

void CzApp::removeAllScenes ( const CzVector< CzScene * > & exclude_scenes )

Removes all scenes except those specified.

Removes and marks for deletion all scenes in the app except the specified scenes. This method is useful for cleaning up multiple scenes at once.

Parameters:

[in] exclude_scenes If non-null, the vector of scenes to exclude.

void CzApp::removeScene ( CzScene * scene )

Removes the scene.

Removes and marks for deletion the supplied scene and all of its contents.

Parameters:

[in] scene If non-null, the scene.

void CzApp::removeScene ( unsigned int name_hash )

Removes the named scene.

Removes and marks for deletion the named scene and all of its contents.

Parameters:

name_hash The scene name as a string hash.

virtual void CzApp::Save ( ) [inline, virtual]

void CzApp::SetAllTimelines ( CzAnimTimeline * timeline )

Sets the timeline of all scenes.

Sets the animation timeline of all scenes to the supplied timeline. This is often useful if you want to fade or scroll all scenes out together.

Parameters:

[in] timeline If non-null, the timeline.

void CzApp::SetBackgroundColour	(	uint8	r,
		uint8	g,
		uint8	b,
		uint8	a
	)

Sets background colour.

Setsthe apps background colour, which is the colour of the display where nothing is rendered.

Parameters:

r	The uint8 to process.
g	The uint8 to process.
b	The uint8 to process.
a	The uint8 to process.

void CzApp::setGLCompatible ( bool enable ) [inline]

void CzApp::setKeyFocus ( CzUIBase * actor ) [inline]

void CzApp::setMaxTouches ( int max ) [inline]

void CzApp::setTimePaused ( bool paused )

Pauses or un-pauses time.

Parameters:

paused true to pause, false to un-pause.

void CzApp::setTouchFocus	(	int	index,
		CzActor *	focus
	)		`[inline]`

void CzApp::setTouchPanEnabled ( bool enabled ) [inline]

bool CzApp::Update ( ) [virtual]

Updates the app.

Updates the app including all sub systems, scenes and their contents etc.. Update() should be called each frame update. Note that Update() also takes care of deleting old unused scenes. When a scene is removed from the app it is not instantly deleted, instead it is marked as destroyed. The scene is deleted by Update() on the next frame.