CzActor Class Reference

A basic actor. We derive different types of game / app objects from this type and add them to be processed and rendered. More...

#include <CzActor.h>

Inheritance diagram for CzActor:

List of all members.

Public Types
enum	eCzActorCategory { AC_Generic, AC_UI }
	Values that define the category of the actor. More...
Public Member Functions
void	setCategory (eCzActorCategory cat)
eCzActorCategory	getCategory () const
void	setUsed (bool in_use)
bool	isUsed () const
void	setScene (CzScene *scene)
CzScene *	getScene ()
void	setType (int type)
int	getType () const
CzIVec2	getSize () const
void	setOriginalPosition (float x, float y)
CzVec2	getOriginalPosition ()
void	setPosition (float x, float y)
	Sets actors scene position.
void	setPosition (const CzVec2 &pos)
void	setPositionX (float x)
void	setPositionY (float y)
void	setDocking (CzScene::eDocking docking)
	Sets this actors docking position.
void	setDocking (CzScene::eDocking docking, int width, int height)
	Sets this actors docking position.
CzScene::eDocking	getDocking ()
void	setMargin (int left, int right, int top, int bottom)
CzIRect	getMargin () const
void	setOriginalMargin (int left, int right, int top, int bottom)
CzVec2	getPosition ()
void	setDepth (float depth)
float	getDepth () const
void	setOrigin (float x, float y)
CzVec2	getOrigin ()
void	setOriginalAngle (float angle)
float	getOriginalAngle ()
void	setAngle (float angle)
	Sets th angle of this actor.
float	getAngle () const
void	setVelocity (float x, float y)
	Sets the linear velocity of this actor.
CzVec2	getVelocity () const
void	setVelocityDamping (float x, float y)
	Sets the linear velocity damping of this actor.
CzVec2	getVelocityDamping () const
void	setVelocityDamping (float damping)
	Sets the velocity damping of this actor.
void	setAngularVelocity (float velocity)
	Sets the angular velocity of this actor.
float	getAngularVelocity () const
void	setAngularVelocityDamping (float damping)
	Sets the angular velocity of this actor.
float	getAngularVelocityDamping () const
void	setOriginalScale (float x, float y)
CzVec2	getOriginalScale ()
void	setScale (const CzVec2 &scale)
void	setScale (float x, float y)
void	setScale (float scale)
CzVec2	getScale () const
void	setColour (uint8 r, uint8 g, uint8 b, uint8 a)
void	setColour (const CzColour &colour)
CzColour	getColour () const
CzColour	getOriginalColour () const
void	setOpacity (uint8 opacity)
int	getOpacity () const
void	setLayer (int layer)
int	getLayer () const
void	setActive (bool active)
	Sets this actor as active.
bool	isActive () const
virtual void	setVisible (bool visible, bool force_set=false)
	Makes an actor visible.
bool	isVisible () const
void	setCollidable (bool collidable)
	Makes this actor collidable.
bool	isCollidable () const
void	setTappable (bool tappable)
bool	isTappable () const
void	setDraggable (bool draggable)
bool	isDraggable () const
bool	isDragging () const
void	setReceiveEventFromChild (bool enable)
bool	canReceiveEventFromChild () const
void	setVisual (CzSprite *visual)
CzSprite *	getVisual ()
void	removeVisual ()
	Removes this actors visual.
void	setTimeline (CzAnimTimeline *timeline)
	Assigns an animation timeline to this actor.
CzAnimTimeline *	getTimeline ()
void	setBindings (CzXomlBindings *bindings)
	Assigns a bindings list to this actor.
CzXomlBindings *	getBindings ()
void	setSimpleBinding (CzXomlBinding *binding)
	Assigns a simple binding to this actor.
CzXomlBinding *	getSimpleBinding ()
void	setCollisionRect (const CzIRect &rect)
	Sets the collision rectangle of this actor.
void	setCollisionSize (int size)
	Sets this actors collision size.
CzIRect	getCollisionRect () const
int	getCollisionSize () const
void	setPreviousPosition (float x, float y)
CzVec2	getPreviousPosition () const
void	setPreviousAngle (float angle)
float	getPreviousAngle () const
void	setWrapPosition (bool enable)
bool	getWrapPosition () const
void	setLinkedTo (CzActor *actor)
	Links a child actor to a parent actor.
CzActor *	getLinkedTo ()
void	setTarget (CzActor *target)
CzActor *	getTarget ()
void	setDestroyed (bool destroyed)
bool	isDestroyed () const
void	setBox2dBody (CzBox2dBody *body)
CzBox2dBody *	getBox2dBody ()
CzActionsManager *	getActionsManager ()
CzAnimTimelinesManager *	getTimelinesManager ()
CzTimersManager *	getTimersManager ()
CzEventManager *	getEventsManager ()
void	setUserPropertyList (CzUserPropertyList *props)
CzUserPropertyList *	getUserPropertyList ()
void	setModifiers (CzModifierManager *mods)
CzModifierManager *	getModifiers ()
virtual bool	setProperty (unsigned int property_name, const CzXomlProperty &data, bool delta)
	Sets the named property of the actor.
bool	setProperty (const char *property_name, const CzString &data, bool delta)
	Sets the named property of the actor.
virtual bool	setProperty (unsigned int property_name, const CzString &data, bool delta)
	Sets the named property of the actor.
bool	getProperty (const char *property_name, CzXomlProperty &prop)
	Gets the named property of the actor.
virtual bool	getProperty (unsigned int property_name, CzXomlProperty &prop)
void	setGridPos (int x, int y)
	Changes an actors grid cell when assigned to a grid.
unsigned int	getGridPos () const
void	setScreenDocking (bool enabled)
bool	getScreenDocking () const
void	setHoldFocus (bool hold)
bool	getHoldFocus () const
void	setTouchindex (int index)
int	getTouchIndex () const
void	setUseParentOpacity (bool enable)
bool	getUseParentOpacity () const
void	setAspectLock (eCzAspectLock lock)
eCzAspectLock	getAspectLock () const
void	setPercPos (bool enable)
bool	getPercPos () const
void *	getUserData ()
void	setUserData (void *data)
bool	getOrphan () const
void	setOrphan (bool enable)
bool	getIgnoreCamera () const
virtual void	setIgnoreCamera (bool enable)
void	setTickEnabled (bool enabled)
bool	isTickEnabled () const
void	setOriginalSize (int w, int h)
	CzActor ()
virtual	~CzActor ()
	Actor destructor.
virtual void	Init ()
	Initialises this actor.
virtual void	SetFromBrush (IzBrush *brush)
virtual void	Reset ()
	Resets this actor.
virtual bool	Update (float dt)
	Updates this actors logic.
virtual bool	UpdateVisual ()
	Updates this actors visual component.
virtual void	ResolveCollisions ()
	Resolve collisions.
virtual void	NotifyCollision (CzActor *other)
	Notifies this actor that a collision has taken place.
virtual CzActor *	HitTest (float x, float y)
	hecks to see if an x,y point hits / touches the actor
virtual bool	isOutsideFocusRange (float x, float y, float scale=1.0f)
	Checks to see if the x,y point is outside the focus range.
bool	TestOverlap (CzActor *other)
	Tests for overlap between between two actors.
bool	TestOverlapRect (CzActor *other)
	Test for overlap between two actors.
virtual void	ProcessEventActions (unsigned int event_name)
	Process the event actions described by event_name.
virtual void	NotifyTapped (int index, int x, int y, bool allow_bubble)
	OnTapped event handler.
virtual void	NotifyBeginTouch (int index, int x, int y, bool allow_bubble)
	OnBeginTouch event handler.
virtual void	NotifyEndTouch (int index, int x, int y, bool allow_bubble)
	OnEndTouch event handler.
virtual void	NotifyCreate ()
	Handles the create event.
virtual void	NotifyDestroy ()
	Handles the destroy event.
virtual void	NotifyOrientationChange (CzScene::eOrientation old_orientation, CzScene::eOrientation new_orientation)
	Handles the orientation change event.
virtual void	NotifySizeChange ()
	Handles the screen size change event.
int	LoadFromXoml (IzXomlResource *parent, bool load_children, CzXmlNode *node)
	Creates an instance of this class from XOML.
bool	PostLoadFromXoml (IzXomlResource *parent, CzXmlNode *node)
	Carries out any post XOML loading tasks.
bool	UpdateFromAnimation (CzAnimInstance *animation)
	Updates actor property from supplied animation.
void	RemoveBody ()
	Removes the physics body.
CzVec2	PercPosToPos (float x, float y)
	Converts percentage based position to scene position.
float	getDistanceBetween (CzActor *actor)
	Gets distance between two actors.
float	getAngleBetween (CzActor *actor)
	Gets angle between two actors.
int	FindChildren (CzVector< CzActor * > &children)
	Finds all actors that children of this actor.
void	RemoveChildren ()
	Removes all actors that are children of this actor.
void	BringActorToFront ()
	Brings this actor to front of the scene.
void	CalculateSizes (int &width, int &height)
	Calculate size of actor if parent or screen if size not specified.
void	CalculateMargins (CzIRect &margin)
	Calculate size of margin from parent or screen if size not specified.
CzVec2	TransformPoint (float x, float y)
	Transform point.
CzVec2	TransformPointToScreen (float x, float y)
	Transform point to screen.
Static Public Member Functions
static void	InitClass ()
	Initialises the class.
static void	ReleaseClass ()
static bool	_setName (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getName (IzXomlResource *target)
static bool	_setType (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getType (IzXomlResource *target)
static bool	_setTag (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setUserData (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getUserData (IzXomlResource *target)
static CzXomlProperty	_getUserProperties (IzXomlResource *target)
static bool	_setPosition (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPosition (IzXomlResource *target)
static bool	_setPositionX (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPositionX (IzXomlResource *target)
static bool	_setPositionY (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPositionY (IzXomlResource *target)
static bool	_setPositionOrg (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setPositionOrgX (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setPositionOrgY (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setDocking (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getDocking (IzXomlResource *target)
static bool	_setMargin (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getMargin (IzXomlResource *target)
static bool	_setDepth (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getDepth (IzXomlResource *target)
static bool	_setOrigin (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getOrigin (IzXomlResource *target)
static bool	_setVelocity (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getVelocity (IzXomlResource *target)
static bool	_setVelocityDamping (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getVelocityDamping (IzXomlResource *target)
static bool	_setAngle (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getAngle (IzXomlResource *target)
static bool	_setAngularVelocity (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getAngularVelocity (IzXomlResource *target)
static bool	_setAngularVelocityDamping (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getAngularVelocityDamping (IzXomlResource *target)
static bool	_setScale (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getScale (IzXomlResource *target)
static bool	_setScaleX (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getScaleX (IzXomlResource *target)
static bool	_setScaleY (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getScaleY (IzXomlResource *target)
static bool	_setColour (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getColour (IzXomlResource *target)
static bool	_setOpacity (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getOpacity (IzXomlResource *target)
static bool	_setLayer (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getLayer (IzXomlResource *target)
static bool	_setOrphan (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getOrphan (IzXomlResource *target)
static bool	_setActive (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getActive (IzXomlResource *target)
static bool	_setVisible (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getVisible (IzXomlResource *target)
static CzXomlProperty	_getScene (IzXomlResource *target)
static bool	_setCollidable (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getCollidable (IzXomlResource *target)
static bool	_setTappable (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getTappable (IzXomlResource *target)
static bool	_setDraggable (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getDraggable (IzXomlResource *target)
static bool	_setBubbling (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getBubbling (IzXomlResource *target)
static CzXomlProperty	_getDestroyed (IzXomlResource *target)
static bool	_setWrapPosition (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getWrapPosition (IzXomlResource *target)
static bool	_setScreenDocking (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getScreenDocking (IzXomlResource *target)
static bool	_setHoldFocus (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getHoldFocus (IzXomlResource *target)
static bool	_setUseParentOpacity (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getUseParentOpacity (IzXomlResource *target)
static bool	_setPercPos (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPercPos (IzXomlResource *target)
static bool	_setIgnoreCamera (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getIgnoreCamera (IzXomlResource *target)
static bool	_setTimeline (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getTimeline (IzXomlResource *target)
static bool	_setTimeScale (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getTimeScale (IzXomlResource *target)
static bool	_setBindings (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getBindings (IzXomlResource *target)
static bool	_setBinding (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getBinding (IzXomlResource *target)
static bool	_setLinkedTo (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getLinkedTo (IzXomlResource *target)
static bool	_setTarget (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getTarget (IzXomlResource *target)
static bool	_setGridPos (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getGridPos (IzXomlResource *target)
static bool	_setLinearImpulse (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setAngularImpulse (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setForce (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setTorque (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setBox2dMaterial (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getBox2dMaterial (IzXomlResource *target)
static bool	_setShape (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setSensor (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getSensor (IzXomlResource *target)
static bool	_setCollisionFlags (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getCollisionFlags (IzXomlResource *target)
static bool	_setOnTapped (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnTapped2 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnTapped3 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnTapped4 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnTapped5 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnBeginTouch (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnBeginTouch2 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnBeginTouch3 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnBeginTouch4 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnBeginTouch5 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnEndTouch (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnEndTouch2 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnEndTouch3 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnEndTouch4 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnEndTouch5 (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnCreate (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnDestroy (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnOrientationChange (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnCollisionStart (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnCollisionEnd (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnTick (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setBodyAwake (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getBodyAwake (IzXomlResource *target)
Protected Member Functions
virtual bool	UpdateBinding (unsigned int property_name, CzXomlVariable *var)
	Updates an actor property from the supplied XOML variable.
virtual void	UpdateBindings (bool force_modified=false)
	Update data bindings.
virtual void	LinkChanged (CzActor *child, bool remove)
	Called from an actor when an actor that links to this actor unlinks itself.
CzActor *	FindEventDependentParent ()
	Events can be set up to bubble down to parents, this method finds parents that is enabled to receive touch events.
CzActor *	FindClipper ()
	Tracks back through actor parents to find any that change the clipping rect.
void	UpdateMargins ()
	Updates margin szie from original margin (used when orientation changes take place)
Protected Attributes
CzScene *	Scene
	Scene that actor lives in.
eCzActorCategory	Category
	Category of actor.
int	Type
	User defined type of Actor (use to distinguish beteeen different actor types)
CzIVec2	Size
	Visual size.
CzVec2	OriginalPosition
	Original position of actor in the scene (when actor was first spawned)
CzVec2	Position
	Current position of actor in the scene.
CzScene::eDocking	Docking
	Docking position.
CzIRect	Margin
	Margin (spacing around the actor)
float	Depth
	Parallax depth.
CzVec2	Origin
	Origin of actor.
CzVec2	Velocity
	Current velocity of actor.
CzVec2	VelocityDamping
	Dampens the velocity (Values less than 1.0f will reduce velocity over time, whilst values larger than 1.0f will increase velocity over time)
float	OriginalAngle
	Original angle in scene (when first spawned)
float	Angle
	Orientation in scene (degrees)
float	AngularVelocity
	Angular velocity.
float	AngularVelocityDamping
	Angular velocity damping.
CzVec2	OriginalScale
	Original scale of actor in the scene (when actor was first spawned)
CzVec2	Scale
	Scale.
CzColour	OriginalColour
	Original colour.
CzColour	Colour
	Colour.
int	Layer
	Depth layer.
bool	Orphan
	Actors orphaned status.
bool	Used
	Used is used when actors pooled to reduce memory fragmentation.
bool	IsActive
	Active state of actor.
bool	IsVisible
	Visible state of actor.
bool	IsCollidable
	Collidable state of actor.
bool	IsTappable
	Tappable state of actor.
bool	IsDraggable
	Draggable state of actor.
bool	IsDragging
	Dragging state of actor.
bool	ReceiveEventFromChild
	If true then this actor will receieve events from its children.
bool	WrapPosition
	If true then if position exits the extents of the scene actor will wrap back around to the opposite side of the scene.
bool	Destroyed
	An actor is marked asd destroyed when it has been marked for deletion.
bool	ScreenDocking
	if true then the actors docking value will be applied to the screen and not any parent containers that support edge docking
bool	HoldFocus
	When set to true this actor will not lose focus when the user moves out of its range.
bool	UseParentOpacity
	If true then this actors visuals opacity will be scaled by its parent, if it has one.
bool	PercentagePosition
	If true then position.
bool	IgnoreCamera
	If true then actor will not move with scene camera.
eCzAspectLock	AspectLock
	Determines which acis to use to lock aspect ratio of actors size.
CzSprite *	Visual
	Visual element that represents the actor.
CzAnimTimeline *	Timeline
	Timeline, controls animation of the actor.
CzXomlBindings *	Bindings
	Manages any attached bindings.
CzXomlBinding *	SimpleBinding
	A simple one property binding.
int	CollisionSize
	Size of collision area.
CzIRect	CollisionRect
	Spherical collision size.
float	PreviousAngle
	Previous updates angle.
CzVec2	PreviousPosition
	Previous updates position.
CzActor *	LinkedTo
	Actor that this actor links to. Linked actors will utilise their target links colour, visibility and transform etc..
CzActor *	Target
	An actor target.
int	TouchIndex
	Index of last touch on this actor.
CzBox2dBody *	Box2dBody
	Box2D physics body.
CzUserPropertyList *	UserPropertyList
	User properties list.
CzActionsManager *	ActionsManager
	Manages actions.
CzAnimTimelinesManager *	TimelinesManager
	Manages timelines.
CzTimersManager *	TimersManager
	Manages attached timers.
CzEventManager *	EventsManager
	List of events that the actor handles.
CzModifierManager *	Modifiers
	Class modifiers manager.
unsigned int	GridPos
	x, y position in grid
void *	UserData
	Extra custom data.
bool	TickEnabled
	True if OnTick event specified.
CzIVec2	OriginalSize
	Original visual size.
CzIRect	OriginalMargin
	Original margin.
CzIVec2	DragAnchor
Static Protected Attributes
static CzXomlClassDef *	ActorClassDef = NULL

---

Detailed Description

A basic actor. We derive different types of game / app objects from this type and add them to be processed and rendered.

Introduction

In the CzScene section we talked about scenes and compared them to the scenes of a movie set. Carrying on from our movie business analogy we can think of Actors as the actors and scenery objects that make up the movie scene with each actor having its own function and purpose within the scene. Actors are the central focus of all AppEasy development as they provide the actual app or game functionality and interaction that makes your game or app what it is. Actors are created inside a scene and belong to that scene. When the scene is destroyed its actors will also be destroyed.

A CzActor is a very generic object that provides quite a lot of functionality out of the box. The idea is for developers to create their own actor types from the base CzActor class then implement their own custom functionality within its Update() method. The basic functionality provided by CzActor includes:

• Support for actor pooling to help reduce memory fragmentation
• Unique names so they can be searched
• Actor types
• Size, Margin and Docking
• Position, Depth, Origin, velocity and velocity damping
• Angle, angular velocity and angular velocity damping
• Scale and Colour
• Draggable state
• Layers
• Active and visible states
• A visual that represents it on screen
• Animation timeline that can be attached to the visual
• Collision size / rectangle
• Wrapping at scenes extents
• Instantiate itself from XOML
• Other actor linkage (used to connect actors in a child / parent style system)
• A Box2D physical body consisting of a material and shape
• Box2D collision category, mask and group
• Managing and clean up of actor local animation timelines
• Managing and clean up of actor local animation timers
• Managing and clean up of actor local events / actions
• Data bindings

CzActor is derived from the IzXomlResource and IzAnimTarget interfaces which enables the actor to be declared in XOML and enables its properties to be targetted and modified by the animation system. The base CzActor has many base properties that define where, how and what the actor appears as in your app / game. For example, all actors have position, angle, scale, colour, events list etc..

AppEasy comes with many pre-defined actor types that each have their own specific purpose. For example, we have Text Actors (CzActorText) that display text, Image Actors (CzActorImage) that display images, Icon actors (CzUIIcon) that act as buttons and many more. Usually actors have a visual attached which is an object that is derived from CzSprite. CzSprite gives the actor its visual appearance on screen. For example CzBitmapSprite enables you to display the actor as an image whilst CzTextSprite enables you to display the actor as text.

Actors can also be augmented to give them additional functionality. Actors can be augmented in a number of ways including adding modifiers (IzModifier) to them which modify their behaviour, they can respond to events (CzEvent) with actions (CzActions) which in turn can affect the scene and other actors and they can run XOML programs (CzProgram) or call functions in script (CzScript) languages to create more complex behaviours. Actors can also take full advantage of the built in physics (CzBox2dBody, CzBox2dJoints, CzBox2dWorld, CzBox2dMaterial, CzBox2dCollidable) and animation systems (CzAnim) to truly bring them to life.

AppEasy provides a large array of different types of actors out of the box, but all actors are derived from 2 basic types of actors:

• ActorImage - This type of actor enables you to display images or more commonly portions of images within a scene
• ActorText - This type of actor enables you to display text using a font within a scene

All other actors that can be created are derived from these two types of actors. Now lets take a brief look at all of the other types of actors that XOML can use:

• ActorImage - Basic image actor that can display an image or brush
• ActorText - Basic text actor that can display text using specific fonts
• ActorParticles - An actor that can generate particles used for special / spot effects
• Icon - An Image actor that can also be used as a button or check box
• Label - An image actor that contains a text actor, can also be used as buttons
• VideoOverlay - An image actor that can display video content
• TextBox - A label actor that allows text entry via on screen keyboard
• Slider - Image actor that can be used as a slider control
• ListBox - A complex actor that displays a list of child actors that can be selected / toggled etc
• Grid - A complex actor that displays a grid / data grid and allows selection of cells
• Image View / Text View - Displays an image or text area that can be pinch zoomed and panned
• Web View - Displays web content
• Tab Bar - A complex actor that can be used to create navigation between different views
• Canvas, StackPanel and WrapPanel - Image actors that act as containers that arrange content in specific ways

As you can see there is a large selection of actors that you can use as-is or as a starting point to create your own actors.

Basic Actor Properties

General Properties:

• Name (string) - Name of the actor, used to refer to the actor from scripts and such. Note that no two actors in the same scene should share the same name.
• Style (style) - Provides a style that this actor should use to style its properties
• Type (number) - A numerical type that can be used to identify the type of this actor (default is 0)
• Active (boolean) - Active state (default is true), actors that are not active will not be processed
• Visible (boolean) - Visible state (default is true), actors that are not visible will not be shown on screen.
• Tappable (boolean) - If true then this actor will receive touch events when touched (default is true). IsTappable in C++
• Draggable (boolean) - When set to true the user can drag the actor around the world with their finger (default is false). IsTappable in C++
• Timeline (timeline) - The time line that should be used to animate the actor
• Bindings (bindings list) - Name of the bindings set that will be bound to this actors properties
• Binding (binding) - A simple binding that is bound to a specific property of the actor
• UserData (number) – A user data, can be used to store anything Visual Properties:
• Position (x, y) - The actors position within the scene (default is 0, 0)
• PositionX (number) - The actors position on the x-axis
• PositionY (number) - The actors position on the y-axis
• PositionOrg (x, y) - Allows setting of actors position based on the actors original position, the new position will be original_position + offset
• PositionOrgX (number) - Allows setting of actors position on the x-axis based on the actors original position, the new position will be original_position + offset
• PositionOrgY (number) - Allows setting of actors position on the y-axis based on the actors original position, the new position will be original_position + offset
• PercPos (boolean) - When set to true positions are specificity as a percentage of the devices screen size (default is false)
• Angle (degrees) - The angle of the actor (default is 0)
• Origin (x, y) - Sets the offset around which the actor will rotate and scale (default is 0,0)
• Depth (number) - Depth of the actor in 3D (larger values move the sprite further away, default is 1.0 for parent actors and 0.0 for child actors)
• Scale (x, y) - The x and y axis scale of the actor (default is 1, 1, which represents no scaling)
• ScaleX, ScaleY (number) - The separate x and y axis scale of the actor
• Colour (r, g, b, a)- The colour of the actor, Each component red, green, blue and alpha should be between the value of 0 and 255 (0 is no colour, whilst 255 is full colour, default)
• Opacity (opacity) - The opacity of the actor (how see-through the actor appears). Opacity value ranges from 0 (invisible) to 255 (fully visible, default)
• Layer (number) - The visible layer that the actor should appear on (maximum layer number is limited by the number of actor layers defined by the scene)
• Docking (dock position) - When set will dock the actor to an edge of the screen or canvas, valid values are top, left, right, bottom, topleft, topright, bottomleft and bottomright
• Margin (left, right, top, bottom) - The amount of space to leave around the actor when placed in a container or docked
• UseParentOpacity (boolean) - When set to true this actor will scale its own opacity by its parents opacity (default is true)
• IgnoreCamera (boolean) – If set to true then this actor will ignore the cameras transformation staying in place when when the camera moves, scales or rotates (default is false)
• Orphan (boolean) – If set to true then this actor will ignore its usual parentchild hierarchy when sorting by layer. This enables child actors to be sorted by layer with parent actors (default is false)

Physical Properties:

• Velocity (x, y) - Initial velocity of the actor
• VelocityDamping (x, y) - The amount to dampen velocity each frame, values of less than 1.0 will slow the actor down over time, values of greater than 1.0 will speed the actor up over time.
• AngularVelocity (number) - The rate at which the orientation of the actor changes in degrees per second
• AngularVelocityDamping (number) - The amount of rotational velocity damping to apply each frame
• WrapPosition (boolean) - If true then the actor will wrap at the edges of the canvas
• Box2dMaterial (material) - Sets the physical material type used by the Box2D actor
• Shape (shape) - Box2D fixture shape for that represents this actor during collisions
• COM (x, y) - Centre of mass of Box2D body
• Sensor (boolean) - Can be used to set the actor as a sensor (default is false)
• CollisionFlags (category, mask, group) - Box2D collision flags

Event Properties:

• OnBeginTouch (actions list) - When the user begins to touch this actor it fires this event and calls the supplied actions list. Actor also supports OnBeginTouch2 to OnBeginTouch5 representing the 2nd to 5th touches on multi-touch devices.
• OnEndTouch (actions list) - When the user stops touching this actor it fires this event and calls the supplied actions list. Actor also supports OnEndTouch2 to OnEndTouch5 representing the 2nd to 5th end touches on multi-touch devices.
• OnTapped (actions list) - When the user taps this actor it fires this event and calls the supplied actions list. Actor also supports OnTapped2 to OnTapped5 representing the 2nd to 5th taps on multi-touch devices.
• OnCreate (actions list) - When this actor is first created it fires this event and calls the supplied actions list
• OnDestroy (actions list) - When the actor is about to be destroyed it fires this event and calls the supplied actions list
• OnOrientationChange (actions list) - When the devices orientation changes it fires this event and calls the supplied actions list
• OnSizeChange (actions list) - When the devices screen size changes it fires this event and calls the supplied actions list (only valid for devices that support dynamic display / window size changing)
• OnCollisionStart (actions list) - When two actor that have Box2D physics enabled start to collide it fires this event and calls the supplied actions list (only if the actor has the iw_notifycollision modifier attached)
• OnCollisionEnd (actions list) - When two actor that have Box2D physics enabled stop colliding it fires this event and calls the supplied actions list (only if the actor has the iw_notifycollision modifier attached)
• OnTick (actions list) - Provides an actions group that is called every time the scene is updated (30 to 60 times per second)
• Bubbling (boolean) - When set to true touch events can bubble up from child actors

Miscellaneous Properties:

• GridPos (x, y) - Grid cell in which to place the actor in a grid
• LinkedTo (actor) - Name of actor that this actor links to (advanced)

Creating Actors

The usual way to create an actor is to choose which type of actor is most appropriate to the task. For example, if you want a simple game character then an CzActorImage will suffice, or maybe you want a button with a background and text, in which case a CzUILabel would be the better choice. Lets take a look at a few different ways to create a label:

XOML Example:

<Label Font="serif" Background="Button1Brush" Text="Im a label" />

Code Example:

// Find the font and brush
CzFont* font = (CzFont*)CZ_GLOBAL_RESOURCE_MANAGER->findResource("serif", CzHashes::Font_Hash);
IzBrush* background_brush = (IzBrush*)CZ_GLOBAL_RESOURCE_MANAGER->findResource("Button1Brush", CzHashes::Brush_Hash);
// Create the label
CzUILabel* label = new CzUILabel();
label->setName("label1");
scene->addActor(label);
label->Init(background, 200, 70);
CzIRect rc = CzIRect(0, 0, -100, -100);
label->InitTextActor(font, rc, "Im a label", false);

Code Example (using macros):

// Find the font and brush
CzFont* font = (CzFont*)CZ_GLOBAL_RESOURCE_MANAGER->findResource("serif", CzHashes::Font_Hash);
IzBrush* background_brush = (IzBrush*)CZ_GLOBAL_RESOURCE_MANAGER->findResource("Button1Brush", CzHashes::Brush_Hash);
// Create the label
CzIVec2 size(200, 70);
CZ_NEW_LABEL(scene, label, "label1", CzString("Im a label"), background_brush, font, size, false);

Lua Script Example:

local font = resource.find("serif", "font");
local brush = resource.find("Button1Brush", "brush");
local label_actor = actor.create("label1", scene, font, "Im a label", brush, 200, 70);

As you can see from all of the above examples, object creation in XOML is by far the easiest, most well organised and quickest approach. Lua is the 2nd, code macros the third and pure code last. We focus mainly on the XOML approach throughout most of the AppEasy documentation as it is by far the most efficient.

Actor Hierarchies

In XOML actors can be declared inside others actors to form an hierarchy (called linking). In this hierarchy actors that are declared inside other actors are called child actors, whilst the container actor is called the parent actor. You will see hierarchical actors used extensively throughout XOML, especially in regards to the user interface system. This child / parent system enables the creation of complex multi-part actors that are built from many actors. In code to make an actor the child of another actor you call setLinedTo() passing in the parent.

When you place child actors inside a parent actor the child is modified in a number of ways:

• Position, scale, rotation and depth become relative to the parent actor, so if the parent actor moves around then the child actors will follow. So for example if you set the child actors position to 0, 0 then it will be centered at the parent. If the parent rotates or scales then the child will also rotate and scale by the same rate as the parent
• The opacity of child actors will be scaled by the parent actors opacity if UseParentOpacity="true" was specified in the child actors definition. For example, if you set the parents opacity to half then all child actors will also appear at half opacity
• When a parent actor is hidden or made visible then all child actors will also be made hidden or visible
• Child actors no longer obey layer ordering and are instead layered in the order in which they are declared inside. You can override this behaviour by adding Orphan=”true” property to the actor definition
• Child actors will steal input events from the parent actor, if the parent actor is drawn before the child actors, unless the parent has Bubbling="true" set, in which case both the child actor and its parent will both receive the input event

Absolute / Percentage Positioning and Sizing

When you begin developing apps and games for mobile you will quickly discover that you need to deal with a large selection of different screen sizes, orientations and aspect ratios. The scenes virtual canvas can go a long towards helping to alleviate this problem. However (for apps in particular) its often more appropriate to render the user interface at the screens native resolution but use a series of clever layout panels to position and size content.

Actors can be positioned in a scene using two methods:

• Absolute Positioned - The position you specify is in absolute or actual scene coordinates
• Percentage Positioned - The position you specify is a percentage of the devices screen size

The default mode of actor positioning is absolute. To change an actors positioning mode to percentage based you need to add PercPos=”true” to the actors definition.

Lets take a look at an example:

XOML Example

<Label Font="serif" Text="Hello World" Position="10, 20" Size="210, 100" /> - Create a label at 10, 20 of size 200 x 100
<Label Font="serif" Text="Hello World" Position="10, 20" PercPos=”true” Size="210, 100" /> - Create a label at 10%, 20% of size 200 x 100

As wall as absolute and percentage based positioning the size of an actor can be absolute or percentage based:

• Absolute Size - The size that you specify is in absolute / actual width and height in scene coordinates
• Percentage Size - The size that you specify is a percentage of the actors parents size or if the actor has no parent a percentage of the devices screen size

The default mode of actor sizing is absolute. By passing a negative width or height you switch the actors sizing mechanism to percentage based. Lets take a look at an example:

XOML Example

<Label Font="serif" Text="Hello World" Position="0, 0" Size="-50, -50" /> - Create a label at 0, 0 of size 50% screen width and height

Using percentage based positioning and sizing with layout panels enables production of device screen size independent apps and games.

Its important to note that actors that are positioned / sized using percentages will change position / size when the devices screen orientation changes.

Docking and Margins

Its often very useful to place an actor somewhere on screen without worrying about the exact position where it needs to be placed. To solve this problem XOML introduces the concept of docking. Docking allows actors to be placed at the edge of the screen or the edge of a canvas. Lets take a look at a XOML example that shows actor docking:

XOML Example

<-- Create a bunch of docked labels:>;
<Label Font="serif" Background="Button1Brush" Size="100, 100" Text="Left" Docking="left" />
<Label Font="serif" Background="Button1Brush" Size="200, 200" Text="Right" Docking="right" />
<Label Font="serif" Background="Button1Brush" Size="150, 150" Text="Top" Docking="top" />
<Label Font="serif" Background="Button1Brush" Size="180, 180" Text="Docked" Docking="bottom" />

You can see a working example of actor docking by taking a look at the ActorDocking example.

Note that when the devices screen orientation changes docked actors will re-dock themselves to dock to the new screen edges. When an actor is docked at a screen or canvas edge you do not always want the actor to be appear right up against the edge, sometimes it looks better to leave a little space. XOML provies the Margin property that allows you to specify some space to leave around the actor. You can set the space to leave around an actor by adding Margin=”left space, right space, top space, bottom space”, where left, right, top and bottom space is the amount of space to leave around the actor. Lets revisit our previous example and add a margin to the first actor:

XOML Example

<Label Font="serif" Background="Button1Brush" Size="100, 100" Text="Left" Docking="left" Margin="20, 0, 0, 0" />

Although this actor is docked to the left hand side of the screen it is no longer clinging to the edge, instead it is pushed our by 20 units, leaving a nice gap. Margins sizes can also be specified using percentage sizing, by making margin values negative you force them to be percentage based. For example:

XOML Example

<Label Font="serif" Background="Button1Brush" Size="100, 100" Text="Left" Docking="left" Margin="-5, 0, 0, 0" />

This label now has a gap down its left hand side that is 5% of the screens width

Layers

Its customary in game and app development to have some kind of visual order in which objects appear. For example, a button should appear over the background that it sits on or the foreground in a game world should appear above the background. To accomplish this XOML uses actor layering. Each scene has a number of layers that actors can be placed on (layers 0 to 15 by default, although this can be changed in the scene definition). Actors that are placed on higher number layers will appear above actors on lower number layers. To set an actors layer you add the Layer=”layer number” property to the actor definition. e.g:

XOML Example

<Icon Name=”icon1” Background="Button1Brush" Size="250, 200" Text="Layer 7" Layer="7" />
<Icon Name=”icon2” Background="Button1Brush" Size="500, 200" Text="Layer 1" Layer="1" />

In this example, icon1 will appear above icon2 because icon1 is on layer 7 whereas icon2 is on layer 1.

Actor Origin

Sometimes we want objects to move a little differently than the norm. All actors by default spin and scale around their centre when rotated or scaled. We can modify this behaviour by moving the origin of the actor. The origin of an actor is the point around which the actor will spin and scale and by moving this origin we can change the position around which it spins and scales.

The ActorChildren example shows an example of moving the origin to change how one actor spins around another. If you pay attention to the small green cube that is orbiting Child 4 you will notice that it orbits Child 4 much like a space craft would orbit a planet. Lets take a look at the XOML for this green cube actor:

<Icon origin="0, 80" background="Button1Brush" backgroundcolour="80, 255, 80, 255" size="20, 20" angularvelocity="7.5">

In this example, we add the Origin=”0, 80” to the icon definition which pushes its centre of rotation 80 units downwards, this in turn causes the actor to have an orbital distance of 80 units from the centre of the parent actor.

Animation

Because there is a lot of focus on actors in XOML, XOML provides a number of ways to animate them. Actors can be assigned an animation timeline which contains many animations that target its properties for example (animations and timelines are covered in the animation section). Actors can also be placed under control of the physics system (covered in a later section) Besides timelines and physics, actors can be animated using linear and angular velocity. If we take a look our basic actor properties again we notice two particularly interesting properties:

• Velocity (x, y) - Initial velocity of the actor
• AngularVelocity (number) - The rate at which the orientation of the actor changes in degrees per second

These two properties allow us to set an initial linear velocity (moves the actor in a direction) and angular velocity (spins the actor at a set speed). If you one again take a look at the ActorChildren example, you will notice that each actor has an AngularVelocity property defined:

XOML Example

<Label Position="0, 0" Font="serif" Background="Button1Brush" BackgroundColour="80, 80, 255, 255" Size="100, 100" Text="Parent" AngularVelocity="1">

By setting this property we can et the actor off spinning as soon as it comes into the game world.

Dragging Actors

XOML provides a neat little feature for all actors called dragging. Any actor can be marked as dragabble by adding Draggable=”true” to the actor definition. Marking the actor as draggable allows the user to drag the actor around the screen using their finger.

Physics

There's nothing like adding realistic physics to a game to bring it to life and increase its immersion factor. To that end XOML provides out of the box physics via Box2D. Any actor can be made to use physics by simply assigning a shape and a Box2D material to it in the actor definition. This includes all actors including user interface components! Lets have a quick recap of the available properties that affect the physics of our actor:

• Velocity (x, y) - Initial velocity of the actor
• VelocityDamping (x, y) - The amount to dampen velocity each frame, values of less than 1.0 will slow the actor down over time, values of greater than 1.0 will speed the actor up over time.
• AngularVelocity (number) - The rate at which the orientation of the actor changes in degrees per second
• AngularVelocityDamping (number) - The amount of rotational velocity damping to apply each frame
• WrapPosition (boolean) - If true then the actor will wrap at the edges of the canvas
• Box2dMaterial (material) - Sets the physical material type used by the Box2D actor
• Shape (shape) - Box2D fixture shape for that represents this actor during collisions
• COM (x, y) - Centre of mass of Box2D body
• Sensor (boolean) - Can be used to set the actor as a sensor
• CollisionFlags (category, mask, group) - Box2D collision flags

Now would be a good to open up the ActorPhysics example that has been provided. Lets take a quick look at some of the important parts of the XOML for this example:

XOML Example

<Scene Name="Scene1" Current="true" Physics="true" WorldScale="1, 1" Gravity="0, 30" Camera="Camera1"> - Create a scene with physics enabled

Firstly we create a scene that can support physics by enabling physics, settings the worlds scale to 1, 1 (this means 1 scene unit is 1 physical unit) and then we set the gravity to act downwards.

XOML Example

<-- Create Box2D materials -->;
<Box2dMaterial Name="Bouncey" Type="dynamic" Density="1.0" Friction="0.3" Restitution="0.6" /> 
<Box2dMaterial Name="Heavy" Type="static" Density="2.0" Friction="0.8" Restitution="0.8" />

Next we create two box2d materials. The first is quite boucey and will be used by our bouncey box. The second material is quite solid and will represent out floor. It is also marked as a static materuial because we do not expect the floor to move. The first material is marked as dynamic becuase we expect our boncey box to move.

XOML Example

<-- Create Box2D shapes -- >;
<Shape Name="Button" Type="box" Width="100" Height="100" />
<Shape Name="Floor" Type="box" Width="1000" Height="100" />

Next we create two shapes (thes represent the physical shape of our objects). In this example we have a small box 100x100 units in size that represents our bouncey box and a much larger 1000x100 box shape that represents our solid floor.

XOML Example

<Label Position="0, 200" Font="serif" Background="Button1Brush" BackgroundColour="255, 80, 80, 255" Size="1000, 100" Text="Floor" Shape="Floor" Box2dMaterial="Heavy"
CollisionFlags="1, 1, 1" /> - Create the floor
<Label Position="-50, -180" Font="serif" Background="Button1Brush" BackgroundColour="80, 255, 255, 255" Size="100, 100" Text="Bouncey" Shape="Button" Box2dMaterial="Bouncey"
CollisionFlags="1, 1, 1" /> - Create an actor to drop onto the floor

Lastly we create a bunch of actors (we have only included the floor and one box here). The first actor (Floor) represents our floor and is assigned the Floor shape and the Heavy material. The second actor (Bouncey) is assigned the Button shape and Bouncey material.

You may by now have noticed an additional property called CollisionFlags. Collision flags are described as:

• Category - The category bits describe what type of collision object the actor is
• Mask - The mask bits describe what type of other collision objects this actor can collide with
• Group - The group index flag can be used to override category and mask, but we generally do not need to use it and usually set it to 0 for all actors.

The ActorCollisionFlags example has been provided to show how collision flags work.

The centre of mass (COM) of an actor in simple terms is the point at which the mass of the object is balanced. If the centre of mass of an object is directly at its centre then when hit towards its centre of mass by another object will generally cause it to spin around its centre. We can move the centre of mass of an actor to give the impression that the mass is centred elsewhere. For example, we may want to move the centre of mass towards the bottom of a box to make it look like it is weighted at the bottom. We can move an actors centre of mass by setting the actors COM attribute to the position of the centre of mass.

Lastly, we can mark actors as being sensors instead of interactive physical objects. When an actor collides with a sensor the sensor does not affect the actor and the actor does not physically affect the sensor. In essense a sensor is there just to detect that something has collided with it. This type of actor is good for actors that represent switches and other types of none interactive actors. To mark an actor as a sensor set Sensor=”true” in the actor definition.

Modifiers

Modifiers can be thought of as small functional building blocks that can be stacked in an actor or scene to extend the functionality of that actor or scene. For example, a typical modifier for a scene could be one that tracks the players scores / hi-scores, change day / night settings or detects special gestures. An actor modifier example could be a modifier that allows the actor move around using heading and speed or even a modifier with functionality specific to your game such as make a baddy that walks left and right on a platform. Lets take a look at how we add a modifier to an actor:

XOML Example

<ActorImage Name="Car" ........ >
    <Modifiers>
        <Modifier Name="iw_notifycollision" Active="false" Param1="0" />
    </Modifiers>
</ActorImage>

In this example we add the iw_notifycollision modifier which allows the actor to respond to collision events between actors.

A modifier accepts the following properties:

• Name - Name of the modifier
• Active - Active state of the modifier
• Param1 to Param4 - Parameters that can be passed to the modifier when it is initialised

At the moment only a few different modifiers are available for actors but more will be added over time. Lets take a look at the modifiers that are currently available.

• Collision Notification Modifier - The iw_ notifycollision modifier when attached to an actor allows it to generate and respond to collision events between actors using OnCollisionStart() and OnCollisionEnd() event handlers (See ActorModifier example for an example showing how to use this modifier). Ths modifier accepts a number of parameters which include:
  • Param1 - An optional mask that can be used to mask collision with actors by their Type. The value supplied will mask actors by type and only allow collision events to be called for those actors that pass the bit mask. For example actor 1 could have a mask of 3 and actor 2 a mask of 1. if the mask is set to 1 then both actors can collide, but if the mask was set to 3 then they could not.
• Script Modifier - the iw_callscript modifier when attached to an actor will call a function in a script each time the actor is updated. This modifier is useful as an alternative to using OnTick event handlers. This modifier accepts the following parameters:
  • Param1 - Script function name
  • Param2 to Param3 - Parameters to be passed to the script function

Future out of the box functionality will be added to XOML using modifiers.

Scripts

Whilst XOML is very powerful it does have some limits when it comes to defining very complex application / app logic, for example path finding algorithms would be quite cumbersome to create using XOML. Actors support the calling of script functions via actions in response to various events occurring. Also, as shown in the previous section, a modifier can be added to an actor that automatically calls script functions every time the actor is updated via the OnTick event, for example:

XOML Example

<Label Font="serif" Text="OnTick Example" OnTick="Update">
    <Actions Name="Update">
        <Action Method="CallScript" Param1="Actor_OnTick" />
    </Actions>
</Label>

Events

Actors can receive and react to a number of different types of events including:

• OnBeginTouch to OnBeginTouch5 - The user has began to touch the actor (up to 5 simultaneous touches)
• OnEndTouch to OnEndTouch5 - The user has stopped touching the actor (up to 5 simultaneous touches)
• OnTapped to OnTapped5 - The user tapped the actor (up to 5 simultaneous touches)
• OnCreate - The actor has been created
• OnDestroy - The actor is about to be destroyed
• OnOrientationChange - A screen orientation or size change has just taken place
• OnCollisionStart - A collision with another actor has begun
• OnCollisionEnd - A collision with another actor has ended
• OnTick - The actor is being updated

All touch events can bubble up to parent actors if the parent actor has event bubbling enabled. Event bubbling is the process of passing the same event on up to actors further up the parent-child heirearchy. Lets take a quick look at an example actor that responds to a number of different events:

XOML Example

<Label Font="serif" Text="Tap Me" Background="Button1Brush" OnTapped="Tapped" OnCreate="Created">
    <Actions Name="Created">
        <Action ....... />
        <Action ....... />
    </Actions>
    <Actions Name="Tapped">
        <Action ....... />
        <Action ....... />
    </Actions>
</Label>

Data Bindings

AppEasy supports the binding of XOML variables to properties of actors. When the variable is changed the target property of the actor is automatically updated. Actors can use bindings lists or simple bindings. A bindings list is a collection of bindings that bind specific variables to specific properties of the actor. Lets take a look at a short XOML example:

XOML Example

<!-- Create a variable that holds the labels position -->;
<Variable Name="LabelPosition" Type="vec2" Value="0, 0" />

<!-- Create a variable that holds the labels angle -->;
<Variable Name="LabelAngle" Type="float" Value="0" />

<!-- Create a data bindings list -->;
<Bindings Name="LabelBindings">
    <Binding Property="Position" Variable="LabelPosition" />
    <Binding Property="Angle" Variable="LabelAngle" />
</Bindings>

<!-- Create a label with bound data -->;
<Label Font="serif" Text="Tap Me" Background="Button1Brush" Bindings="LabelBindings" />

In the above example we create two variables, a bindings list and a label. In the bindings list we bind LabelPosition to the Position property and LabelAngle to the Angle property. We then assign the bindings list to the label actor using Bindings="LabelBindings". Now any changes to LabelPosition / LabelAngle will automatically be applied to the actors Position and Angle properties.

Simple data bindings work in much the same way except a simple binding is the binding of a single variable to a single property. Lets take a look:

XOML Example

<!-- Create a variable to track number of collisions -->;
<Variable Name="num_collisions" Type="int" Value="0" />
        
<!-- Create a label to display number of collisions -->;
<Label Font="serif" Background="Button1Brush" Docking="topleft" Binding="[Text]num_collisions" />

In this example we speciofy the property "Text" by including the prtoperty name in square brackets [Text], we then tag on the name of the bound variable. Only a single simple binding may be attached to an actor. Actors can have a bindings list and a simple binding at the same time. Note that a simple binding bound to the same property as a bindings list will take precedence over the property in the bindings list. Also note that some actor properties are two way bindings, so the actor can write values back to the variable.

Creating a Custom Actor

Whilst CzScene can be instantiated and used as-is, CzActor is abstract and cannot. The actor system is designed this way to allow th developer to create their own custom actor types that provide bespoke functionality that is specific to their game or app. Whilst AppEasy Core provides a multitide of actor types as well as ways of extending actors with the likes of modifiers (see IzModifier), in some cases the required functionality could be better achieved by deriving a new type of actor from one of the base actor types.

You begin the creation of a custom actor by deriving your own actor class from one of the actor classes then overloading the following methods to provide implementation:

• void Init()
• bool Update(float dt)
• bool UpdateVisual()

Here's a quick example:

class MyActor : public CzActor
{
public:
    MyActor() : CzActor() {}
    ~MyActor() {}

    void        Init()
    {
        CzActor::Init();
    }
    
    bool        Update(float dt)
    {
        if (!CzActor::Update(dt))
            return false;

        // Here we put our actor specific implementation

        return true;
    }

    bool        UpdateVisual()
    {
        if (!CzActor::UpdateVisual())
            return false;

        // Here we put our actor specific rendering code (if any is needed)

        return true;
    }
};

We have provided a very basic implementation of Init(), Update() and UpdateVisual() which call the base CzActor class methods so we keep its functionality in-tact.

You can take the implementation one step further by implementing both the IzXomlResource and IzAnimTarget interfaces to allow instantiation of your custom actor class from XOML and to allow your class to be a target for animation time lines.

Firstly lets take a look at XOML enabling your custom actor class. To get AppEasy to recognise your actor class whilst parsing XOML files you need to do a few things:

• Derive your class from IzXomlResource class and implement the LoadFromXoml method
• Create a class creator that creates an instance of your class then add this to the XOML engine

Lets start by taking a look at step 1.

Because we have derived our class from CzActor (which is derived from IzXomlResource) we already have the support for step 1. However we would like to insert our own custom attribute tags so we need to make a few changes.

Lets take a look at our new class with thiose changes:

class MyActor : public CzActor
{
public:
    // Properties
protected:
    int         NumberOfEyes;
public:
    void        setNumberOfEyes(int num_eyes)   { NumberOfEyes = num_eyes; }
    float       getNumberOfEyes() const         { return NumberOfEyes; }
    // Properties End
public:
    MyActor() : CzActor() {}
    ~MyActor() {}

    void        Init()
    {
        CzActor::Init();
    }
    
    bool        Update(float dt)
    {
        if (!CzActor::Update(dt))
            return false;

        // Here we put our actor specific implementation

        return true;
    }

    bool        UpdateVisual()
    {
        if (!CzActor::UpdateVisual())
            return false;

        // Here we put our actor specific rendering code (if any is needed)

        return true;
    }

    // Implementation of IzXomlResource interface
    bool            LoadFromXoml(IzXomlResource* parent, bool load_children, CzXmlNode* node)
    {
        if (!CzActor::LoadFromXoml(parent, load_children, node))    // Notice how we call the base implementation of LoadFromXoml to ensure that any base actor properties also get loaded
            return false;

        // Add our own custom attribute parsing
        for (CzXmlNode::_AttribIterator it = node->attribs_begin(); it != node->attribs_end(); it++)
        {
            unsigned int name_hash = (*it)->getName().getHash();

            if (name_hash == CzString::CalculateHash("NumberOfEyes"))
            {
                setNumberOfEyes((*it)->getValueAsInt());
            }
        }

        return true;
    }
};

Our new class now basically supports a new NumberOfEyes attribute that we will eventually be able to set in XOML using something like:

<MyActor Name="AlienCritter" Position="100, 100" Size="100, 100" NumberOfEyes="3" />

However, before we can do that we need to let the XOML system know about our new type of class (MyActor), so it can be instantiated when the XOML parser comes across it. To do this we need to create a XOML class creator:

class MyActorCreator : public IzXomlClassCreator
{
public:
    MyActorCreator()
    {
        setClassName("MyActor");
    }
    IzXomlResource* CreateInstance(IzXomlResource* parent) { return new MyActor();  }
};

The creator basically defines the tag name "MyActor" and returns an instance of the MyActor class when CreateInstance() is called.

To get the XOML system to recognise our new creator we need to add it to the XOML parsing system using:

// Add custom MyActor to XOML system
CZ_XOML->addClass(new MyActorCreator());

Now XOML integration is out of the way, lets take a quick look at enabling our class as an animation target.

To enable a class as an animation target we derive it from IzAnimTarget and implement the UpdateFromAnimation() method. Luckily we derived our MyActor class from the CzActor class which already provides this functionality. Lets take a quick look at how we extend the animation update method to account for animating our NumberOfEyes variable.

bool            UpdateFromAnimation(CzAnimInstance *animation)
{
    if (CzActor::UpdateFromAnimation(animation))    // Notice how we call the base implementation of UpdateFromAnimation to ensure that any base actor properties also get animated
        return true;

    // Add our own custom animating property
    unsigned int property_name = animation->getTargetPropertyHash();

    if (property_name == CzString::CalculateHash("NumberOfEyes"))
    {
        CzAnimFrameFloat* frame = (CzAnimFrameFloat*)animation->getCurrentData();
        setNumberOfEyes((int)frame->data);
        return true;
    }

    return false;
}

We added the above code to our MyActor class definition. We begin by calling the base UpdateFromAnimation() method so we can keep the existing animation properties of the actor. We then add our own custom check for the NumberOfEyes variable. If the animation property matches NumberOfEyes then we set the number of eyes to the provided interpolated value.

Todo:

• setProperty() needs to be replaced with CzXomlProperty instead of CzString as string conversion has to take place each time a property is set.
• Refactor setProperty(), UpdateFromAnimation(). UpdateBinding() and LoadFromXoml() so they all use a centralised update property method.
• Optimise setProperty(), getProperty(), UpdateFromAnimation(), UpdateBinding() and LoadFromXoml() to perform less comparisons (divide search by first character of property name.
• Make property system more extensible by replacing current if-then-else system with a new class property system that stores a list of available properties along with which static methods should be called to modify them. This will enable users to more easily extend derived actors.

---

Member Enumeration Documentation

enum CzActor::eCzActorCategory

Values that define the category of the actor.

Enumerator:

AC_Generic	Actor is a generic type of actor (CzActorImage or CzActorText)
AC_UI	Actor is a UI actor such as CzUIIcon, CzUILabel etc..

---

Constructor & Destructor Documentation

CzActor::CzActor

(

)

[inline]

CzActor::~CzActor

(

)

[virtual]

Actor destructor.

---

Member Function Documentation

CzXomlProperty CzActor::_getActive

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getAngle

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getAngularVelocity

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getAngularVelocityDamping

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getBinding

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getBindings

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getBodyAwake

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getBox2dMaterial

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getBubbling

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getCollidable

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getCollisionFlags

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getColour

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getDepth

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getDestroyed

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getDocking

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getDraggable

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getGridPos

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getHoldFocus

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getIgnoreCamera

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getLayer

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getLinkedTo

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getMargin

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getName

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getOpacity

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getOrigin

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getOrphan

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getPercPos

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getPosition

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getPositionX

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getPositionY

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getScale

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getScaleX

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getScaleY

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getScene

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getScreenDocking

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getSensor

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getTappable

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getTarget

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getTimeline

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getTimeScale

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getType

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getUseParentOpacity

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getUserData

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getUserProperties

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getVelocity

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getVelocityDamping

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getVisible

(

IzXomlResource *

target

)

[static]

CzXomlProperty CzActor::_getWrapPosition

(

IzXomlResource *

target

)

[static]

bool CzActor::_setActive	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setAngle	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setAngularImpulse	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setAngularVelocity	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setAngularVelocityDamping	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setBinding	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setBindings	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setBodyAwake	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setBox2dMaterial	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setBubbling	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setCollidable	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setCollisionFlags	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setColour	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setDepth	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setDocking	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setDraggable	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setForce	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setGridPos	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setHoldFocus	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setIgnoreCamera	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setLayer	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setLinearImpulse	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setLinkedTo	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setMargin	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setName	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnBeginTouch	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnBeginTouch2	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnBeginTouch3	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnBeginTouch4	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnBeginTouch5	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnCollisionEnd	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnCollisionStart	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnCreate	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnDestroy	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnEndTouch	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnEndTouch2	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnEndTouch3	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnEndTouch4	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnEndTouch5	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnOrientationChange	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnTapped	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnTapped2	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnTapped3	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnTapped4	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnTapped5	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOnTick	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOpacity	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOrigin	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setOrphan	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setPercPos	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setPosition	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setPositionOrg	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setPositionOrgX	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setPositionOrgY	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setPositionX	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setPositionY	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setScale	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setScaleX	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setScaleY	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setScreenDocking	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setSensor	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setShape	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setTag	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setTappable	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setTarget	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setTimeline	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setTimeScale	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setTorque	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setType	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setUseParentOpacity	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setUserData	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setVelocity	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setVelocityDamping	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setVisible	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

bool CzActor::_setWrapPosition	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		[static]

void CzActor::BringActorToFront

(

)

Brings this actor to front of the scene.

Removes the actor from the scene and adds it at the end of the scenes actor list. This causes the actor to be placed above any other actors that are on the same layer.

void CzActor::CalculateMargins

(

CzIRect &

margin

)

Calculate size of margin from parent or screen if size not specified.

Calculates the size of the actors margins.

A utiliy method tha calculates the size of the actors margins based on the supplied size. If a negative value is supplied then it will be classed as a perctnage based size and will be calculated from the size of the actors parent or screen size if the actor has no parent.

Parameters:

[in,out]

margin

The margin.

void CzActor::CalculateSizes	(	int &	width,
		int &	height
	)

Calculate size of actor if parent or screen if size not specified.

Calculates the size of the actor.

A utiliy method tha calculates the size of the actor based on the supplied size. If a negative value is supplied then it will be classed as a perctnage based size and will be calculated from the size of the actors parent or screen size if the actor has no parent.

Parameters:

[in,out]	width	The width.
[in,out]	height	The height.

bool CzActor::canReceiveEventFromChild

(

)

const [inline]

int CzActor::FindChildren

(

CzVector< CzActor * > &

children

)

Finds all actors that children of this actor.

Searches this actors scene for all actors that link to it (actors that are children) and places them into the provided children vector.

Parameters:

[out]

children

[out] If non-null, the children.

Returns:

The number of children.

CzActor * CzActor::FindClipper

(

)

[protected]

Tracks back through actor parents to find any that change the clipping rect.

Searches up the actor heirarchy for an actor that is a clipper.

Starting from this actor, searches up the actor hierarchy for an actor that is a clipper. An actor that is a clipper is an actor that clips its children against its bounds. Clippers are used extensively by the UI actior system with container actors clipping their child actors against their bounds.

Returns:

null if it fails, else actor that is a clipper.

CzActor * CzActor::FindEventDependentParent

(

)

[protected]

Events can be set up to bubble down to parents, this method finds parents that is enabled to receive touch events.

Finds the event dependent parent of this actor.

Utility method that searches up the actor hierarchy to find the first parent that can receive events from its childen. Actors can be made to bubble events up their heirarchy to parent actors so they can also receieve the same events. This method will find the first parent that can receieve bubbled events. Below is an example actor that shows event bubbling:

Example

    <StackPanel orientation="Vertical" bubbling="true">
        <Label .... />
    </StackPanel>
 

In the above example the label and the StackPanel can both receive input events as the StackPanel parent has event bubbling enabled.

Returns:

null if it fails, else the parent that can receive events from its children.

CzActionsManager* CzActor::getActionsManager

(

)

[inline]

float CzActor::getAngle

(

)

const [inline]

float CzActor::getAngleBetween

(

CzActor *

actor

)

Gets angle between two actors.

Calculates the angle between this actor and another.

Parameters:

[in]

actor

If non-null, the actor.

Returns:

The angle between the two actors in degrees

float CzActor::getAngularVelocity

(

)

const [inline]

float CzActor::getAngularVelocityDamping

(

)

const [inline]

eCzAspectLock CzActor::getAspectLock

(

)

const [inline]

CzXomlBindings* CzActor::getBindings

(

)

[inline]

CzBox2dBody* CzActor::getBox2dBody

(

)

[inline]

eCzActorCategory CzActor::getCategory

(

)

const [inline]

CzIRect CzActor::getCollisionRect

(

)

const [inline]

int CzActor::getCollisionSize

(

)

const [inline]

CzColour CzActor::getColour

(

)

const [inline]

float CzActor::getDepth

(

)

const [inline]

float CzActor::getDistanceBetween

(

CzActor *

actor

)

Gets distance between two actors.

Calculates the euclidean distance between this actor and another.

Parameters:

[in]

actor

If non-null, the actor.

Returns:

The distance between the two actors.

CzScene::eDocking CzActor::getDocking

(

)

[inline]

CzEventManager* CzActor::getEventsManager

(

)

[inline]

unsigned int CzActor::getGridPos

(

)

const [inline]

bool CzActor::getHoldFocus

(

)

const [inline]

bool CzActor::getIgnoreCamera

(

)

const [inline]

int CzActor::getLayer

(

)

const [inline]

CzActor* CzActor::getLinkedTo

(

)

[inline]

CzIRect CzActor::getMargin

(

)

const [inline]

CzModifierManager* CzActor::getModifiers

(

)

[inline]

int CzActor::getOpacity

(

)

const [inline]

CzVec2 CzActor::getOrigin

(

)

[inline]

float CzActor::getOriginalAngle

(

)

[inline]

CzColour CzActor::getOriginalColour

(

)

const [inline]

CzVec2 CzActor::getOriginalPosition

(

)

[inline]

CzVec2 CzActor::getOriginalScale

(

)

[inline]

bool CzActor::getOrphan

(

)

const [inline]

bool CzActor::getPercPos

(

)

const [inline]

CzVec2 CzActor::getPosition

(

)

[inline]

float CzActor::getPreviousAngle

(

)

const [inline]

CzVec2 CzActor::getPreviousPosition

(

)

const [inline]

bool CzActor::getProperty	(	const char *	property_name,
		CzXomlProperty &	prop
	)

Gets the named property of the actor.

Returns the named property of the actor. The properties value is returned in a CzXomlProperty which is a structure that contains a union of all possible property types.

Parameters:

	property_name	Name of the property.
[out]	prop	The property data.

Returns:

true if it succeeds, false if property does not exist.

bool CzActor::getProperty	(	unsigned int	property_name,
		CzXomlProperty &	prop
	)		[virtual]

Returns the named property of the actor. The properties value is returned in a CzXomlProperty which is a structure that contains a union of all possible property types.

Parameters:

	property_name	Name of the property as a string hash (faster searching).
[in,out]	prop	The property.

Returns:

true if it succeeds, false if property does not exist.

Reimplemented in CzActorParticles, CzUITabBar, CzUIBase, CzUIGrid, CzUIListBox, CzActorText, CzActorImage, CzActorConnector, CzUIImageView, CzUISlider, CzActorTilemap, CzUILabel, CzUITextView, CzUIWebView, CzUITab, CzUITextBox, CzUIVideoOverlay, CzUIStackPanel, and CzUIWrapPanel.

CzVec2 CzActor::getScale

(

)

const [inline]

CzScene* CzActor::getScene

(

)

[inline]

bool CzActor::getScreenDocking

(

)

const [inline]

CzXomlBinding* CzActor::getSimpleBinding

(

)

[inline]

CzIVec2 CzActor::getSize

(

)

const [inline]

CzActor* CzActor::getTarget

(

)

[inline]

CzAnimTimeline* CzActor::getTimeline

(

)

[inline]

CzAnimTimelinesManager* CzActor::getTimelinesManager

(

)

[inline]

CzTimersManager* CzActor::getTimersManager

(

)

[inline]

int CzActor::getTouchIndex

(

)

const [inline]

int CzActor::getType

(

)

const [inline]

bool CzActor::getUseParentOpacity

(

)

const [inline]

void* CzActor::getUserData

(

)

[inline]

CzUserPropertyList* CzActor::getUserPropertyList

(

)

[inline]

CzVec2 CzActor::getVelocity

(

)

const [inline]

CzVec2 CzActor::getVelocityDamping

(

)

const [inline]

CzSprite* CzActor::getVisual

(

)

[inline]

bool CzActor::getWrapPosition

(

)

const [inline]

CzActor * CzActor::HitTest	(	float	x,
		float	y
	)		[virtual]

hecks to see if an x,y point hits / touches the actor

Checks to see if the supplied point is within the area that the actors visual covers. Testing is done in screen coordinares

Parameters:

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

Returns:

null if it no hit, else actor that was hit.

void CzActor::Init

(

)

[virtual]

Initialises this actor.

Places the actor into an initialised and usable state. Most other actor classes override this method and take care of per actor initialisation.

void CzActor::InitClass

(

)

[static]

Initialises the class.

Sets up the classes avaiiable properties. Used by the XOML system to find, set amd get class properties.

Reimplemented in CzActorParticles, CzUIBase, CzUITabBar, CzUIGrid, CzUIListBox, CzActorImage, CzActorText, CzUIWebView, CzActorConnector, CzUIImageView, CzUISlider, CzUITextView, CzUILabel, CzActorTilemap, CzUITab, CzUIVideoOverlay, CzUITextBox, CzUIStackPanel, and CzUIWrapPanel.

bool CzActor::isActive

(

)

const [inline]

bool CzActor::isCollidable

(

)

const [inline]

bool CzActor::isDestroyed

(

)

const [inline]

bool CzActor::isDraggable

(

)

const [inline]

bool CzActor::isDragging

(

)

const [inline]

bool CzActor::isOutsideFocusRange	(	float	x,
		float	y,
		float	scale = 1.0f
	)		[virtual]

Checks to see if the x,y point is outside the focus range.

Checks the point x, y to see if it is outside the focus range of the actor. The focus range is calculated as the radius of the visual multiplied by scale. Focus range is used to decide when to release the touch focus on an actor that currently has touch focus.

Parameters:

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

Returns:

true if outside focus range, false if not.

bool CzActor::isTappable

(

)

const [inline]

bool CzActor::isTickEnabled

(

)

const [inline]

bool CzActor::isUsed

(

)

const [inline]

bool CzActor::isVisible

(

)

const [inline]

virtual void CzActor::LinkChanged	(	CzActor *	child,
		bool	remove
	)		[inline, protected, virtual]

Called from an actor when an actor that links to this actor unlinks itself.

Reimplemented in CzUITabBar, CzUIGrid, CzUIListBox, CzUICanvas, and CzUIPanel.

int CzActor::LoadFromXoml	(	IzXomlResource *	parent,
		bool	load_children,
		CzXmlNode *	node
	)		[virtual]

Creates an instance of this class from XOML.

LoadFromXoml is the main method used by all classes that can be instantiated from XOML mark-up. This method creates an instance of this class from the supplied XML node structure specified by node. if parent is not NULL then the created instance will utilise the supplied parent to determine where it should live within the app. For example, if the parent is a scene then the actor will be placed in that scene. if the parent is another actor then this actor will be placed into the scene of the supplied actor and linked as a child to the parent actor. If load_chlldren is true then any child nodes contained within the actor will also be loaded.

Parameters:

[in]	parent	If non-null, the parent.
	load_children	true to load child nodes.
[in]	node	If non-null, the XOML markup node that defines this object

Returns:

nergative value for error. if 0 then processing of further XOML will stop.

Implements IzXomlResource.

Reimplemented in CzActorParticles, CzUIBase, CzUITabBar, CzUIGrid, CzUIListBox, CzUITabs, CzActorImage, CzActorText, CzUIWebView, CzActorConnector, CzUIImageView, CzUISlider, CzUITextView, CzUILabel, CzActorTilemap, CzUITab, CzUITextBox, CzUIVideoOverlay, CzUIStackPanel, CzUIWrapPanel, and CzUICanvas.

void CzActor::NotifyBeginTouch	(	int	index,
		int	x,
		int	y,
		bool	allow_bubble
	)		[virtual]

OnBeginTouch event handler.

The OnBeginTouch event handler is called whenever the user begins to touch the actor. Actors can process up to 5 simultaneous touch events OnBeginTouch to OnBeginTouch5. if event bubbling is enabled then the event will also be passed up to the parent.

Parameters:

index	Index of the touch.
x	The touched x coordinate.
y	The touched y coordinate.
allow_bubble	true to allow event bubbling, false to deny event bubbling.

Reimplemented in CzUIBase, CzUIImageView, CzUITextView, and CzUISlider.

void CzActor::NotifyCollision

(

CzActor *

other

)

[virtual]

Notifies this actor that a collision has taken place.

This method is usually implemented by actors that wnat to know when a collision nivolving them takes place. This method is usually called by the actor that hit this actor.

Parameters:

[in,out]

other

If non-null, the other.

void CzActor::NotifyCreate

(

)

[virtual]

Handles the create event.

When an actor is created it will raise the OnCreate event. This can be used to call actions or do other post actor creation huose keeping.

void CzActor::NotifyDestroy

(

)

[virtual]

Handles the destroy event.

When an actor is about to be destroyed it will raise the OnDestroy event. This can be used to call actions or do other pre actor destruction house keeping.

void CzActor::NotifyEndTouch	(	int	index,
		int	x,
		int	y,
		bool	allow_bubble
	)		[virtual]

OnEndTouch event handler.

The OnEndTouch event handler is called whenever the user stops touching the actor. This can occur for a number fo reasons including:

• if the user lifts their finger off the actor
• If the user moves their finger too from the actor (loses focus)
• if the user scrolls the container (list boc for example)
• The scene is switched

Actors can process up to 5 simultaneous touch events OnEndTouch to OnEndTouch5. if event bubbling is enabled then the event will also be passed up to the parent.

Parameters:

index	Index of the touch.
x	The touched x coordinate.
y	The touched y coordinate.
allow_bubble	true to allow event bubbling, false to deny event bubbling.

Reimplemented in CzUIBase, CzUIImageView, CzUITextView, and CzUISlider.

void CzActor::NotifyOrientationChange	(	CzScene::eOrientation	old_orientation,
		CzScene::eOrientation	new_orientation
	)		[virtual]

Handles the orientation change event.

When a screen orientation or size change occurs all actors will receive this event enabling them to modify themselves to take advantage of the new screen orientation / size. This default implementation will update the actors position and call any attached OnOrientationChange actions.

Parameters:

old_orientation	The old orientation.
new_orientation	The new orientation.

When a screen orientation or size change occurs all actors will receive this event enabling them to modify themselves to take advantage of the new screen orientation / size.

Parameters:

old_orientation	The old orientation.
new_orientation	The new orientation.

Reimplemented in CzUIBase, CzUIGrid, CzActorImage, CzActorText, CzUIWebView, CzUISlider, and CzUITab.

void CzActor::NotifySizeChange

(

)

[virtual]

Handles the screen size change event.

When a screen size change (not orientation change) occurs all actors will receive this event enabling them to modify themselves to take advantage of the new screen size. This default implementation will update the actors position and call any attached OnSizeChange actions.

void CzActor::NotifyTapped	(	int	index,
		int	x,
		int	y,
		bool	allow_bubble
	)		[virtual]

OnTapped event handler.

The OnTapped event handler is called whenever the actor is tapped on by the user. Actors can process up to 5 simultaneous touch events OnTapped to OnTapped5. if event bubbling is enabled then the event will also be passed up to the parent.

Parameters:

index	Index of the touch.
x	The touched x coordinate.
y	The touched y coordinate.
allow_bubble	true to allow event bubbling, false to deny event bubbling.

Reimplemented in CzUIBase, and CzUITextBox.

CzVec2 CzActor::PercPosToPos	(	float	x,
		float	y
	)

Converts percentage based position to scene position.

Utility method that converts the supplied percentage based position to screen position.

Parameters:

x	The x coordinate as a percentage.
y	The y coordinate as a percentage.

Returns:

Screen position.

bool CzActor::PostLoadFromXoml	(	IzXomlResource *	parent,
		CzXmlNode *	node
	)		[virtual]

Carries out any post XOML loading tasks.

PostLoadFromXoml adds the opportunity to carry out post load events, such as when the actor has finished loading all of its child nodes. Often timelines and actions list are specified as child nodes of an actor. These will not be available in resource manager until the actors has finished loading, so the creation process cannot deal with them until after the actor has been fully loaded. PostLoadFromXoml also fires the OnCreate event to notify XOML that the actor has been fully loaded.

Parameters:

[in,out]	parent	If non-null, the parent.
[in,out]	node	If non-null, the node.

Returns:

true if it succeeds, false if it fails.

Reimplemented from IzXomlResource.

void CzActor::ProcessEventActions

(

unsigned int

event_name

)

[virtual]

Process the event actions described by event_name.

Processes the actions list that is associated with the event named event_name (event_name is a hash of the actual event name to speed up searches)

Parameters:

event_name

Name of the event as a string hash

void CzActor::ReleaseClass

(

)

[static]

Reimplemented in CzActorParticles, CzUIBase, CzUITabBar, CzUIGrid, CzUIListBox, CzActorImage, CzActorText, CzUIWebView, CzActorConnector, CzUIImageView, CzUISlider, CzUITextView, CzUILabel, CzActorTilemap, CzUITab, CzUIVideoOverlay, CzUITextBox, CzUIStackPanel, and CzUIWrapPanel.

void CzActor::RemoveBody

(

)

Removes the physics body.

Removes the physics body that is associatd with this actor. Also sets all velocities to 0.

void CzActor::RemoveChildren

(

)

Removes all actors that are children of this actor.

Searches the scene for actors that are children of this actor, removes them from the scene and deletes them. Note that whilst an actor is immediately removed from the scene it is not deleted until the scene has finished being processed and the actor clean up stage takes place. In the meantime the actor is marked as Destroyed.

void CzActor::removeVisual

(

)

Removes this actors visual.

If the actor has a visual then it will be removed and deleted.

void CzActor::Reset

(

)

[virtual]

Resets this actor.

In a system where actor objects are "re-used", such as in some kind of actor pooling system its often handy to be able to reset the actor into a default state so that the actor can be re-used. Memory pooling system pre-allocate a group of objects and re-use them instead of constantly creating and destroying them. Reset offers a way to reset the actor to its default state so it can be re-used.

void CzActor::ResolveCollisions

(

)

[virtual]

Resolve collisions.

Derived actors that are interested in collision implement this method to determine what they could have collided with. There is no base implementation for this method.

Here is a short example that shows:

Example

    void ActorPlayer::ResolveCollisions()
    {
        for (CzScene::_Iterator it = Scene->begin(); it != Scene->end(); ++it) // Walk the scenes actors
        {
            if ((*it)->getType() == 1)              // Only test collision against ball type actors
            {
                if (CheckCollision(*it))            // Check for physical collision
                {
                    NotifyCollision(*it);           // Notify ourselves that we collided with ball actor
                    (*it)->NotifyCollision(this);   // Notify ball actor that we collided with it
                }
            }
        }
    }
 

void CzActor::setActive

(

bool

active

)

Sets this actor as active.

Active actors are processed / updated when they are active. An inactive actor's processing is suspended. You can set actors an inactive if you want to reeuce processing or disable specific actors in a scene. Note that active actors will still be displayed if they are visible.

Parameters:

active

true to make active.

void CzActor::setAngle

(

float

angle

)

Sets th angle of this actor.

Sets the actors orientation in the scene. If a physics body is attached then its physics world orientation will also be updated.

Parameters:

angle

The angle in degrees.

void CzActor::setAngularVelocity

(

float

velocity

)

Sets the angular velocity of this actor.

Sets the actors angular velocity. If a physics body is attached then its physics world angular velocity will also be updated.

Parameters:

velocity

The angular velocity.

void CzActor::setAngularVelocityDamping

(

float

damping

)

Sets the angular velocity of this actor.

Sets the actors angular velocity damping. If a physics body is attached then its physics world angular velocity damping will also be updated.

Parameters:

damping

The angular velocity damping.

void CzActor::setAspectLock

(

eCzAspectLock

lock

)

[inline]

void CzActor::setBindings

(

CzXomlBindings *

bindings

)

Assigns a bindings list to this actor.

Assigns a bindings list to the actor which updates properties of the actor asynchronously from XOML variables. The bindings within a bindings list map variables to properties of the actor, so that when changes to these variables are made they update the properties of the actor. If the outgoing bindings list is not managed then it will be deleted. For more information on bindings see CzXomlBinding and CzXomlBindings

Parameters:

[in]

bindings

If non-null, the bindings.

void CzActor::setBox2dBody

(

CzBox2dBody *

body

)

[inline]

void CzActor::setCategory

(

eCzActorCategory

cat

)

[inline]

void CzActor::setCollidable

(

bool

collidable

)

Makes this actor collidable.

When an actor is made collidable it can collide with other actors in the scene. Note that collision between actors is only supported for actors that are under control of the physics system.

Parameters:

collidable

true if collidable.

void CzActor::setCollisionRect

(

const CzIRect &

rect

)

Sets the collision rectangle of this actor.

The Collision Rect is a rectangular area that represents the approximate area that the actor covers in the scene (usually its visible size) WhIlst collision rects are not used internally by the actor system, functionality has been provided that enables you to test for actors that overlap. CheckCollisionRect() enables you to test if two actors overlay in the scene.

Parameters:

rect	The collision rectangle in scene coordinates.

void CzActor::setCollisionSize

(

int

size

)

Sets this actors collision size.

Its often useful and "much" quicker to check if two actors can potentially overlap by testing their radii and distance apart. Collision Size represents the radius of an actor but squared so we do not later have to use costly square roots to get the real radius. The CheckCollision() method enables you to test if two actors overlap based on their radius and distance apart.

Parameters:

size	The radius of the actor in scene coordinates

void CzActor::setColour	(	uint8	r,
		uint8	g,
		uint8	b,
		uint8	a
	)		[inline]

void CzActor::setColour

(

const CzColour &

colour

)

[inline]

void CzActor::setDepth

(

float

depth

)

[inline]

void CzActor::setDestroyed

(

bool

destroyed

)

[inline]

void CzActor::setDocking

(

CzScene::eDocking

docking

)

Sets this actors docking position.

A version of setDocking(CzScene::eDocking docking, int width, int height) that does not require a specific width and height. Instead these are calculated from the effective size of the actors visual.

Parameters:

docking

The docking position.

void CzActor::setDocking	(	CzScene::eDocking	docking,
		int	width,
		int	height
	)

Sets this actors docking position.

Actors can be docked to the edges of the screen to enable tidy resolution independent placement of actors. Actors can be docked to 8 differrnt locations, including:

• Top
• Left
• Right
• Bottom
• Top-left
• Top-right
• Bottom-left
• Bottom-right

Note that if an actor is added to a CzUICanvas then the canvas will take over docking and dock the actor to its own buonds. Also note that if the screen resolution / orientation changes docked actors will be repositioned to fit the new resolution.

Parameters:

docking	The docking position.
width	The width of the actor in scene coordinates.
height	The height of the actor in scene coordinates.

void CzActor::setDraggable

(

bool

draggable

)

[inline]

void CzActor::SetFromBrush

(

IzBrush *

brush

)

[virtual]

void CzActor::setGridPos	(	int	x,
		int	y
	)

Changes an actors grid cell when assigned to a grid.

When an actor is assigned to a grid, you can use this method to set which grid cell the actor is assigned to.

Parameters:

x	Horizontal grid cell.
y	Vertical grid cell.

void CzActor::setHoldFocus

(

bool

hold

)

[inline]

virtual void CzActor::setIgnoreCamera

(

bool

enable

)

[inline, virtual]

Reimplemented in CzUILabel.

void CzActor::setLayer

(

int

layer

)

[inline]

void CzActor::setLinkedTo

(

CzActor *

actor

)

Links a child actor to a parent actor.

The actor system uses a linked child-parent hierarchy to allow actors to be assigned as children of other actors. In XOML if an actor is declared inside another actors tag then it will automatically be assigned as a child of the containing actor. In code things work a little differently. Standard actors do not contain a list of child actors, instead actors carry a parent link that allows them to be linked to a parent. This enables you to rework the heirarchy without moving actors from one actors child list to another. Actor searches are also much faster as hierarchical searches do not need to be made to find actors within the scene.

Parameters:

[in,out]

actor

If non-null, the actor.

void CzActor::setMargin	(	int	left,
		int	right,
		int	top,
		int	bottom
	)		[inline]

void CzActor::setModifiers

(

CzModifierManager *

mods

)

[inline]

void CzActor::setOpacity

(

uint8

opacity

)

[inline]

void CzActor::setOrigin	(	float	x,
		float	y
	)		[inline]

void CzActor::setOriginalAngle

(

float

angle

)

[inline]

void CzActor::setOriginalMargin	(	int	left,
		int	right,
		int	top,
		int	bottom
	)		[inline]

void CzActor::setOriginalPosition	(	float	x,
		float	y
	)		[inline]

void CzActor::setOriginalScale	(	float	x,
		float	y
	)		[inline]

void CzActor::setOriginalSize	(	int	w,
		int	h
	)		[inline]

void CzActor::setOrphan

(

bool

enable

)

[inline]

void CzActor::setPercPos

(

bool

enable

)

[inline]

void CzActor::setPosition	(	float	x,
		float	y
	)

Sets actors scene position.

Sets the actors x,y position in scene coordinates. If a physics body is attached then its physics world position will also be updated.

Parameters:

x	The x coordinate in scene coordinates.
y	The y coordinate in scene coordinates.

void CzActor::setPosition

(

const CzVec2 &

pos

)

[inline]

void CzActor::setPositionX

(

float

x

)

[inline]

void CzActor::setPositionY

(

float

y

)

[inline]

void CzActor::setPreviousAngle

(

float

angle

)

[inline]

void CzActor::setPreviousPosition	(	float	x,
		float	y
	)		[inline]

bool CzActor::setProperty	(	unsigned int	property_name,
		const CzXomlProperty &	data,
		bool	delta
	)		[virtual]

Sets the named property of the actor.

Sets the named property of this Actor. The properties value supplied will be converted. If delta is set to true then the existing value of the property will be added to instead of replaced.

Parameters:

	property_name	Name of the property as a string hash (faster searching).
[in]	data	The property data.
	delta	true if property should be added to instead of replaced.

Returns:

true if it succeeds, false if property does not exist.

Reimplemented in CzActorParticles, CzUITabBar, CzUIBase, CzUIGrid, CzUIListBox, CzActorText, CzActorConnector, CzActorImage, CzUIImageView, CzActorTilemap, CzUISlider, CzUILabel, CzUITextView, CzUIWebView, CzUITab, CzUITextBox, CzUIVideoOverlay, CzUIStackPanel, and CzUIWrapPanel.

bool CzActor::setProperty	(	const char *	property_name,
		const CzString &	data,
		bool	delta
	)

Sets the named property of the actor.

Sets the named property of this actor. The properties value (data) is supplied as a string and will be converted. If delta is set to true then the existing value of the property will be added to instead of replaced.

Parameters:

	property_name	Name of the property.
[in]	data	The property data.
	delta	true if property should be added to instead of replaced.

Returns:

true if it succeeds, false if property does not exist.

bool CzActor::setProperty	(	unsigned int	property_name,
		const CzString &	data,
		bool	delta
	)		[virtual]

Sets the named property of the actor.

Sets the named property of this actor. The properties value (data) is supplied as a string and will be converted. If delta is set to true then the existing value of the property will be added to instead of replaced.

Parameters:

	property_name	Name of the property as a string hash (faster searching).
[in]	data	The property data.
	delta	true if property should be added to instead of replaced.

Returns:

true if it succeeds, false if property does not exist.

Reimplemented in CzActorParticles, CzUITabBar, CzUIBase, CzUIGrid, CzUIListBox, CzActorText, CzActorConnector, CzActorImage, CzUIImageView, CzActorTilemap, CzUISlider, CzUILabel, CzUITextView, CzUIWebView, CzUITab, CzUITextBox, CzUIVideoOverlay, CzUIStackPanel, and CzUIWrapPanel.

void CzActor::setReceiveEventFromChild

(

bool

enable

)

[inline]

void CzActor::setScale

(

const CzVec2 &

scale

)

[inline]

void CzActor::setScale	(	float	x,
		float	y
	)		[inline]

void CzActor::setScale

(

float

scale

)

[inline]

void CzActor::setScene

(

CzScene *

scene

)

[inline]

void CzActor::setScreenDocking

(

bool

enabled

)

[inline]

void CzActor::setSimpleBinding

(

CzXomlBinding *

binding

)

Assigns a simple binding to this actor.

Assigns a simple binding to the actor. A simple binding can be thought of as a bindings list containing only one binding. Often, when binding actor properties to XOML variables you will only need to bind a single property (for example binding the Text property of a label to a XOML string variable). Simple bindings offer a quick and easy solution that enables a binding to be made without having to create a full bindings list. Note that simple bindings do not exist in the resource manager and are managed by the actor, so when a simple binding is replaced the previous simple binding will be deleted. For more information on bindings see CzXomlBinding and CzXomlBindings

Parameters:

[in,out]

binding

If non-null, the binding.

void CzActor::setTappable

(

bool

tappable

)

[inline]

void CzActor::setTarget

(

CzActor *

target

)

[inline]

void CzActor::setTickEnabled

(

bool

enabled

)

[inline]

void CzActor::setTimeline

(

CzAnimTimeline *

timeline

)

Assigns an animation timeline to this actor.

Assigns an animation timeline to the actor which updates properties of the actor asynchronously from properties of the timelines animations. The animations within a timeline can target specific properties of the actor. If the actor already has a timeline assigned then it will be replaced. If the outgoing timeline is not managed then it will be deleted.

For more information on timelines see CzAnimTimeline.

Parameters:

[in]

timeline

If non-null, the timeline.

void CzActor::setTouchindex

(

int

index

)

[inline]

void CzActor::setType

(

int

type

)

[inline]

void CzActor::setUsed

(

bool

in_use

)

[inline]

void CzActor::setUseParentOpacity

(

bool

enable

)

[inline]

void CzActor::setUserData

(

void *

data

)

[inline]

void CzActor::setUserPropertyList

(

CzUserPropertyList *

props

)

[inline]

void CzActor::setVelocity	(	float	x,
		float	y
	)

Sets the linear velocity of this actor.

Sets the actors linear velocity. If a physics body is attached then its physics world linear velocity will also be updated.

Parameters:

x	The x velocity in scene coordinates.
y	The y velocity in scene coordinates.

void CzActor::setVelocityDamping	(	float	x,
		float	y
	)

Sets the linear velocity damping of this actor.

Sets the actors linear velocity damping. If a physics body is attached then its physics world linear velocity damping will also be updated.

Parameters:

x	The x velocity damping.
y	The y velocity damping.

void CzActor::setVelocityDamping

(

float

damping

)

Sets the velocity damping of this actor.

Sets the actors velocity damping to the same value on both x and y axis. If a physics body is attached then its physics world linear velocity damping will also be updated.

Parameters:

damping

The linear velocity damping.

void CzActor::setVisible	(	bool	visible,
		bool	force_set = false
	)		[virtual]

Makes an actor visible.

Actors can be made visible / invisible by setting their visibility. An invsiible actor will not be displayed but will still be processed if it is active.

Parameters:

visible	true to show, false to hide.
force_set	unused at this time

Reimplemented in CzUIBase.

void CzActor::setVisual

(

CzSprite *

visual

)

[inline]

void CzActor::setWrapPosition

(

bool

enable

)

[inline]

bool CzActor::TestOverlap

(

CzActor *

other

)

Tests for overlap between between two actors.

Utility method that performs very basic distance check between this actor and another to see if they overlap.

Parameters:

[in]

other

If non-null, the other actor

Returns:

true if hit, false if it no hit.

bool CzActor::TestOverlapRect

(

CzActor *

other

)

Test for overlap between two actors.

Utility method that performs rect overlap tests distance between this actor and another to see if they overlap. This method of pverlapping test is more computationally expensive but also more accurate.

Parameters:

[in]

other

If non-null, the other actor.

Returns:

true if hit, false if it no hit.

CzVec2 CzActor::TransformPoint	(	float	x,
		float	y
	)

Transform point.

Transform point x, y by actors local angle / scale transform. This method is useful if you want to figure out where a paticular point on an actor would be in the scene.

Parameters:

x	The x coordinate relative to the actor in scene coordinates.
y	The y coordinate relative to the actor in scene coordinates.

Returns:

The transformed point in scene coordinates

CzVec2 CzActor::TransformPointToScreen	(	float	x,
		float	y
	)

Transform point to screen.

Transform point x, y by actors local angle / scale transform. This method is useful if you want to figure out where a paticular point on an actor would be on screen.

Parameters:

x	The x coordinate relative to the actor in scene coordinates.
y	The y coordinate relative to the actor in scene coordinates.

Returns:

.

bool CzActor::Update

(

float

dt

)

[virtual]

Updates this actors logic.

Updates the actors logic, including:

• Processing event actions
• Processing any attached modifiers
• Updating dragging state
• Updating physics
• Updating the attached timeline

This method should be overriden by derived actors to provide the actor specific logic.

Note that dt is used to scale actor internals that rely on time. This value enables the actor run in an environment where time (the frame rate of the device) can vary allowing animation to keep up without slowing down or speeding up when the frame rate varies.

Note that if an actor returns false then it will automatically be removed from the scene.

Parameters:

dt	The number of seconds since the app was last updated

Returns:

true if it succeeds, false if it fails.

Reimplemented in CzActorParticles, CzUIBase, CzUITabBar, CzUIGrid, CzUIListBox, CzActorConnector, CzUIImageView, CzUITextView, CzUILabel, CzUISlider, CzActorTilemap, CzUIVideoOverlay, CzUIWrapPanel, and CzUICanvas.

bool CzActor::UpdateBinding	(	unsigned int	property_name,
		CzXomlVariable *	var
	)		[protected, virtual]

Updates an actor property from the supplied XOML variable.

Updates a single property from the value of the bound XOML variable.

Parameters:

	property_name	Name of the property.
[in,out]	var	If non-null, the variable.

Returns:

true if it succeeds, false if property does not exist.

Reimplemented in CzActorParticles, CzUIBase, CzUITabBar, CzUIGrid, CzUIListBox, CzActorText, CzActorImage, CzActorConnector, CzUIImageView, CzUITextView, CzActorTilemap, CzUISlider, CzUILabel, CzUIWebView, CzUITab, CzUITextBox, CzUIVideoOverlay, CzUIStackPanel, and CzUIWrapPanel.

void CzActor::UpdateBindings

(

bool

force_modified = false

)

[protected, virtual]

Update data bindings.

Updates the actors internal bindings.

Walks the actors bindings list updating all of its bindings and an attached simple data binding if attached. Passing to true to force_modified will force the bindings to be updated, even if the system does not think the bound variables have not changed.

Parameters:

force_modified

true to force an update.

bool CzActor::UpdateFromAnimation

(

CzAnimInstance *

animation

)

[virtual]

Updates actor property from supplied animation.

Updates the actors property that is specified by the supplied animation. When a timeline animation targets the property of an actor this method will be called by the animation to move the animations frame data into its target property.

    <Timeline name="Anim1" autoplay="true">
        <Animation anim="PosAnim" target="Position">
    </Timeline>
 

In the above example PosAnim targets the Position property. Internally the animation will call UpdateFromAnimation() passing in itself. UpdateFromAnimation() will examine the target preoperty name of the animation as see that it wants to update "Position".

Parameters:

[in]

animation

If non-null, the animation.

Returns:

true if it succeeds, false if property does not exist.

Implements IzAnimTarget.

Reimplemented in CzActorParticles, CzUIBase, CzUITabBar, CzUIGrid, CzUIListBox, CzActorImage, CzActorText, CzUIWebView, CzActorConnector, CzUIImageView, CzUISlider, CzUITextView, CzUILabel, CzActorTilemap, CzUITab, CzUITextBox, CzUIStackPanel, CzUIVideoOverlay, and CzUIWrapPanel.

void CzActor::UpdateMargins

(

)

[protected]

Updates margin szie from original margin (used when orientation changes take place)

Updates the margins.

During an OnOrientationChange event, this utility method is called to recalculate the size of the margins.

bool CzActor::UpdateVisual

(

)

[virtual]

Updates this actors visual component.

Updates the visual component of the actor moving actor data such as position, colour to its visual.

This method can be overriden by derived actors to provide the actor specific display logic.

Returns:

true if it succeeds, false if it fails.

Reimplemented in CzActorParticles, CzActorText, CzActorImage, CzUIWebView, CzUIImageView, and CzUITextView.

---

Member Data Documentation

CzActionsManager* CzActor::ActionsManager [protected]

Manages actions.

CzXomlClassDef * CzActor::ActorClassDef = NULL [static, protected]

float CzActor::Angle [protected]

Orientation in scene (degrees)

float CzActor::AngularVelocity [protected]

Angular velocity.

float CzActor::AngularVelocityDamping [protected]

Angular velocity damping.

eCzAspectLock CzActor::AspectLock [protected]

Determines which acis to use to lock aspect ratio of actors size.

CzXomlBindings* CzActor::Bindings [protected]

Manages any attached bindings.

CzBox2dBody* CzActor::Box2dBody [protected]

Box2D physics body.

eCzActorCategory CzActor::Category [protected]

Category of actor.

CzIRect CzActor::CollisionRect [protected]

Spherical collision size.

int CzActor::CollisionSize [protected]

Size of collision area.

CzColour CzActor::Colour [protected]

Colour.

float CzActor::Depth [protected]

Parallax depth.

bool CzActor::Destroyed [protected]

An actor is marked asd destroyed when it has been marked for deletion.

CzScene::eDocking CzActor::Docking [protected]

Docking position.

CzIVec2 CzActor::DragAnchor [protected]

CzEventManager* CzActor::EventsManager [protected]

List of events that the actor handles.

unsigned int CzActor::GridPos [protected]

x, y position in grid

bool CzActor::HoldFocus [protected]

When set to true this actor will not lose focus when the user moves out of its range.

bool CzActor::IgnoreCamera [protected]

If true then actor will not move with scene camera.

bool CzActor::IsActive [protected]

Active state of actor.

bool CzActor::IsCollidable [protected]

Collidable state of actor.

bool CzActor::IsDraggable [protected]

Draggable state of actor.

bool CzActor::IsDragging [protected]

Dragging state of actor.

bool CzActor::IsTappable [protected]

Tappable state of actor.

bool CzActor::IsVisible [protected]

Visible state of actor.

int CzActor::Layer [protected]

Depth layer.

CzActor* CzActor::LinkedTo [protected]

Actor that this actor links to. Linked actors will utilise their target links colour, visibility and transform etc..

CzIRect CzActor::Margin [protected]

Margin (spacing around the actor)

CzModifierManager* CzActor::Modifiers [protected]

Class modifiers manager.

CzVec2 CzActor::Origin [protected]

Origin of actor.

float CzActor::OriginalAngle [protected]

Original angle in scene (when first spawned)

CzColour CzActor::OriginalColour [protected]

Original colour.

CzIRect CzActor::OriginalMargin [protected]

Original margin.

CzVec2 CzActor::OriginalPosition [protected]

Original position of actor in the scene (when actor was first spawned)

CzVec2 CzActor::OriginalScale [protected]

Original scale of actor in the scene (when actor was first spawned)

CzIVec2 CzActor::OriginalSize [protected]

Original visual size.

bool CzActor::Orphan [protected]

Actors orphaned status.

bool CzActor::PercentagePosition [protected]

If true then position.

CzVec2 CzActor::Position [protected]

Current position of actor in the scene.

float CzActor::PreviousAngle [protected]

Previous updates angle.

CzVec2 CzActor::PreviousPosition [protected]

Previous updates position.

bool CzActor::ReceiveEventFromChild [protected]

If true then this actor will receieve events from its children.

CzVec2 CzActor::Scale [protected]

Scale.

CzScene* CzActor::Scene [protected]

Scene that actor lives in.

bool CzActor::ScreenDocking [protected]

if true then the actors docking value will be applied to the screen and not any parent containers that support edge docking

CzXomlBinding* CzActor::SimpleBinding [protected]

A simple one property binding.

CzIVec2 CzActor::Size [protected]

Visual size.

CzActor* CzActor::Target [protected]

An actor target.

bool CzActor::TickEnabled [protected]

True if OnTick event specified.

CzAnimTimeline* CzActor::Timeline [protected]

Timeline, controls animation of the actor.

CzAnimTimelinesManager* CzActor::TimelinesManager [protected]

Manages timelines.

CzTimersManager* CzActor::TimersManager [protected]

Manages attached timers.

int CzActor::TouchIndex [protected]

Index of last touch on this actor.

int CzActor::Type [protected]

User defined type of Actor (use to distinguish beteeen different actor types)

bool CzActor::Used [protected]

Used is used when actors pooled to reduce memory fragmentation.

bool CzActor::UseParentOpacity [protected]

If true then this actors visuals opacity will be scaled by its parent, if it has one.

void* CzActor::UserData [protected]

Extra custom data.

CzUserPropertyList* CzActor::UserPropertyList [protected]

User properties list.

CzVec2 CzActor::Velocity [protected]

Current velocity of actor.

CzVec2 CzActor::VelocityDamping [protected]

Dampens the velocity (Values less than 1.0f will reduce velocity over time, whilst values larger than 1.0f will increase velocity over time)

CzSprite* CzActor::Visual [protected]

Visual element that represents the actor.

bool CzActor::WrapPosition [protected]

If true then if position exits the extents of the scene actor will wrap back around to the opposite side of the scene.

---

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

• CzActor.h
• CzActor.cpp
• CzUIBase.cpp