# Implementation

This page gives an overview of how Behaviors can be implemented.

#### **How to implement a Behavior**

There is very little difference between implementing a Widget and implementing a Behavior. Though there are some difference which will be explained below.

##### Base Class

The major difference is that Behaviors need to be derived from the [Candera::Behavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_behavior.html "Behaviors are small re-usable functional blocks that communicate via events. Behaviors are based on W...") base class instead of the [Candera::WidgetBase](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_widget_base.html "Abstract base class for Candera Widgets.") class. Incidentally the [Candera::Behavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_behavior.html "Behaviors are small re-usable functional blocks that communicate via events. Behaviors are based on W...") base class is internally derived from [Candera::WidgetBase](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_widget_base.html "Abstract base class for Candera Widgets.") further demonstrating the similarities between both.

<div class="contents" id="bkmrk-"><div class="contents"><div class="textblock">  
</div></div></div>##### Methods

<div drawio-diagram="2350"><img src="https://doc3161en.candera.eu/uploads/images/drawio/2023-02/drawing-7-1677203692.png" alt=""/></div>

From the [Candera::WidgetBase](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_widget_base.html "Abstract base class for Candera Widgets.") the already known Init() and Update() methods are inherited.

<div class="contents" id="bkmrk-init%3A-called-once-wh"><div class="contents"><div class="textblock">

- **Init:** Called once when the Widget/Behavior is created, after all Widget/Behavior properties have been set. This is used to initialize the Widget/Behavior.
- **Update:** Called once per iteration (frame). Here normally the Widget/Behavior performs its actual functionality.

</div></div></div>Newly added are the methods from [Candera::Behavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_behavior.html "Behaviors are small re-usable functional blocks that communicate via events. Behaviors are based on W...") which are related to event handling and the attached node:

<div class="contents" id="bkmrk-dispatchevent%3A-start"><div class="contents"><div class="textblock">

- **DispatchEvent:** Starts dispatching an event with a specified strategy
- **OnEvent:** Called when an event is received by a Behavior
- **SetNode/GetNode:** Allows access to the node this behavior is attached to. Note that this uses a new data type called [Candera::AbstractNodePointer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_abstract_node_pointer.html "The class AbstractCameraPointer is an wrapper class to abstract 2D and 3D camera nodes.") which abstracts between 2D and 3D nodes. This allows creating behaviors that work und 2D and 3D without duplicating code.

</div></div></div>##### META INFO

The Meta-Info is essential to provide generic access to all properties of the widget/behavior as well as special information for Scene-Composer about the available properties, their types and functionality. The available macros to define the Meta-Info are very similar to those used by widgets.

The first set of Macros defines a Behavior either for 3D, 2D or both (mixed):

```
    ...
    <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#gac11e42b36cc6ee1a4814d07df4abff9b">CdaBehaviorDef</a>(<<ClassName>>, <<BaseClassName>>)
        [Information][Properties][Events] 
    <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#ga1d66b72219f10490bc1faf9e1c2445bf">CdaBehaviorDefEnd</a>() 
    ... 
```

```
    ...  
    <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#ga0df74c6a17b4313fffc1084d9fb4e60d">CdaBehavior2DDef</a>(<<ClassName>>, <<BaseClassName>>)
        [Information][Properties][Events] 
    <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#ga1d66b72219f10490bc1faf9e1c2445bf">CdaBehaviorDefEnd</a>() 
    ...
```

```
    ...  
    <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#gaa6c7bb84ac98320b27829f415f095ed9">CdaBehaviorMixedDef</a>(<<ClassName>>, <<BaseClassName>>)
        [Information][Properties][Events] 
    <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#ga1d66b72219f10490bc1faf9e1c2445bf">CdaBehaviorDefEnd</a>()
    ...  
```

All other macros are the same as where used by Widgets. This includes the macros to add additional information:

```
    ...  
    CdaReadableName("Name")
    CdaCategory("Category")  
    CdaDescription("Description")
    ...  
```

As well as the macros to define properties:

```
... 
CdaProperties() 
...     [Property List] 
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___widget_base.html#gaadabeed44f0653634b664191cd875742">CdaPropertiesEnd</a>() 
...
```

```
... 
CdaProperty(<<Name>>, <<Type>>, <<Setter>>, <<Getter>>) 
CdaDescription("Column used by this Item inside the Area") 
CdaCategory("Area") 
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___meta_info.html#ga119bef57449bd05d8b3c40d7d514e375">CdaPropertyEnd</a>() 
... 
```

The new macros for events will be described in the <span style="color: rgb(230, 126, 35);">[Event Handling](https://doc3161en.candera.eu/link/570#bkmrk-event-handling)</span> chapter.   
For further information about the Meta Info please also see chapter <span style="color: rgb(230, 126, 35);">[Behavior Definition](https://doc3161en.candera.eu/link/568#bkmrk-page-title)</span>.

##### RUNTIME TYPE INFORMATION

CGI-Studio uses its own RTTI system for major parts instead of relying on the RTTI of the compiler. For this a set of macros is added to each class that uses this system. In case of Behaviors only a single macro is required to be added to the code:

```
... 
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#gade83d69bfb6ff6767119bbc71d3b76de">CGI_BEHAVIOR_RTTI_DEFINITION</a>(<<ClassName>>) 
... 
```

<div class="contents" id="bkmrk--1"><div class="contents"><div class="textblock"><div class="fragment">---

</div></div></div></div>#### **Event Handling**

Events are one of the major new features introduced via Behaviors. This chapter shows how they can be utilized from within the Behavior code.

##### Meta Info

The first requirement is to add all events that should are either received or sent to the Meta-Info via the following macros:

```
... 
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#gacffa930ff589666f40b4cfe1101e82fe">CdaEvents</a>()    
   <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#gaf18af8294463f4c87092b0dd719ce807">CdaEvent</a>(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#ga1f87d4147378125fc817898dd84e98eb">CdaOutputEvent</a>, <<EventType>>, "Description")    
   <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#gaf18af8294463f4c87092b0dd719ce807">CdaEvent</a>(CdaInputEvent, <<EventType>>, "Description") 
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#gaca0f18f1742e7e52edc48d782d902a7b">CdaEventsEnd</a>() 
...
```

##### Sending Events

An Event can be sent by multiple different approaches.

The first is achieved by calling the DispatchEvent() method of the Behavior or any of the other available alternatives. It requires providing the dispatch strategy and event itself. When using this method the dispatching will start from the current node of the Behavior.

```
... 
    CgiStudioControl::Event event;     
    EventDispatchResult dispatchResult;     
    EventDispatchStrategy dispatchStrategy; 
 
    DispatchEvent(dispatchStrategy, event, dispatchResult); 
... 
```

<div class="header" id="bkmrk-note-that-the-event-"><div class="header"><div class="headertitle"><div class="title"><div class="contents"><div class="contents"><div class="textblock"><div class="fragment">  
</div><dl class="note"><dd></dd><dd><p class="callout info">Note that the Event and EventDispatchStrategy need to be replaced with the concrete implementations.</p>

</dd><dd></dd><dd>The second options is to directly call the DispatchEvent() method of the Event-Dispatch-Strategy. This allows to define the node from which the dispatching should start:</dd><dd></dd></dl></div></div></div></div></div></div></div>

```
... 
    Candera::EventDispatchResult eventDispatchResult; 
    <a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_broadcast_event_dispatch_strategy.html" title="Broadcast strategy: the event will be dispatched first for the node with a Direct strategy and then f...">Candera::BroadcastEventDispatchStrategy</a> dispatchStrategy; 
    <a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_cgi_studio_control_1_1_change_value_event.html" title="Received by a ValueBehavior to change the value. Value can be absolute or relative (will be added)...">CgiStudioControl::ChangeValueEvent</a> valueChangedEvent(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_variant.html">FeatStd::Variant</a>(listDataEvent->GetData()),                                                            
                                                         CgiStudioControl::ChangeValue::Absolute); 
    dispatchStrategy.<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_broadcast_event_dispatch_strategy.html#a2147a1a0a6eb0d4f93cd32dcd9404698">DispatchEvent</a>(GetNode(), valueChangedEvent, eventDispatchResult); 
... 
```

##### Receiving Events

Receiving of events is done via the OnEvent-Method. Here normally the incoming events are type-cast to check the Event-Type and processed if applicable. Further it is possible to stop further dispatching of the event via the Dispatch-Result. In case a custom Dispatch-Result is used (again type-casting can be used) then additional information can be returned to the sender.

```
... 
void ListItemEventBehavior::OnEvent(const <a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_event.html" title="Event serves as a base class for user derived events.">FeatStd::Event</a>& event, Candera::EventDispatchResult& dispatchResult) 
{     
    const ListDataEvent* listDataEvent = Candera::Dynamic_Cast<const ListDataEvent*>(&event); 
 
    if (0 != listDataEvent) {         
        if (m_index == listDataEvent->GetIndex()) {             
            dispatchResult.StopDispatchingImmediately(); 
 
            // Do something with the data of the event         
        }     
    } 
} 
... 
```

If derived from Behaviors that also do event processing also the Base-Class OnEvent method should be called.

```
... 
Base::OnEvent(event, dispatchResult); 
... 
```

##### Custom Events

It is possible to define custom events by simply deriving from [FeatStd::Event](http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_event.html "Event serves as a base class for user derived events.") class. An Event can contain any number custom data.

```
... 
class ListDataEvent : public FeatStd::Event 
{     
    public:         
        FEATSTD_RTTI_DECLARATION(); 
 
        ListDataEvent(FeatStd::Int32 index, FeatStd::Int32 value) :             
            m_index(index),            
            m_value(value)         
        {         
        } 
 
        FeatStd::Int32 GetIndex() const         
        {             
            return m_index;         
        } 
 
        FeatStd::Int32 GetData() const         
        {             
            return m_value;         
        } 
 
    private:         
        FeatStd::Int32 m_index;         
        FeatStd::Int32 m_value; 
}; 
...
```

```
... 
FEATSTD_RTTI_DEFINITION(ListDataEvent, <a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_event.html" title="Event serves as a base class for user derived events.">FeatStd::Event</a>) 
... 
```

##### FINDING BEHAVIORS

The second major advantage compared to widgets is that it is now possible to determine if any and which Behaviors are attached to a node. This can be done by iterating over all behaviors of a node via the code snipped shown below.

```
... 
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_behavior.html" title="Behaviors are small re-usable functional blocks that communicate via events. Behaviors are based on W...">Candera::Behavior</a>* behavior = <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#ga69a5dc63c0630e3ee64ada60854041bb">Candera::Behavior::GetFirstBehavior</a>(node); 
 
while (0 != behavior) {     
    // do something 
 
    behavior = behavior-><a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behavior_base.html#gaeb8b1c6d391f8a18e57bf8b3a570239c">GetNextBehavior</a>(); 
} 
...
```

For a better understanding of how events work, please see chapter <span style="color: rgb(230, 126, 35);">[Predefined Behaviors](https://doc3161en.candera.eu/link/566#bkmrk-page-title)</span>.

<div class="contents" id="bkmrk--2"></div>#### **Creating a custom Behavior**

<div id="bkmrk-first-to-create-a-cu">First to create a custom Behavior for most of them a Base Behavior has to be implemented. (If the Base Behavior is not needed the next few steps can be skipped)</div><div id="bkmrk--3">  
</div><div id="bkmrk-to-do-this-achieve-t">To do this achieve that a &lt;CUSTOMBEHAVIOR&gt;Base.xhcdl file has to be created.</div><div id="bkmrk-this-file-contains-t">This file contains things like: includeName, behavior name, readableName, category, properties and the UUID.</div><div id="bkmrk-these-need-to-be-fil">These need to be filled out for the specifications of the Behavior.</div><div id="bkmrk--4">  
</div><div id="bkmrk-samples-for-this-fil">Samples for this file can be found under: "...\cgi_studio_controls\src\Behaviors". Just select a BehaviorBase.xhcdl which has similarities with the custom behaviour copy it and modify it to the special needs.</div><div id="bkmrk--5">  
</div><div id="bkmrk-if-the-file-is-finis">If the file is finished add it to the "...\cgi_studio_controls\src\Behaviors\Behaviors.xhcdl" file in this way:</div><div id="bkmrk--6"></div><div id="bkmrk-behaviors.xhcdl-%3Cinc"><table border="1" style="border-collapse: collapse; width: 100%; border-width: 1px; border-style: dashed;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>**Behaviors.xhcdl**</td></tr><tr><td>

```
<include href="<BEHAVIORFOLDER>/<CUSTOMBEHAVIOR>Base.xhcdl" />
```

</td></tr></tbody></table>

</div><div id="bkmrk-next-start-the-%22...%5C">Next start the "...\cgi_studio_controls\src\Behaviors\GenerateBehaviors.bat". This file then generates the &lt;CUSTOMBEHAVIOR&gt;Base.h and &lt;CUSTOMBEHAVIOR&gt;Base.cpp files.</div><div id="bkmrk--8">  
</div><div id="bkmrk-after-this-step-is-c">After this step is completed the actual Behavior logic has to be written. The &lt;CUSTOMBEHAVIOR&gt;.h/.cpp files will be made and the files of other already implemented Behaviors can serve as the Template for the custom Behavior.</div><div id="bkmrk--9"><div class="align-left">  
</div></div>##### **Adding the Behavior to the entire CGI Studio:**

<div id="bkmrk-if-the-intention-is-"><div>If the Intention is to use the Behavior in every CGI Studio project it can be added to the whole Studio.</div><div>  
</div><div>For this the &lt;CUSTOMBEHAVIOR&gt;Base.h/.cpp have to be added to "...\cgi_studio_controls\src\Behaviors\&lt;BEHAVIORFOLDER&gt;\generated\FileList.cmake" in this manner:</div><div><table border="1" style="border-collapse: collapse; width: 64.5238%; border-width: 1px; border-style: dashed; height: 122.4px;"><thead><tr style="height: 33.6px;"><td style="height: 33.6px; border-width: 1px;">**FileList.cmake**</td></tr></thead><tbody><tr style="height: 88.8px;"><td style="height: 88.8px; border-width: 1px;">

```
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>Base.h"
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>Base.cpp"
```

</td></tr></tbody></table>

</div><div>Next the &lt;CUSTOMBEHAVIOR&gt;.h/.cpp as well as &lt;CUSTOMBEHAVIOR&gt;Base.xhcdl have to be added to "...\cgi_studio_controls\src\Behaviors\&lt;BEHAVIORFOLDER&gt;\FileList.cmake" like this:</div><div>  
</div><div><table border="1" style="border-collapse: collapse; width: 65.3571%; border-width: 1px; border-style: dashed;"><tbody><tr><td>**FileList.cmake**</td></tr><tr><td>

```
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>Base.xhcdl"
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>.h"
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>.cpp"

```

</td></tr></tbody></table>

</div><div>After these two steps the Behavior can be build with CMake and then Visual Studio. (For a Guide how to do that have a look at the Wiki Page: [Building-Player-and-Widgets](https://doc3161en.candera.eu/books/build-system-setup/page/building-player-and-widgets))</div><div>  
</div><div>After opening Visual Studio ALL_Build -&gt; Build can be started which is found under CMakePredefinedTargets.</div><div><div drawio-diagram="8990"><img src="https://doc3161en.candera.eu/uploads/images/drawio/2026-04/drawing-7-1777357420.png" alt=""/></div>

</div>Now CGI Studio can be opened and the custom Behavior can be used. <div>  
</div></div>##### **Adding the Behavior to a specific Project:**  


<div id="bkmrk-to-add-a-behavior-to">To add a Behavior to a specific Project the "...\cmake\Apps\Courier\CourierSampleApp\CMakeLists.txt" of the Project has to be modified with this line. (CUSTOMBEHAVIOR_FOLDER has to be substituted with the actual folder name)</div><div id="bkmrk--12"></div><div id="bkmrk-cmakelists.txt-add_s"><table border="1" style="border-collapse: collapse; width: 105.119%; border-width: 1px; border-style: dashed; height: 110.4px;"><colgroup><col style="width: 100%;"></col></colgroup><tbody><tr style="height: 29.6px;"><td style="height: 29.6px;">**CMakeLists.txt**</td></tr><tr style="height: 80.8px;"><td style="height: 80.8px;">

```
add_subdirectory("${CANDERA_ROOT_PATH}/<CUSTOMBEHAVIOR_FOLDER>" "${CMAKE_BINARY_DIR}/<CUSTOMBEHAVIOR_FOLDER>")
```

</td></tr></tbody></table>

</div><p class="callout warning">**Important:** This include has to be after all other includes, because some of them clear the Behavior list.</p>

<div id="bkmrk-next-the-%3Ccustombeha">Next the &lt;CUSTOMBEHAVIOR_FOLDER&gt; has to be created in the Candera root Directory. This folder then needs to include CMakeLists.txt as well as a FileList.cmake.</div><div id="bkmrk--13"></div><div id="bkmrk--14"></div><table border="1" id="bkmrk-cmakelists.txt-%23-cre" style="border-collapse: collapse; width: 100%; border-width: 1px; border-style: dashed;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>**CMakeLists.txt**</td></tr><tr><td>

```
# Creation of new dedicated behavior project
project(MyCustomBehaviors)
add_library(${PROJECT_NAME})

#----------------------------------------------------------------------
# collecting all files
include("${CMAKE_CURRENT_LIST_DIR}/FileList.cmake")

# load the paths as sources into 'all_sources'
get_target_property(all_sources ${PROJECT_NAME} SOURCES)

# create a structured visualization inside the solution
source_group(TREE ${CMAKE_CURRENT_LIST_DIR} FILES ${all_sources})

#----------------------------------------------------------------------
# this is the include path to the custom behaviors which shall be used.
target_include_directories(${PROJECT_NAME}
  PUBLIC
  ${CMAKE_CURRENT_LIST_DIR}
)

#----------------------------------------------------------------------
# definition of which project must be linked
# if application parts like application lib is required, please link the project accordingly.
target_link_libraries(${PROJECT_NAME}
  PUBLIC
  Candera
)

#----------------------------------------------------------------------
# These two calls attach a Behavior project to the internal Behavior set.
# IMPORTANT: the 0 at the end tells the system that already existing behaviors should not be cleared.
CgiBehaviorSet_AddTarget(${PROJECT_NAME} 0)
CgiCreateBehaviorPartSet("${PROJECT_NAME}" "BehaviorSet_${PROJECT_NAME}")
```

</td></tr></tbody></table>

<table border="1" id="bkmrk-filelist.cmake-targe" style="border-collapse: collapse; width: 100%; height: 59.2px; border-width: 1px; border-style: dashed;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr style="height: 29.6px;"><td style="height: 29.6px;">**FileList.cmake**</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">

```
target_sources(${PROJECT_NAME}
  PRIVATE
  "${CMAKE_CURRENT_LIST_DIR}/FileList.cmake"
)
include("${CMAKE_CURRENT_LIST_DIR}/Behaviors/FileList.cmake")

```

</td></tr></tbody></table>

After that we need to create another folder in our initial &lt;CUSTOMBEHAVIOR\_FOLDER&gt;.

<p class="callout warning">**Important:** This folder has to be named "Behaviors".</p>

Into this folder we paste our custom Behavior files. (&lt;CUSTOMBEHAVIOR&gt;Base.h/.cpp, &lt;CUSTOMBEHAVIOR&gt;.h/.cpp, &lt;CUSTOMBEHAVIOR&gt;Base.xhcdl)

Then we create another FileList.cmake where we add lines for all our custom Behavior files as seen below.

<table border="1" id="bkmrk-filelist.cmake-targe-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>**FileList.cmake**</td></tr><tr><td>

```
target_sources(${PROJECT_NAME}
  PRIVATE
  "${CMAKE_CURRENT_LIST_DIR}/FileList.cmake"
  
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>Base.h"
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>Base.cpp"
  
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>Base.xhcdl"
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>.h"
  "${CMAKE_CURRENT_LIST_DIR}/<CUSTOMBEHAVIOR>.cpp"

)

```

</td></tr></tbody></table>

<div id="bkmrk--15"><div>  
</div></div><div id="bkmrk-after-these-steps-th">After these steps the Behavior can again be build with CMake and then Visual Studio. (For a Guide how to do that have a look at the Wiki Page: [Building-Player-and-Widgets](https://doc3161en.candera.eu/books/build-system-setup/page/building-player-and-widgets))</div><div id="bkmrk--16">  
</div><div id="bkmrk-after-opening-visual">After opening Visual Studio ALL_Build -&gt; Build can be started which is found under CMakePredefinedTargets.</div><div id="bkmrk--17"><div drawio-diagram="8991"><img src="https://doc3161en.candera.eu/uploads/images/drawio/2026-04/drawing-7-1777357479.png" alt=""/></div>

</div><div id="bkmrk--20">  
</div><div id="bkmrk-now-the-specific-pro">Now the specific Project can be opened and the custom Behavior can be used.</div>