CzAction Struct Reference

An action is a command that can be executed from XOML. More...

#include <CzActions.h>

List of all members.

Public Member Functions
	CzAction ()
void	setMethodName (const char *name)
unsigned int	getMethodName () const
void	setParameter1 (CzString &p)
void	setParameter1 (const char *p)
CzString &	getParameter1 (IzXomlResource *parent=NULL)
void	setParameter2 (CzString &p)
void	setParameter2 (const char *p)
CzString &	getParameter2 (IzXomlResource *parent=NULL)
void	setParameter3 (CzString &p)
void	setParameter3 (const char *p)
CzString &	getParameter3 (IzXomlResource *parent=NULL)
void	setParameter4 (CzString &p)
void	setParameter4 (const char *p)
CzString &	getParameter4 (IzXomlResource *parent=NULL)
void	setParameter5 (CzString &p)
void	setParameter5 (const char *p)
CzString &	getParameter5 (IzXomlResource *parent=NULL)
void	setConditions (const char *cond)
unsigned int	getConditions () const
Public Attributes
unsigned int	MethodName
	Action method type.
CzString	Params [5]
	Action parameters.
CzXomlVariable *	Variables [5]
	Cached variable parameters (prevents continually searching for variables)
unsigned int	Conditions
	Name of conditions variable that defines a set of conditions that must be met for this action to be executed.
bool	Not
	if true then result of condition will be inversed
CzActions *	Parent
	Parent actions container.
CzString	_Conditions

---

Detailed Description

An action is a command that can be executed from XOML.

Introduction

An action consists of a method and a number of parameters (eiter variabls or values) that can be passed to that method. Note that actions will cache any variables that are passed as parameters osthey do not have to be constantly searched for in the resuorce manager.

An action also carries a conditions variable which defines a conditions variable that can be used to conditionally execute the action.

A game or app would be pretty useless if it did nothing other than just sit and look pretty. Users generally expect lots of interaction with their apps. XOML uses the events and actions system to provide such interaction.

From a XOML point of view an event is something that has happened in the app that some scene or actor needs to know about. For example, when the user taps a button to see help he raises the tapped help button event. An action from XOML's point of view is something that is done in response to an event. Continuing on with the same example, an action that could be carried out in response to the user pressing the help button is to load and show a help scene.

Scenes and different types of actors all handle a variety of different events (more on this later). Likewise scenes and different actors can carry our different actions. If we look back at our scene and actor property definitions we see many properties with names such as OnCreate, OnDestroy, OnTapped etc.. These properties represent event handlers. When we define one of these properties for an object we tell the system that we want to respond to that event occurring by calling an actions list.

An actions list is a list of actions that should be carried out in response to an event occurring. Actions lists can be declared globally, local to a scene or even local to an actor.

The BasicActions example shows an example how to use events with actions. Lets take a look at the XOML for this example to see how it works:

<!-- Create rotation animation (we will use this to animate angle of the label) -->
<Animation Name="AngleAnim" Duration="4" Type="float">
    <Frame Time="0" Value="0" />
    <Frame Time="4" Value="360" />
</Animation>
    
<!-- Create a timeline that can be used to animate an actor -->
<Timeline Name="Anim1" AutoPlay="false">
    <Animation Anim="AngleAnim" Target="Angle" />
</Timeline>

<!-- Create a scene -->
<Scene Name="Scene1" Current="true" >

    <!-- Create a label with an animation -->
    <Label Font="serif" Background="Button1Brush" BackgroundColour="80, 80, 255, 255" Size="100, 100" Text="Animation" OnBeginTouch="Spin" NotifyEnd(Touch="StopSpin" Timeline="Anim1">
        <Actions Name="Spin">
            <Action Method="PlayTimeline" />
        </Actions>
        <Actions Name="StopSpin">
            <Action Method="PauseTimeline" />
        </Actions>
    </Label>

</Scene>

Firstly we create an animation and a timeline that will be used to spin our label. Next we create a label within a scene and assign action lists to the OnBeginTouch and NotifyEnd(Touch events. Next, we define two actions list, one called Spin and another called StopSpin. The first action list calls an action called PlayTimeline which tells the actor to start playing its current timeline. The second actions list calls an action called PauseTimeline which tells the actor to pause playback of its timeline. The OnBeginTouch event is raised when the user starts to press the actor, the NotifyEnd(Touch event is raised when the user stops touching the actor.

You use the Actions tag to declare a list of actions. Actions can be declared globally so that any scene or actor can call them, local to a scene so that the scene and any actors contained with the scene can call them or local to an actor in which case only that actor can call them. Lets take a look at the properties that are supported by an Actions list:

• Name (string) - Name of actions group
• Local (boolean) - When set to false, this actions group will be added to the scenes actions manager instead of the actors actions manager
• Condition (variable) - A condition variable that must evaluate to true for this action list to be executed (this is an optional feature and can be used to conditionally execute actions lists based on the state of the app, such as the value of certain variables)
• Tag (string) - Resource tag (used to group resources together)

An actions list contains a list of action tags. An action tag has the following properties:

• Method (method name) - A method is the actual action that takes places such as PlayTimeline, SetProperty etc..
• Param1 to Param5 - Five parameters that can be passed to the action. with exception to parameters that are passed as optional container scenes. Note that the shorter P1 to P5 attributes can be substituted for Param1 to Param5. Variables can be passed to any parameter that is not expecting a variable name or optional container scene
• Condition (variable) - A condition variable that must evaluate to true for this action to executed (this is an optional feature and can be used to conditionally execute actions based on the state of the app, such as the value of certain variables)

Method is a required property. In some cases Param1 to Param5 may also be required properties (see individual actions)

Note that when passing a variable to an actions parameter the variable will be searched for in the container scene (or in many cases the optional container scene that was passed). If it is not found there then the global variables space will be searched. If the variable is found then the variables value will be substituted as the parameter. If the variable does not exist then XOML assumes that the variable is a value.

For clarity the container scene is the scene that contains the actor that called the action, if the action is called from an actor. If the action was called from a scene then that scene will be the container scene.

XOML has an ever growing list of supported actions that can be called to carry out certain functions. Actions are grouped by purpose into the following groups:

• CzXomlActions_Actor - Actor specific actions
• CzXomlActions_Animation - Animation specific actions
• CzXomlActions_Comms - Communications specific actions
• CzXomlActions_Market - Market specific actions
• CzXomlActions_Media - Media specific actions
• CzXomlActions_Program - XOML Program Removal actions
• CzXomlActions_Resource - Resource specific actions
• CzXomlActions_Scene - Scene specific actions
• CzXomlActions_Script - Script specific actions
• CzXomlActions_Shared - Scene / actor shared actions
• CzXomlActions_Sys - System specific actions
• CzXomlActions_Variable - Variable specific actions

Actions Scope<h1> The scope of an actions list depends on where it was declared. You can declare actions in the following places:Inside actor tags - The actions list will be assigned to the actors actions manager and will be local to the actor and timelines that are local to the actorInside scene tags - The actions list will be assigned to the scenes actions manager and will be local to the scene and any actors / timelines within that sceneInside timeline tags - The actions list will be assigned to the actors actions manager if it was declared inside an actor or to the scenes if it was declared inside a scene. if declared globally then the actions list will be assigned to the global actions manager and will be available to all scenes and their actorsDeclared globally (outside a scene) - The actions list will be assigned to the global actions manager and will be available to all scenes and actors Creating Actions

Below we show 3 different ways of creating actions and assigning them to an actor:

XOML Example:

<!-- Create a label object -->
<Label Font="serif" Background="Button1Brush" BackgroundColour="255, 80, 80, 255" Text="Clipping" WrapPosition="true" OnTick="Update">
    <Actions Name="Update">
        <Action Method="AddProperty" Param1="Position" Param2="2, 2" />
    </Actions>
</Label>

Code Example:

    // Create label
    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);
    CzIVec2 size(200, 70);
    CZ_NEW_LABEL(scene, label, "label1", CzString("Clipping"), background_brush, font, size, false);
    label->setBackgroundColour(CzColour(255, 80, 80, 255));
    label->setWrapPosition(true);

    // Create an actions list that modifies the Position property of the label
    CzActions* actions = new CzActions();
    actions->setName("Update");
    CzAction* action = new CzAction();
    action->setMethodName("AddProperty");
    actions->addAction(action);
    action->setParameter1("Position");
    action->setParameter2("2, 2");

    // Add actions list to the label actors actions manager
    label->getActionsManager()->addActions(actions);

    // Tie label OnTick event to Update actions list
    label->getEventsManager()->addEvent("OnTick", "Update", true);
    label->setTickEnabled(true);    // When OnTick is specified we need to inform actor that it has been added to list (optimisation)

Code Example (using macros):

    // Create label
    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);
    CzIVec2 size(200, 70);
    CZ_NEW_LABEL(scene, label, "label1", CzString("Clipping"), background_brush, font, size, false);
    label->setBackgroundColour(CzColour(255, 80, 80, 255));
    label->setWrapPosition(true);

    // Create an actions list that modifies the Position property of the label
    CZ_NEW_SINGLE_ACTION_P2(actions, a, "Update", "AddProperty", "Position", "2, 2");
    label->getActionsManager()->addActions(actions);

    // Tie label OnTick event to Update actions list
    label->getEventsManager()->addEvent("OnTick", "Update", true);
    label->setTickEnabled(true);    // When OnTick is specified we need to inform actor that it has been added to list (optimisation)

As you can see, by far the easiest way to work with actions, actions lists and events is to use XOML.

Creating Custom Actions

Actions are a great way of passiong information between XOML and code, but the actions system wouldn't be as useful if it was limited to just the standard set of actions. Lets take a look at how to create our own custom actions that can be called from XOML.

To create our own action we follow the following process:

• Derive a new actions class from IzXomlAction
• Set the action name in the constructor using setActionName() - This will be the name as it will be used in XOML.
• Implement the Execute() method of IzXomlAction
• Add an instance of the action to the actions manager

Lets take a look at the first 3 stages:

class CzXomlActions_MyAction : public IzXomlAction
{
    CzXomlActions_MyAction()
    {
        // Set the action name (case insensitive )
        setActionName("myaction");
    }
public:
    void Execute(IzXomlResource* source, CzAction* action)
    {
        CzApp* app = NULL;
        CzScene* scene = NULL;
        CzActor* actor = NULL;

        // Determine the scene, app and possibly actor that called the action
        if (source->getClassTypeHash() == CzHashes::Scene_Hash)
        {
            scene = (CzScene*)source;
            app = scene->getParent();
        }
        else
        if (source->getClassTypeHash() == CzHashes::Actor_Hash)
        {
            actor = (CzActor*)source;
            scene = actor->getScene();
            app = scene->getParent();
        }

        // Get the container / parent that contains the action
        IzXomlResource* cont = (actor != NULL) ? (IzXomlResource*)actor : (IzXomlResource*)scene;

        // Do something with the action
        CzString& param1 = action->getParameter1(cont);
        CzString& param2 = action->getParameter2(cont);
        DoSomething(param1, param2);
    }
};

Note that you do not need to determine the app, scene and actor of the caller if you do not need them all. We have provided them all as an example.

Also note that in this example we call the actions parameter extraction methods CzAction::getParameter1() and CzAction::getParameter2() which will evaluate the parameters that were passed to the action. The evaluation process will check the parameters for variables and if any are found then these variables values will be returned. You do not need to add this step if you do not rely on XOML variables being passed as parameters to your actions. Below is an example of a much simplified action handler:

class CzXomlActions_MyAction : public IzXomlAction
{
    CzXomlActions_MyAction()
    {
        // Set the action name (case insensitive )
        setActionName("myaction");
    }
public:
    void Execute(IzXomlResource* source, CzAction* action)
    {
        // Do something with the action
        DoSomething(action->Params[0], action->Params[1]);
    }
};

The last stage of adding your own custom action is to notify the XOML system that your action is available. To do this we call CZ_XOML->addAction():

CZ_XOML->addAction(new CzXomlActions_MyAction());

Note that CZ_XOML is a macro that accesses the global XOML singleton.

We would place this call somewhere in our apps main boot up sequence so it gets called before any XOML parsing that contains this action begins.

Now lets take a look at a small XOML example that shows the use of our new action:

<Actions Name="AnActionsList">
    <Action Method="MyAction" Param1="Hello World!" Param2="Im an action!" />
</Actions>

Conditional Actions

A conditional action is an action that will be executed only if certain conditions are met. Lets take a look at a short example:

<Actions Name="UpdatePLayerScore">
    <Action Method="AddVar" Param1="PlayerScore" Param2="1" Condition="!PlayerScoreTooHigh" />
    <Action Method="SetVar" Param1="PlayerScore" Param2="0" Condition="PlayerScoreTooHigh" />
</Actions>

In the above example the Condition attribute contains the PlayerScoreTooHigh variable. This variable is evaluated when the action is ran. if it returns true then the action will be executed. Note that if the condition variable is prefixed with an exlamation mark then the result of the condition will be inverted. In this case the action will only be executed if the result of evaluating the action is false. Conditions can also be applied to the actions list itself. Conditional actions offer a quick and easy way of applying simple logic to your apps directly in XOML without having to resort to code.

Some Examples

Lets take a look at some useful example actions:

<Action Method="ShowActor" P1="RefundedMessage"/>       - Show an actor
<Action Method="HideActor" P1="RefundedMessage"/>       - Hide an actor

<Action Method="CallScript" Param1="Guess" />   - Calls a script method

<Action Method="Inline" Param1="
        local scene = scene.find('Scene1');
        local sound = resource.find('explosion', 'sound', scene);
        media.playSound(sound, true);            - Executes Lua script inline
        " />

<Action Method="PlaySound" Param1="explosion" Param2="true" />  - Play a sound effect

<Action Method="Purchase" P1="coins1" />    - Purchase a product using in-app purchasing

<Action Method="SetProperty" P1="BackgroundColour" P2="128, 128, 255, 255" P3="Menu" /> - change the background colour of a menu

<Action Method="LoadFile" Param1="RoundFile" Param2="true" Param3="Round1.txt" Condition="IsRound0" /> - Load a file

<Action Method="SetVar" Param1="CardIndex" Param2="0" /> - Set the value of a variable

<Action Method="CallActions" Param1="NextRound" /> - Call anoter actions list

---

Constructor & Destructor Documentation

CzAction::CzAction

(

)

[inline]

---

Member Function Documentation

unsigned int CzAction::getConditions

(

)

const [inline]

unsigned int CzAction::getMethodName

(

)

const [inline]

CzString & CzAction::getParameter1

(

IzXomlResource *

parent = NULL

)

CzString & CzAction::getParameter2

(

IzXomlResource *

parent = NULL

)

CzString & CzAction::getParameter3

(

IzXomlResource *

parent = NULL

)

CzString & CzAction::getParameter4

(

IzXomlResource *

parent = NULL

)

CzString & CzAction::getParameter5

(

IzXomlResource *

parent = NULL

)

void CzAction::setConditions

(

const char *

cond

)

[inline]

void CzAction::setMethodName

(

const char *

name

)

[inline]

void CzAction::setParameter1

(

CzString &

p

)

[inline]

void CzAction::setParameter1

(

const char *

p

)

[inline]

void CzAction::setParameter2

(

CzString &

p

)

[inline]

void CzAction::setParameter2

(

const char *

p

)

[inline]

void CzAction::setParameter3

(

CzString &

p

)

[inline]

void CzAction::setParameter3

(

const char *

p

)

[inline]

void CzAction::setParameter4

(

CzString &

p

)

[inline]

void CzAction::setParameter4

(

const char *

p

)

[inline]

void CzAction::setParameter5

(

CzString &

p

)

[inline]

void CzAction::setParameter5

(

const char *

p

)

[inline]

---

Member Data Documentation

CzString CzAction::_Conditions

unsigned int CzAction::Conditions

Name of conditions variable that defines a set of conditions that must be met for this action to be executed.

unsigned int CzAction::MethodName

Action method type.

bool CzAction::Not

if true then result of condition will be inversed

CzString CzAction::Params[5]

Action parameters.

CzActions* CzAction::Parent

Parent actions container.

CzXomlVariable* CzAction::Variables[5]

Cached variable parameters (prevents continually searching for variables)

---

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

• CzActions.h
• CzActions.cpp