CoreItem

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

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 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 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(ATTRIBUTE_TYPE::COREITEM, "item");
   donothing->setValue("item", item);
   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 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 evaluate 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 totally 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, 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, vector elements are comma ',' separated.

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 initialise attributes values. There is no need to precise "1D", "2D", "3D" or "4D" as the dimension is given directly by the attribute type. Expression is evaluated only once to initialize the attribute. **Warning : If the evaluation use other attributes (in other instances or not), they must have been loaded and initialized before the current one. In a given XML, attributes are initialised in the order they are read in the XML.

<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 :

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

Setting a Value

SetValue action waits "duration" then set 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 execute 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 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 wiki page 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" ] }