# CGI Studio 3.5

Release Date: January 2018

# General 3.5

CGI1-21755 - CMake: Generated projects cause too long path names on Windows

Sometimes the path name length of the project files, that are generated by CMake, are too long for the Windows file system, depending on build folder path length, device, OS, CPU, ... Suffixes for the project names have been removed (in FeatStd and [Courier](http://dev.doc.cgistudio.at/APILINK/namespace_courier.html) CMake files).

---

# Candera 3.5

To keep backwards compatibility for any interface change in the public API the old interface has been kept and marked as deprecated. The deprecated interfaces will be removed in future versions. Compiler warnings will be generated when using a deprecated interface through the usage of Candera Macro CANDERA\_DEPRECATED\_3\_4\_0.

# Candera/FeatStd CMake Build System Changes

#### Clipping Enabled by Default

The flag CANDERA\_LAYOUT\_CLIPPING\_ENABLED was disabled by default. From now on the flag CANDERA\_LAYOUT\_CLIPPING\_ENABLED is enabled by default. Reason: for proper layout in terms of HMI controls the clipping of layout areas is mandatory. HMI controls are a major focus of CGI Studio 3.5.

---

# Candera Base

#### Cached Layout

A new (dynamic) property has been added to the [Layouter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_layouter.html "A non-zero padding applies space inside the element layout's width and height. The values can be set ...") class: Cached Layout It specifies if the layout of the node should be performed only once until a invalidation inside the subtree occurs. A cached layout will be only laid out again as soon as the layout of an inner node is marked as invalid. See Layouter::SetCached and Layouter::IsCached.

<p class="callout info">Widgets or Behaviors shall not invalidate the scene containing a laid out node anymore, but the according node! The default value of the new property is \_False\_.</p>

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

</div></div></div>#### Script Parameter Animation Property Setter

A new animation property setter has been added that can animate a numeric variable defined in a script.

---

# Candera System

#### Property of Type Variant

Support for widget / behavior properties of type [FeatStd::Variant](http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_variant.html) has been added. To use datatype serialization of type Variant it is necessary to add the following include statement:

```
#include <Candera/System/Mathematics/MathDataTypes.h>
```

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

</div></div></div></div>

# Candera AssetLoader

#### Property of Type Optional

Support for widget / behavior properties of type [FeatStd::Optional](http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_optional.html "The template class Optional is a wrapper for representing optional objects that may not have been ini...") has been added. To use datatype serialization of type Optional it is necessary to add the following include statement:

```
#include <CanderaAssetLoader/AssetLoaderBase/OptionalDataType.h>
```

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

</div></div></div></div>

# Textengine

#### Support of Monotype's font engine: iType

[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") supports the font engine 'iType' of 'Monotype' now. In this release a basic integration of iType was done. With the provided iType integration two different shaper are supported: Complex Script and NoShaper. Monotypes own shaper will be part of next releases.

The current integration of Monotype uses its default settings. Textrendering supports several glyph cache/render types: [Bitmap](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html "A 2-dimensional bitmap that can be used as a texture, background or sprite. A bitmap pointing to a va..."), Surface, Glyph, GlyphCache and GlyphAtlas. Two of these types are supported by iType now. These are [Bitmap](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html "A 2-dimensional bitmap that can be used as a texture, background or sprite. A bitmap pointing to a va...") and GlyphAtlas. The others may work but with cache functionality limitations. Therefore, it is not recommended to use one of the other caches. In general: best performances are reached when GlyphAtlas (GPU solution) or [Bitmap](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html "A 2-dimensional bitmap that can be used as a texture, background or sprite. A bitmap pointing to a va...") (CPU solution) is being used.

Due to different algorithms to interpret font data, it is expected to see small differences when comparing monotype and freetype content. E.g.:

<div class="contents" id="bkmrk-gray-values-%28transit"><div class="contents"><div class="textblock">- Gray values (transition between glyph and background) differ in its intensity.
- Applied glyph kerning may shift the text by 1 px.

</div></div></div>One of the great benefits of iType is its performance when it comes to rasterization of text. This is already visible in the first integration steps and provides a small forecast to the next steps.

---

# Candera Behaviors

#### Event Handler Behaviors

Classes have been added to support [Event](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_event.html) Handling. The [TriggerBehavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_trigger_behavior.html "The TriggerBehavior references a ConditionBehavior and an array of ActionBehavior. ConditionBehavior and ActionBehavior are base classes. Any input event is processed by a TriggerBehavior, which evaluates a condition (ConditionBehavior). If the condition evaluates to true, then the TriggerBehavior invokes one or more ActionBehavior. A filter on event type can be achieved by a specialized ConditionBehaviorclass for such an event.") references a ConditionBehavior and an array of [ActionBehavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_action_behavior.html "The Action Behavior is part of the Event Handling with Behaviors pattern. It follows the ECA (Event-C..."). ConditionBehavior and [ActionBehavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_action_behavior.html "The Action Behavior is part of the Event Handling with Behaviors pattern. It follows the ECA (Event-C...") are base classes. Any input event is processed by a [TriggerBehavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_trigger_behavior.html "The TriggerBehavior references a ConditionBehavior and an array of ActionBehavior. ConditionBehavior and ActionBehavior are base classes. Any input event is processed by a TriggerBehavior, which evaluates a condition (ConditionBehavior). If the condition evaluates to true, then the TriggerBehavior invokes one or more ActionBehavior. A filter on event type can be achieved by a specialized ConditionBehaviorclass for such an event."), which evaluates a condition (ConditionBehavior). If the condition evaluates to true, then the [TriggerBehavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_trigger_behavior.html "The TriggerBehavior references a ConditionBehavior and an array of ActionBehavior. ConditionBehavior and ActionBehavior are base classes. Any input event is processed by a TriggerBehavior, which evaluates a condition (ConditionBehavior). If the condition evaluates to true, then the TriggerBehavior invokes one or more ActionBehavior. A filter on event type can be achieved by a specialized ConditionBehaviorclass for such an event.") invokes one or more ActionBehaviors. A filter on event type can be achieved by a specialized ConditionBehavior class for such an event.

<div class="contents" id="bkmrk-value-processing-beh"><div class="contents"><div class="textblock">---

</div></div></div>#### Value Processing Behaviors

The ValueBehavior provides a Variant data type which is bindable. A value change results in a processing of that value by sending a [ProcessValueEvent](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_process_value_event.html "Event gets sent by Source Process Value Behaviors (Value Behavior) when value changed.") to a referenced [ProcessValueBehavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_process_value_behavior.html "The ProcessValueBehavior provides a Variant data type which is bindable. A value change results in a ..."). The [ProcessValueBehavior](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_process_value_behavior.html "The ProcessValueBehavior provides a Variant data type which is bindable. A value change results in a ...") base class has been added. Derived classes can be chained to realize a data flow processing from input to an according (visual) output. Example: from a changed "speed" value to a mapped rotation value and further to an animated rotation of a needle node.

---

# Candera Scripting

#### Script Events

This versions adds support for script events. Script events can be sent and received by both [Lua scripts](http://dev.doc.cgistudio.at/APILINK/group___lua_scripting_events.html) and [native code](http://dev.doc.cgistudio.at/APILINK/group___scripting_events.html).

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

</div></div></div>#### Candera Object References in Scripts

This versions adds support for referencing Candera objects in scripts. These object references are aware about the lifetime of the objects they reference without interfering with them. They can be passed from native code to scripts and vice versa, as well as dereferenced to call object specific methods in Lua.

<div class="contents" id="bkmrk--0"><div class="contents"><div class="textblock">---

</div></div></div>#### Lua Animation Functions

This versions adds support for [animations](http://dev.doc.cgistudio.at/APILINK/group___lua_binding_animation.html) in Lua scripts.

---

# Courier 3.5

<span style="color:rgb(34,34,34);font-size:1.666em;font-weight:400;">IPC dynamic Component Count and Process Count</span>

Due to a new concept of IPC messages more processes and components are allowed. Actually the size of a message is dynamic by compile time now. Note the following points:

<div class="contents" id="bkmrk-changed-componenttyp"><div class="contents"><div class="textblock">1. Changed ComponentType::Invalid to COURIER\_COMPONENT\_MAX\_COUNT.
2. All applications need the same COURIER\_COMPONENT\_MAX\_COUNT and COURIER\_PROCESS\_MAX\_COUNT to work properly.

---

</div></div></div>

# FeatStd 3.5

# FeatStd Util

#### Variant Type

A [Variant](http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_variant.html) data type has been introduced. The variant can hold a bool, UInt32, Int32 or Float value.

---

# SceneComposer 3.5

#### Property Editing Improvements

In CGI Studio SceneComposer for some properties the user can choose from a defined set of values e.g. the type of layout he wants to use (GridLayout, StackLayout...) or he can define the values for horizontal and vertical alignment. CGI Studio 3.5 offers intuitive icons to the user, so he can easily decide, which option he wants to take. Tooltips when hovering these icons make these icons even more user friendly.

Several items have properties where more than one value can be entered:

<div class="contents" id="bkmrk-position-properties-"><div class="contents"><div class="textblock">- position properties require a value for the x- and a value for the y-coordinate
- size properties require a value for the x- and a value for the y-coordinate
- margin properties even require 4 values (for left, top, right and bottom)

</div></div></div>With CGI Studio 3.5 the input fields for these values are positioned next to each other in multiple columns to save space and reduce scrolling effort.  
At the same time, the appearance of the properties has been very much improved and looks a lot tighter.

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

</div></div></div>#### Nine-Patch

When scaling images, the loss of too much quality shall be prevented. To optimize the scaling process, with CGI Studio 3.5 each image allows the configuration as Nine-Patch. By defining four stretchable areas for left, top, right and bottom, the image will be divided into 9 differently scaled patches (thus Nine-Patch) as seen in the image below. The Nine-Patch configuration is considered at any kind of scale operation - no matter if it is a manual scale operation or during layout calculation.

<div class="contents" id="bkmrk-see-also%3A-9-patch-im"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color:rgb(230,126,35);">[9-patch image](https://doc316en.candera.eu/link/291#bkmrk-page-title)</span> in SceneComposer User Manual
- <span style="color:rgb(230,126,35);">[Tutorial 14: 9-patch image](https://doc316en.candera.eu/link/429#bkmrk-page-title)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Pivot Hint

In addition to optimized resizing of images using the Nine-Patch approach described above, the user can define a Pivot Hint for each image. Additionally the Pivot Hint is used by Behaviours to allow them to set a Pivot Offset to an image that has been set.

<div class="contents" id="bkmrk--0"><div class="contents"><div class="textblock">---

</div></div></div>#### State Machine

Since this version on CGI Studio introduces support for a new integrated solution to model behaviour based on the "state machine" concept. By using traditional design means, multiple state machines can be defined. A state machine contains states and transitions and allows defining model changes into the graphical model when certain conditions are met. The state machine links work-flow logic to existing CGI Studio graphical items and building blocks such as behaviours and controls.

<div class="contents" id="bkmrk-see-also%3A-state-mach"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color:rgb(230,126,35);">[State Machine](https://doc316en.candera.eu/books/state-machine)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Controls &amp; Behaviours

There is a bunch of new predefined Controls in SceneComposer. They cover many elements necessary in a user interface. Among those Controls are a progress-bar, gauge, telltale, list, button, slider and many more. Controls quicken the process of HMI development massively. The HMI elements can interact with each other and because of the underlying Behaviors no single line of code has to be written for many use cases.

To make these Controls work and to be able to define own Controls, the list of Behaviors has increased significantly. There are many different Behaviors reaching from Event Handling to Value Processing.

<div class="contents" id="bkmrk-see-also%3A-controls-%26"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color:rgb(230,126,35);">[Controls &amp; Behaviours](https://doc316en.candera.eu/books/controls-and-behaviors)</span> in SceneComposer User Manual
- <span style="color:rgb(230,126,35);">[Getting Started with Controls](https://doc316en.candera.eu/books/best-practice/chapter/gettingstartedcontrols-solution)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Building Blocks for Behaviours

Behaviours can be nested and in this way combined to a reusable behaviour building block that is part of the solution and appears in the Solution Explorer. These behaviour blocks offer the possibility to configure, which of the properties of this behaviour block will be published and are therefore editable at the time the behaviour block is instantiated and used in the SceneComposer scene.

When many behaviors are nested, the hierarchy of the behaviors is shown trough the visualization of the behaviors integral map ( = "tree") structure. The tree structure of nested behaviors is now visualized properly in the Scene Tree View. This makes it easier to see, which behaviors belong together.

<div class="contents" id="bkmrk-see-also%3A-behavior-b"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color:rgb(230,126,35);">[Behavior Building Blocks](https://doc316en.candera.eu/link/567#bkmrk-page-title)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### EventHandler Tab

Every control needs an EventHandler in order to handle user events and take appropriate actions. With CGI Studio 3.5 an EventHandler Tab has been introduced in the Properties View for all Controls. In this EventHandler Tab the user can choose the event he wants to react on from a drop-down menu. Furthermore, conditions and actions can also be configured with drop-down menus in this tab. Having only a selection of suitable and applicable conditions available at configuration time after selecting an event makes this new EventHandler Tab a welcome and user friendly feature.

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

</div></div></div>#### Drop Shadow Effect

A drop shadow text effect was implemented in order to permit - in 2D scenes - the creation of visual effects similar to those available in other graphic tools. By using any of its properties - like "Distance", "Shadow Scale", "Blur Filter", "Light Angle" - the user has the possibility to set the shadow effect on any text as needed.

<div class="contents" id="bkmrk--2"><div class="contents"><div class="textblock">---

</div></div></div>#### Monotype

Font engine iType feature has been integrated. iType is a font engine which main purpose is fast and qualitative rasterization of fonts.

Monotype/iType has a special porting API with which target and OS specifics can be overridden. CGI Studio provides a single solution for all targets. For this, the framework links the API to the device and operating system layers. It is also possible to use an own customized port instead of the CGI Studio solution.

<div class="contents" id="bkmrk-see-also%3A-integratio"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color:rgb(230,126,35);">[Integration of Monotype](https://doc316en.candera.eu/link/294#bkmrk-page-title)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Candera Scripting

This versions adds support for script events. Script events can be sent and received by both [Lua scripts](http://dev.doc.cgistudio.at/APILINK/group___lua_scripting_events.html) and [native code](http://dev.doc.cgistudio.at/APILINK/group___scripting_events.html). At the same time, this versions adds support for [referencing Candera objects in scripts](http://dev.doc.cgistudio.at/APILINK/group___lua_object_references.html). These object references are aware about the lifetime of the objects they reference without interfering with them. They can be passed from native code to scripts and vice versa, as well as dereferenced to call object specific methods in Lua.

<div class="contents" id="bkmrk--3"><div class="contents"><div class="textblock">---

</div></div></div>#### New Data Types: Optional and Variant

Especially for the implementation of the new Behaviors new data types have been introduced.

<div class="contents" id="bkmrk-optional%3A-the-option"><div class="contents"><div class="textblock">- Optional: The Optional data-type allows the use of uninitialized objects. Therefore it provides methods to check whether the object has been initialized or not.
- Variant: The Variant data-type allows to store one value in different types. The type can be an integer, unsigned integer, floating point number or boolean.

---

</div></div></div>