Kigs Framework Introduction (2/8) - CoreModifiable

Table of Contents

• Introduction
• Class Type and Name
  • Instance Type
• Reference Counting and Instances Tree
  • Smart Pointers
  • Instances Tree
  • Searching Instances by Name or Type
• Attributes
  • Declaration
  • Access
  • Dynamic Attributes
• Virtual Methods
  • Initialization / Un-initialization​​​​​
  • Add / Remove Sons or Parents
  • Update
  • Attribute Set Notification
• Methods
  • Faster Way (But More Restrictive)
  • Easier Way
• Aggregates
• Serialization
  • Export
  • Import
• Already Published in this Series
• History

Introduction

In the first article of this series, we have offered a general overview of the Kigs framework. This article will focus on the main base class of the framework: the CoreModifiable class.

Class Type and Name

All high level classes have to inherit CoreModifiable, or another CoreModifiable inherited class, in order to have access to instance factory, reference counting, serialization, attributes...

Here is a basic example of class declaration:

// this class inherits CoreModifiable directly
class SimpleSampleClass : public CoreModifiable
{
public:
    // helper Macro to setup everything needed
    DECLARE_CLASS_INFO(SimpleSampleClass, CoreModifiable, Application);
    // helper Macro to declare an inline constructor (empty here)
    DECLARE_INLINE_CONSTRUCTOR(SimpleSampleClass) {}
protected:
    // override initialization method called explicitly with "Init()" 
    // or implicitly when importing from XML for example
    void InitModifiable() override;
};

Instead of DECLARE_CLASS_INFO, DECLARE_ABSTRACT_CLASS_INFO can be used to create a base class that can't be directly instantiated. Parameters are class name, parent class name and module name. Module name parameter is just an helper parameter.

Instead of DECLARE_INLINE_CONSTRUCTOR, DECLARE_CONSTRUCTOR can be used, associated with IMPLEMENT_CONSTRUCTOR (probably in the .cpp file).

Then the .cpp file will look like that:

// Helper macro, setup implementation
IMPLEMENT_CLASS_INFO(SimpleSampleClass)
// override InitModifiable method
void SimpleSampleClass::InitModifiable()
{
    // call parent InitModifiable method
    ParentClassType::InitModifiable();
    // check if parent initialization was OK
    if (_isInit)
    {
        // initialize things
    }
}

`ParentClassType` is a helper typedef used to call methods on parent class.

`_isInit` is also a helper macro used to test if the class was correctly initialized...

Then, in the initialization of the module or application, classes must be declared (to factory):

DECLARE_FULL_CLASS_INFO(KigsCore::Instance(), 
                        SimpleSampleClass, SimpleSampleClass, Application);

Parameters are: the current singleton instance of KigsCore, the name of the class to instantiate, the name given to the instance factory, and the Module name.

The name of an instance can be retrieved with the getName() method:

std::string name=simpleclass1->getName();

Instance Type

Testing instance type is possible using `isSubType` method:

// test if a cast can be done
if(simpleclass1->isSubType("SimpleSampleClass"))
{
       SimpleSampleClass* castSimpleClass=simpleclass1->as<SimpleSampleClass>();
}

Reference Counting and Instances Tree

So now an instance of the class SimpleSampleClass can be asked to the instance factory:

// ask for a SimpleSampleClassBase instance named simpleclass1
CMSP simpleclass1 = KigsCore::GetInstanceOf("simpleclass1", "SimpleSampleClass");

When created, the instance has a ref count of 1.

• `addItem` increases ref count of the added instance by 1.
• `removeItem` decreases ref count of the removed instance by 1.

Smart Pointers

SmartPointer classes are used to easily manage ref counting. CMSP is a class inheriting  SmartPointer<CoreModifiable>.
SP and SmartPointer are equivalent.

{
    // sp is a smart pointer on an instance of SimpleSampleClass named "simpleclass1"
    SmartPointer<SimpleSampleClassBase> sp=KigsCore::GetInstanceOf
                                           ("simpleclass1", "SimpleSampleClass");
}   // exiting the block scope will automatically delete the instance "simpleclass1"

Pointers on CoreModifiable inherited instances can be wrapped in SmartPointer using SharedFromThis method

// smartpointer with no ref count increase
SmartPointer<SimpleSampleClassBase> sp=instance1->SharedFromThis();

Operator `->` is used to access functionality of the instance in the SmartPointer:

float test;
sp->getValue("test",test);

And retrieving the instance pointer itself is done using get() method:

SimpleSampleClassBase* simpleinstance = sp.get();

Instances Tree

Instances inheriting CoreModifiable class maintain lists of their parents and sons instances (not in an inheritance point of view). So it is possible to construct trees of instances.

// ask for a SimpleSampleClassBase instance named simpleclass1
CMSP simpleclass1 = KigsCore::GetInstanceOf("simpleclass1", "SimpleSampleClass");
// Initialize class
simpleclass1->Init();

// ask for two other instances
CMSP simpleclass2 = KigsCore::GetInstanceOf("simpleclass2", "SimpleSampleClass");
simpleclass2->Init();
CMSP simpleclass3 = KigsCore::GetInstanceOf("simpleclass3", "SimpleSampleClass");
simpleclass3->Init();

// and add simpleclass2 and simpleclass3 to simpleclass1
simpleclass1->addItem(simpleclass2); // simpleclass2 count ref is now 2
simpleclass1->addItem(simpleclass3); // simpleclass3 count ref is now 2

// add simpleclass1 to this
addItem(simpleclass1);

It is then easy to retrieve instances in the tree using `GetInstanceByPath` method:

// retrieve instances in the instances tree using "path"
CMSP simpleclass2 = 
     GetInstanceByPath("SimpleSampleClass:simpleclass1/simpleclass2");
CMSP simpleclass1 = 
     simpleclass2->GetInstanceByPath("/Sample2/SimpleSampleClass:simpleclass1");
CMSP simpleclass3 = simpleclass2->GetInstanceByPath("../simpleclass3");
simpleclass3 = GetInstanceByPath("*/simpleclass3");

• If path starts with `/`, then start search by root parents (parents of this without parent).
• If path contains `../`, then continue search from parents instance.
• If path contains `*/`, then search all sons instance at this level in path.

Searching Instances by Name or Type

Search can be done in sons:

// retrieve all instances named "simpleclass1" in sons list
std::vector<CMSP> instances;
GetSonInstancesByName("CoreModifiable", "simpleclass1",instances);
printf("GetSonInstancesByName result :\n");
for (auto i : instances)
{
    printf("found instance named : %s\n", i->getName().c_str());
}
instances.clear();
// retrieve all instances named "simpleclass2" recursively in sons list
GetSonInstancesByName("CoreModifiable", "simpleclass2", instances,true);
printf("Recursive GetSonInstancesByName result :\n");
for (auto i : instances)
{
   printf("found instance named : %s\n", i->getName().c_str());
}
instances.clear();
// retrieve all instances of type CoreModifiable in sons list
GetSonInstancesByType("CoreModifiable", instances);
printf("GetSonInstancesByType result :\n");
for (auto i : instances)
{
   printf("found instance named : %s\n", i->getName().c_str());
}
instances.clear();
// retrieve all instances of type SimpleSampleClass recursively in sons list
GetSonInstancesByType("SimpleSampleClass", instances,true);
printf("Recursive GetSonInstancesByType result :\n");
for (auto i : instances)
{
    printf("found instance named : %s\n", i->getName().c_str());
}

Or at a global scope:

// retrieve all instances named "simpleclass1" at global scope
instances = GetInstancesByName("CoreModifiable", "simpleclass1");
printf("GetInstancesByName result :\n");
for (auto i : instances)
{
    printf("found instance named : %s\n", i->getName().c_str());
}
instances.clear();
// retrieve all instances of type SimpleSampleClass at global scope
instances = GetInstances("SimpleSampleClass");
printf("GetInstances result :\n");
for (auto i : instances)
{
    printf("found instance named : %s\n", i->getName().c_str());
}

Attributes

The CoreModifiable attributes are detailed in a next article.

Here is just a brief overview.

Declaration

CoreModifiable can have "compile time" attributes that can be declared in the class as below:

class SimpleSampleClass : public CoreModifiable
{
public:
    DECLARE_CLASS_INFO(SimpleSampleClass, CoreModifiable, Application);
    DECLARE_INLINE_CONSTRUCTOR(SimpleSampleClass) {}
protected:
    // unsigned int attribute "Version"
    maUInt      m_version = BASE_ATTRIBUTE(Version, 0);
    // string attribute "Description"
    maString    m_desc = BASE_ATTRIBUTE(Description, "");
};

Another way to declare several attributes, mapped on member variables is to use WRAP_ATTRIBUTES macro:

class SimpleSampleClass : public CoreModifiable
{
public:
	DECLARE_CLASS_INFO(SimpleSampleClass, CoreModifiable, Application);
	DECLARE_INLINE_CONSTRUCTOR(SimpleSampleClass) {}
protected:
	// unsigned int attribute "Version"
	u32            mVersion = 0;
        // string attribute "Description"
	std::string    mDescription = "";

    WRAP_ATTRIBUTES(mVersion,mDescription);
};

WRAP_ATTRIBUTES macro remove the first character (here 'm' prefix) of the attribute to define the name of the attribute (used by getters/setters, serialization...)

Access

Then, on an instance of SimpleSampleClass, the attributes can be accessed with getValue / setValue methods:

simpleclass1->setValue("Version",5);
std::string desc;
simpleclass1->getValue("Description",desc);

Dynamic Attributes

It's also possible to add or remove attributes dynamically:

simpleclass1->AddDynamicAttribute(ATTRIBUTE_TYPE::BOOL, "isON");
simpleclass1->RemoveDynamicAttribute("isON");

All the attributes of an instance are serialized to and from XML files when the instance is serialized.

Virtual Methods

Initialization / Un-initialization

Two methods are useful to overload to manage initialization of an instance:

// Init the modifiable and set the _isInit flag if OK. 
// Need to call ParentClassType::InitModifiable() when overriding !
virtual    void InitModifiable();

// Called when init has failed. 
// Need to call ParentClassType::UninitModifiable() when overriding !
virtual    void UninitModifiable();

InitModifiable is called by Init() method.

Here is a classic way to overload InitModifiable:

// InitModifiable overload sample code
void SimpleSampleClass::InitModifiable()
{
    // check for multiple init
    if (_isInit)
    {
        // init was already done, just return
        return;
    }
    // call parent class InitModifiable
    ParentClassType::InitModifiable();
    // if everything is OK, do this initialization
    if (_isInit)
    {
        bool somethingWentWrong=false;
        // here is some initialization code for this
        ...
        // check if something went wrong
        if(somethingWentWrong)
        {
            // call Uninit
            UnInit();
            return;
        }
    }
}

Of course, it's also a good thing to add a virtual destructor to free all allocations done by the class or add some specific destruction code.

Add / Remove Sons or Parents

If a special behaviour is needed when an instance is added to another, for example to check if an instance of a specific type is added to another, the following methods can be overloaded:

// add the given parent to list. Need to call ParentClassType::addUser(...) when overriding !
virtual void addUser(CoreModifiable* user);

// remove the given parent from list. 
// Need to call ParentClassType::removeUser(...) when overriding !
virtual void removeUser(CoreModifiable* user);
    
// add a son. Need to call ParentClassType::addItem(...) when overriding !
virtual bool addItem(const CMSP& item, ItemPosition pos = Last);
    
// remove a son. Need to call ParentClassType::removeItem(...) when overriding !
virtual bool removeItem(const CMSP& item);

Update

// Update method. Call to ParentClassType::Update is not necessary when overriding
virtual void Update(const Timer&  timer, void* addParam);

The Update method of an instance is called at each application loop if the instance was added to auto update:

// add instanceToAutoUpdate to application auto update system
KigsCore::GetCoreApplication()->AddAutoUpdate(instanceToAutoUpdate);

Of course, the instance is automatically removed from auto update when destroyed or manually by calling RemoveAutoUpdate:

// remove instanceToAutoUpdate from application auto update system
KigsCore::GetCoreApplication()->RemoveAutoUpdate(instanceToAutoUpdate);

Update method can also be called manually by CallUpdate method or RecursiveUpdate method.

Attribute Set Notification

CoreModifiable attributes can notify their owners when they change (when accessed by "setValue"), calling the "NotifyUpdate" method with their ID.

// Called when an attribute that has its notification level set to Owner is modified. 
// Need to call ParentClassType::NotifyUpdate(...) when overriding !
virtual void NotifyUpdate(const u32 labelid);

Methods

Faster Way (But More Restrictive)

The detailed specifications of the CoreModifiable methods are be described in a next article.

Here is just a brief overview.

The class CoreModifiable allows defining methods callable by their name (string) with a fixed prototype:

bool    methodName(CoreModifiable* sender,std::vector<CoreModifiableAttribute*>& params,
                   void* privateParams);

Helpers macro are available to facilitate things: DECLARE_METHOD(methodName), DECLARE_VIRTUAL_METHOD(methodName), DECLARE_PURE_VIRTUAL_METHOD(methodName),

DECLARE_OVERRIDE_METHOD(methodname),DEFINE_METHOD(classtype,methodName).

In class declaration:

// method that add 1 to the given parameter
DECLARE_METHOD(incrementParam);

and then in cpp file, class definition:

DEFINE_METHOD(SimpleSampleBaseClass, incrementParam)
{
    float val=0;
    // access first param (we could check for param name here)
    if (params[0]->getValue(val,this)) // if first param value can be get as float
    {
        // increment value
        params[0]->setValue(val + 1.0f,this);
    }
    return true;
}

The list of CoreModifiable methods must be declared in the class header using COREMODIFIABLE_METHODS(method1,method2...) helper macro.

// declare all CoreModifiable methods
COREMODIFIABLE_METHODS(incrementParam);

The method can then be called on a CoreModifiable instance pointer (without knowing the exact instance type):

CoreModifiableAttribute* param = item->getAttribute("CountWhenAdded");
if (param)
{
    // call incrementParam method
    std::vector<CoreModifiableAttribute*> sendParams;
    sendParams.push_back(param);
    item->CallMethod("incrementParam", sendParams);
    std::cout << item->getName() << " parameter CountWhenAdded = " 
    << item->getValue<int>("CountWhenAdded") << std::endl;
}

Easier Way

Any CoreModifiable member method can be accessed by its name using WRAP_METHODS helper macro:

// simple method
void    printMessage();
// ask possible call by name
WRAP_METHODS(printMessage);

WRAP_METHODS can take several coma separated parameters.

Then the method can be called with SimpleCall method:

simpleclass1->SimpleCall("printMessage");

For methods with parameters and return value, the SimpleCall method will be used like this:

int returnedValue = instance->SimpleCall<int>("DoSomethingFun",42,"yes");

Aggregates

Two or more CoreModifiable instances of different types can be aggregated all together.

For example, let's define a material class managing Color and Shininess:

class SimpleMaterialClass : public CoreModifiable
{
public:
    DECLARE_CLASS_INFO(SimpleMaterialClass, CoreModifiable, Application);
    DECLARE_INLINE_CONSTRUCTOR(SimpleMaterialClass) 
    { std::cout << "SimpleMaterialClass constructor" << std::endl; }

protected:

    // RGB color
    maVect3DF    m_Color = BASE_ATTRIBUTE(Color,1.0,0.0,0.0);
    // shininess
    maFloat        m_Shininess = BASE_ATTRIBUTE(Shininess, 0.5);
};

If an instance of material is aggregate with an instance of SimpleSampleClass:

// create an instance of SimpleMaterialClass
CMSP material= KigsCore::GetInstanceOf("material", "SimpleMaterialClass");
// manage simpleclass3 and material as one unique object
simpleclass3->aggregateWith(material);

It's then possible to directly get or set "Shininess" or "Color" values on simpleclass3:

float shine=0.0f;
simpleclass3->getValue("Shininess", shine);
std::cout << simpleclass3->getName() << " has Shininess value of " 
<< shine << " thanks to aggregate with SimpleMaterialClass " << std::endl;

The opposite is also true, it's possible to retrieve SimpleSampleClass values from "material" instance. And calling CoreModifiable methods is also available the same way.

Serialization

Export

Export is only available when project is built in StaticDebug or StaticReleaseTools configuration. In StaticRelease, KigsID (used as map key for instances name...) are optimized and std::string used to construct them are not preserved.

// only if export is available
#ifdef KIGS_TOOLS
    // export Sample1 and its sons in Sample1.xml file
    CoreModifiable::Export("Sample1.xml", simpleclass.get(), true);
#endif // KIGS_TOOLS

Corresponding Sample1.xml file will look like this:

<?xml version="1.0" encoding="utf-8"?>
<Inst N="simpleclass" T="SimpleSampleClass">
    <Inst N="localtimer" T="Timer">
        <Attr N="Time" V="0.001191"/>
        <Attr T="float" N="floatValue" V="12.000000" Dyn="yes"/>
    </Inst>
</Inst>

Import

Import is always available (in all build configurations).

// import instances from file "Sample1.xml"
CMSP imported=CoreModifiable::Import("Sample1.xml");

Find all the sample code from this article in Sample2 project on GitHub (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

• 31^st January, 2020: Initial version
• 2^nd February, 2020: Small fix in addItem / removeItem prototype
• 7^th February, 2020: Added latest published article in the series
• 14^th February, 2020: Article (4/8) added to the series
• 21^st February, 2020: Article (5/8) added to the series and little bug fix in code
• 2^nd March, 2020: Article (6/8) added to the series
• 19^th March, 2020: Article (7/8) added to the series, and fix GetInstances methods prototype in samples
• 17^th June, 2020 : Added final article of the series 
• 1^st March, 2023: Update after framework refactoring