Kigs Framework Introduction (5/8) - CoreItem

Table of Contents

• Introduction
• Basic CoreItem Usage
• Expression Evaluation
  • Using CoreItem in C++ Code
    • Mathematical Operators
    • Logical Operators
    • Mathematical Functions
    • Test and Affectation
    • Attributes
    • Methods
    • Vectors
    • Instructions Separator
  • For CoreModifiable Attributes Initialisation (XML)
• Animation
  • Interpolation CoreAction
    • Linear Interpolation
    • Hermite Interpolation
  • Setting a Value
  • KeyFrame Actions
  • Loop Actions
    • For Loop
    • DoWhile Loop
  • Compose Actions
    • Combo
    • Series
  • Functions
  • Other Actions
    • Wait
    • Notification
    • Signal
    • RemoveFromParent
• Already Published in this Series
• History

Introduction

CoreItem is a family of class with several different usages:

• JSON type objects manipulation
• Expression evaluation / basic scripting language
• CoreModifiable values animation

Let's have a look at those Kigs framework features.

Basic CoreItem Usage

CoreItem are classes used to manage JSON type of object hierarchy.

Main CoreItem types are CoreValue, CoreMap and CoreVector.
The easier way to manipulate CoreItem is to use CoreItemSP, a smartpointer on CoreItem:

// Create a CoreValue<int> with value 52
CoreItemSP item = CoreItemSP(52);

Here is the list of constructors for CoreValue:

• CoreItemSP(const bool& value): create a CoreValue<bool>
• CoreItemSP(const float& value): create a CoreValue<float>
• CoreItemSP(const int& value): create a CoreValue<int>
• CoreItemSP(const unsigned int& value): create a CoreValue<unsigned int>
• CoreItemSP(const std::string& value) or CoreItemSP(const char* value): create a CoreValue<std::string>
• CoreItemSP(const usString& other): create a CoreValue<usString>

Here is the list of constructors for CoreVector:

• CoreItemSP(const v2f& value): create a CoreVector with two CoreValue<float> values
• CoreItemSP(const v3f& value): create a CoreVector with three CoreValue<float> values
• CoreItemSP(const v4f& value): create a CoreVector with four CoreValue<float> values

Other static helper functions are:

• getCoreMap(): return an empty CoreMap
• getCoreVector(): return an empty CoreVector
• template<typename smartPointOn, typename ... Args> static CoreItemSP getCoreItemOfType(Args&& ... args): return the asked type of CoreItem.

CoreItem hierarchy can also be created from a JSON file or string:

// A CoreItem hierarchy can be created from json file (or json string)
JSonFileParser L_JsonParser;
CoreItemSP item = L_JsonParser.Get_JsonDictionaryFromString(R"====(
  {
   "obj1" : { "obj3": [0.4, 0.9, 0.0, "str"] },
   "val1" : 15
  }
)====");

And then the item can be read using array-like access:

// check if val2 exist
if (item["val2"].isNil())
{
    std::cout << "val 2 not found " << std::endl;
}
else
{
    std::cout << "val 2 : " << (int)item["val2"] << std::endl;
}

std::cout << "val 1 : " << (int)item["val1"] << std::endl;
std::cout << " first obj3 array val : " << (float)item["obj1"]["obj3"][0] << std::endl;

CoreItem can be inserted in a CoreMap or CoreVector using the set method:

// create a CoreValue<float>
CoreItemSP toInsert(61.5f);
// add it to CoreMap item with key "val2"
item->set("val2", toInsert);
// set with "" do a push_back on CoreVector
item["obj1"]["obj3"]->set("",CoreItemSP("stringValue"));

maCoreItem are CoreModifiable attributes that can be added to CoreModifiable and then exported or imported:

CMSP donothing = KigsCore::GetInstanceOf("useless", "DoNothing");
donothing->AddDynamicAttribute(COREITEM, "item");
donothing->setValue("item", item.get());
Export("testCoreItemExport.xml", donothing.get());

The generated XML file contains a DATA section containing the exported JSON:

<?xml version="1.0" encoding="utf-8"?>
<Inst N="useless" T="DoNothingObject">
   <Attr T="coreitem" N="item" Dyn="yes">
<![CDATA[{"obj1":{"obj3":[0.400000,0.900000,0.000000,
          "str","lastElem",[5.000000,4.000000,3.000000]]},
"val1":15,
"val2":52}]]>
   </Attr>
</Inst>

Expression Evaluation

Another kind of CoreItem are CoreItemOperator.
They can be used to evaluate a mathematical expression with access to CoreModifiable attributes or methods.

Using CoreItem in C++ Code

The expression is given as a string starting with "eval" keyword, the dimension of the expression: "1D" or nothing for float, "2D" for 2D vectors, "3D" for 3D vectors, "4D" for 4D vectors and the expression to be evaluated between parenthesis.

CoreItemSP    tsteval("eval(12.0*sin(4.0))");
// evaluate the expression and print it
std::cout << "Expression : 12.0*sin(4.0) = " << (float)tsteval << std::endl;

Of course, more complex expressions are possible :

tsteval = std::string("eval(if(({/Sample5->randomNumber(0.0,2.0)}>1.0),
#/Sample5->EvalResult.x#=(#/Sample5->EvalResult.x#+1);1,
#/Sample5->EvalResult.y#=(#/Sample5->EvalResult.y#+1);2))");

The expression is re-evaluated each time we cast the CoreItem to float, Point2D (or v2f), Point3D (or v3f) or Vector4D (or v4f).

Mathematical Operators

• '*' = multiplication
• '+' = addition
• '-' = subtraction or negation
• '/' = division
• '(' and ')' = parenthesis are also available to group mathematical operations

Logical Operators

• '==' = test equality
• '!=' = test difference
• '>' = test superiority
• '<' = test inferiority
• '>=' = test superiority or equality
• '<=' = test inferiority or equality
• '&&' = logical AND
• '||' = logical OR

Mathematical Functions

Working on float values.

• 'sin' = gives sinus of the given parameter
• 'cos' = gives cosinus of the given parameter
• 'tan' = gives tangent of the given parameter
• 'abs' = gives absolute value of the given parameter
• 'min' = gives minimum value of the given parameters
• 'max' = gives maximum value of the given parameters

Test and Affectation

• 'if' = function if takes 3 parameters, first is the test, second is the returned result if the test is true (then), third is the returned result if the test is false (else).
• '=' affect the right part value to the left part attributes

Attributes

• '#path_to_owner->attribute_name#' = CoreModifiable attributes are given by their path

When using maCoreItem, the path can be relative to owner CoreModifiable. To get only one value of a 2D or 3D or 4D vector, a '.x', '.y','.z' or 'w' can be added to the attribute name.

Methods

• '{path_to_owner->method_name(arg1,arg2...)}' = CoreModifiable methods are given by their path. Like for attributes, when using maCoreItem, the path can be relative to owner CoreModifiable.

Vectors

• '[' and ']' = are delimiters for vector members. Then each member is separated from the next one by ','.

Instructions Separator

• ';' = several expressions can be evaluated, separated by ';'. The last one is the one returned.

For CoreModifiable Attributes Initialisation (XML)

The same mechanism can be used in XML file to initialize attributes values.
There is no need to precise "1D", "2D", "3D" or "4D" as the dimension is given directly by the attribute type.
The expression is evaluated only once to initialize the attribute.

<Inst N="simpleclass" T="SimpleClass">
   <Attr N="IntValue" V="eval(32*4)"/>
</Inst>

Animation

A third way to use CoreItem is to create animation with CoreAction. Animations are available thanks to the CoreAnimation module.

Here is an example of animation in the "Screen_Main.xml" file of Sample5:

<Inst Name="animateLogo" Type="CoreSequenceLauncher">
    <Attr Type="coreitem" Name="Sequence"><![CDATA[
{"animateLogo":[
    {"Linear2D":[4,[0.5,0.5],[1.0,0.5],"Dock"]},
    {"Linear2D":[4,[1.0,0.5],[0.5,0.0],"Dock"]},
    {"Combo": [
        {"Hermite2D":[4,[0.5,0.0],[0.5,1.0],[-1.0,0.0],[1.0,0.0],"Dock"]},
        {"Linear1D":[4,0.0,3.14,"RotationAngle"]}]},
    {"SetValue1D":[1,1,"/Sample5->NeedExit"]}
]}
]]>
    </Attr>
    <Attr Type="bool" Name="StartOnFirstUpdate" Value="true" />
</Inst> 

In the previous XML extract, a CoreSequenceLauncher instance is created as a son of a UIImage of the Kigs framework logo. All numeric, 2D, 3D or 4D vectors CoreModifiable attributes can be animated using CoreAction.
A CoreSequence is then created like this:

{"Sequence Name":[
CoreAction1,
CoreAction2,
...
]}

Each action is described as a JSON object:

{"ActionType":[ActionParam1 , ActionParam2, ...]}

In a CoreSequence, each action is executed before the next one.

Interpolation CoreAction

Linear Interpolation

Linear1D, Linear2D, Linear3D, Linear4D are available.

2D, 3D or 4D values are given between '[' and ']' and separated by ','.

Here is an example of Linear2D interpolation :

{"Linear2D":[duration,[start_value.x,start_value.y],[end_value.x,end_value.y],
"attribute_path->attribute_name",isRelative]}

duration is a float given in seconds, then the start and end values are given, then the CoreModifiable attribute to animate, and the optional relative attribute with following possible values:

• 0 => absolute start and end values
• 1 => start and end relative (mean given values are added to the current value)
• 2 => start relative, end absolute
• 3 => start absolute, end relative

Hermite Interpolation

Hermite interpolation is an interpolation with given starting and ending tangent.

Here is an example of Hermite1D interpolation (2D, 3D and 4D are also available):

{ "Hermite1D": [duration,start_value, end_value,start_tangent, 
   end_tangent,"attribute_path->attribute_name",isRelative] }

Setting a Value

SetValue action waits "duration", then sets the given value to the attribute.
SetValue1D, SetValue2D, SetValue3D, SetValue4D are available.

Here is an example of SetValue3D:

{ "SetValue3D" : [duration, [value.x,value.y,value.z] , "attribute_path->attribute_name"] }

KeyFrame Actions

At the moment, no interpolation is done, KeyFrame actions are the same as series of SetValue actions.
KeyFrame1D, KeyFrame2D, KeyFrame3D, KeyFrame4D are available.

Here is an example of KeyFrame2D:

{"KeyFrame2D" : ["attribute_path->attribute_name", key1_time , [key1_value.x,key1_value.y]
                                                 , key2_time , [key2_value.x,key2_value.y]
                                                 , ...
                                                 , keyN_time, [keyN_value.x,keyN_value.y] ] }

Loop Actions

For Loop

Execute the same action N times. If N is -1, do an infinite loop.

{ "ForLoop" : [N ,{ CoreAction } ] }

DoWhile Loop

Execute the same action while a given attribute is true (not 0).

{ "DoWhile" : ["attribute_path->attribute_name", { CoreAction } ] }

Compose Actions

Combo

A Combo action executes all its son actions at the same time.

{ "Combo" : [{action1},
            ,{action2},
            , ...
            ,{actionN} ] }

Series

A Serie action plays son actions as a sequence: each one after the other.

{ "Serie" :[ {action1},
            ,{action2},
            , ...
            ,{actionN} ] }

Functions

Animate CoreModifiable attribute using CoreItem expression evaluation.

Function1D, Function2D, Function3D, Function4D are available.

There are two possible ways to pass an expression to Function action:

• A float (1D) expression is given for each dimension needed.
• A unique expression with the same dimension of the defined action is given.

The actionTime() method can be used in the expression to get current action time. If "null" is given for one of the expression, then the parameter is unchanged.

Example of Function2D:

{ "Function2D": [duration,["expression1","expression2"],"attribute_path->attribute_name"] }

or:

{ "Function2D": [duration,"expression2D","attribute_path->attribute_name"] }

Example of actionTime usage:

{ "Function2D": [2.0,["0.5+0.5*sin(actionTime())","null"],"AnchorPoint"] }

Other Actions

Wait

Do nothing during the given value in second.

{ "Wait" : [ duration ] }

Notification

Post a message after waiting duration.
An optional string can be given as notification parameter (usString* is passed as private param).

{ "Notification" :  [ duration , "notification_name", "optional_param" ] }

See Signal / Slot / Notification future article for details.

Signal

Make owner CoreModifiable instance send a signal after waiting duration.
An optional string can be given as usString signal parameter.

{ "Signal" :  [ duration , "signal", "optional_param" ] }

See Signal / Slot / Notification future article for details.

RemoveFromParent

Remove the object owning this sequence from its parent of the given type after waiting duration.

{ "RemoveFromParent" :  [ duration , "parent_type" ] }

Find all the sample code from this wiki section in Sample5 project (browse the code).

Already Published in this Series

1. Kigs Framework Introduction (1/8) - Overview
2. Kigs Framework Introduction (2/8) - CoreModifiable
3. Kigs Framework Introduction (3/8) - Attributes
4. Kigs Framework Introduction (4/8) - Methods
5. Kigs Framework Introduction (5/8) - CoreItem
6. Kigs Framework Introduction (6/8) - Signal, Slot, Notification
7. Kigs Framework Introduction (7/8) - Lua Binding
8. Kigs Framework Introduction (8/8) - Data Driven Application

History

• 20^th February, 2020: Initial version
• 3^rd March, 2020: Article (6/8) added to the series
• 19^th March, 2020: Article (7/8) added to the series
• 17^th June, 2020 : Added final article of the series
• 1^st March, 2023: Article updated after framework refactory