# Advanced Cluster Solution # Overview This solution represents an advanced 2D cluster example. It consists of various scenes that are necessary to represent an advanced Cluster. The Main Scene consists of gauges that can be manipulated with Controls and Behaviors. This documentation includes a tutorial of how this advanced gauges can be implemented without coding. Other scenes, like the coverflow, show some other interactions in the solution and how this can be achieved with Behaviors. Culture is also used to support switching between display languages. Furthermore, a scene with a dynamic list is included in the sample. The dynamic list is the result of the tutorial that can be found under [Dynamic List](https://doc316en.candera.eu/link/293#bkmrk-page-title). Advanced Cluster Part 1 to Part 4 are step-by-step tutorial of customizing a gauge by using the built in controls as a base. More design elements and behaviors are used to change its look and extend its logic. The gauges represent the main scene of this sample solution.
- [Advanced Cluster Part 1](https://doc316en.candera.eu/link/275#bkmrk-page-title) - [Advanced Cluster Part 2](https://doc316en.candera.eu/link/277#bkmrk-page-title) - [Advanced Cluster Part 3](https://doc316en.candera.eu/link/278#bkmrk-page-title) - [Advanced Cluster Part 4](https://doc316en.candera.eu/link/280#bkmrk-page-title) ---
# Advanced Cluster Part 1 This section of the Best Practice describes how to configure the **render target** for this solution. It shows how to imported images via **\[Import Resources\]**. Some of these images will be used in controls later. In order for them to correctly fit e.g. into a Gauge control they need to have their **pivot point** adjusted. Finally, a **Custom Gauge** control will be created based on Scene Composer's built-in Gauge control. #### Create Solution and Setup Render Target A new empty solution will be created and the render target configuration is performed. 1. Create a **new solution** using the Empty Solution template and save it as shown in [Creating a new Solution](http://cgi3151en.candera.eu/books/getting-started/page/creating-a-new-solution "Creating a new Solution"). - A new solution is created and saved. 2. In the Solution Explorer panel on the top left select "Scene3D" (under "Solution - Scenes") and delete it either using the <Del> key or via the context menu **\[Delete\]** as described in [Delete a Scene](http://cgi3151en.candera.eu/books/scene-design/page/delete-a-scene "Delete a Scene"). - A **\[Delete Items\]** dialog will popup. 3. Please resolve all dependencies with **\[Delete Usage Item\]** (which is the default) and click **\[OK\]**. - Scene3D will be deleted. 4. Activate the Render Targets panel on the top right and select **\[Display (0)\]**. In the Properties panel below change the display's X and Y Resolution. - The horizontal and vertical resolution of the display is defined. - The aspect ratio of the display will be calculated automatically.
**Target Item****Setting Value**
X Resolution 1680
Y Resolution 720
5. In the Render Targets panel select Scene2D\\Camera (0). In the Properties panel check the checkbox to **Enable Swapping**. - Swapping has been enabled for Scene2D's camera. - The display will be refreshed after each time this scene is rendered.
**Camera****Enable Swapping**
Scene2D\\Camera(0)TRUE
#### Import Images and Configure Pivot Hints The images needed for this solution will be imported. They will later be used to build up the gauge control. For correct positioning and alignment inside the control, the [Pivot Hints](https://doc316en.candera.eu/books/scene-design/page/pivot-hint "Pivot Hint") for these images need to be configured. Additionally, the Custom\_Gauge control will be created. 1. In the menu bar choose **\[Import\] - \[Import Resources...\]** as described in [How to Import Resources](http://cgi3151en.candera.eu/books/import-of-resources/page/how-to-import-resources "How to Import Resources"). - **\[Import Resources\]** dialog will be opened 2. Navigate to the following folder, select all files provided in this folder and press **\[Open\]**. **<cgi-studio-root>/cgi\_studio\_content/Resources/AdvancedCustomGauge** - **\[Import Images\]** dialog will be opened as seen in the image below the next step. 3. Use the settings as shown in the screenshot below and press **\[OK\]**. - The images have been imported into the solution and are ready to be used.

Select an item in the Solution Explorer panel to access its properties in the Properties panel.

4. To configure the [Pivot Hint](https://doc316en.candera.eu/books/scene-design/page/pivot-hint "Pivot Hint"), select the image in the **Solution Explorer** panel. In the **Properties panel** under **\[Bitmap\]** you can adjust the image's **Pivot Hint settings**. Configure the images with the values given in the table below. - The images' Pivot Hints are correctly configured to be used in Scene Composer's Gauge Control: The needle images' Pivot Hints are their **central point of rotation**. The other images' Pivot Hints are configured to align the images correctly in the Gauge Control.
**Image****Enable Pivot Hint****Pivot Hint**
**X****Y**
NeedleBmpTRUE17.50250.00
Needle\_LighterTRUE241.00245.00
Numbers\_0-24BmpTRUE325.00329.00
Numbers\_0-8BmpTRUE325.00 329.00
Points\_BlueBmpTRUE282.00282.00
Points\_Blue\_RedBmpTRUE282.00282.00
5. In the Toolbox panel's **\[Controls\]** section under "Common" **copy** the **Gauge Control** either via the context menu entry "Copy" or via the keyboard <Ctrl>+C. **Paste** the Gauge Control into the Solution Explorer's folder "Solution > Controls" either via the context menu entry "Paste" or via the keyboard <Ctrl>+V. - A copy of the Gauge Control has been created in the Scene Composer solution's Controls folder. 6. In the Solution Explorer panel **rename** the newly copied Gauge to **"Custom\_Gauge"** either via the context menu entry "Rename" or via the keyboard <F2>. - The copy of the Gauge Control in the Solution Explorer's Controls folder is called "Custom\_Gauge".

The image below shows where to copy the Gauge Control from and where to copy it to.

# Advanced Cluster Part 2 In this part of the Advanced Cluster Best Practice the Custom\_Gauge control will be extended with a ForegroundImage and a NeedleEffectImage and new images will be configured to change the control's appearance completely. #### Restructuring Custom\_Gauge Control 1. In the Solution Explorer double-click the "**Custom\_Gauge**". - The control "**Custom\_Gauge**" will be opened in the Scene Editor, ready to be edited. - Scene Tree will display the tree of nodes the control is composed of. 2. In the Scene Tree panel rename the "Group" node to "**Group\_Bitmaps**". - In the Scene Tree panel the Group node has been renamed.
**Rename from****Rename to**
GroupGroup\_Bitmaps
3. In the Scene Tree panel select the root node Custom\_Gauge. In the Properties panel's **\[Layouter\]** section change the Layout type from "Overlay" to "None". - The Layout Type has been changed. 4. In the Scene Tree panel right-click on the "BackgroundImage" and choose **\[Clone...\]** from the context menu. In the opening "Clone Item" dialog enter "ForegroundImage" as name and press **\[OK\]**. - A clone of "BackgroundImage" has been created. Its name is "ForegroundImage". The Scene Tree now looks as in the image below.
#### Exchanging Custom\_Gauge Control's Images In steps 1 - 3 of this section the Custom\_Gauge new images for the **ForegroundImage** and **BackgroundImage** nodes will be configured. These steps need to be performed for the BackgroundImage node as well as for the Foreground Image node. In steps 4 - 5 of this section the NeedleImage will be cloned and the images of NeedleImage and NeedleEffectImage will be exchanged. 1. In the Scene Tree panel select the image. In the right side of the Scene Tree click on the **\[Fusion...\]** button. - Fusion will be opened, displaying the Fusion diagram for the image.
2. In the Fusion diagram change the ProvideImageProperty's image by clicking the magnifying glass icon to the property's right. - The **\[Choose Item\]** dialog will be displayed. 3. In the **\[Choose Item\]** dialog choose the appropriate new image given in the table below and click **\[OK\]**. - The images displayed by the BackgroundImage and ForegroundImage nodes have been changed. - When activating the Scene Editor the Custom\_Gauge with new Foreground and Background image can be viewed. It should look like the image below.

To switch to the Fusion diagram of the second image simply double click it in the Scene Tree panel.

**Node****new ProvideImageProperty image**
BackgroundImageSolution > Resources > Bitmaps > Points\_Blue\_RedBmp
ForegroundImageSolution > Resources > Bitmaps > Numbers\_0-8Bmp
4. In the Scene Tree panel create a clone of the "NeedleImage" and name it "NeedleEffectImage". - A clone of "NeedleImage" has been created. Its name is "NeedleEffectImage". The Scene tree looks as in the image below.

Please follow the order of the nodes in the scene tree to ensure their proper visibility.

5. Let's change the images displayed by NeedleImage and NeedleEffectImage. This can be done similarly to above. Select the image, open Fusion and click on the magnifying glass next to the ProvideImageProperty's image property. Configure the images given in the table below. - The images displayed by the NeedleImage and NeedleEffectImage nodes have been changed. - When activating the Scene Editor the Custom\_Gauge with new Needle and NeedleEffect image can be viewed. It should look like the image below (the needle is pointing to 3 o'clock).
**Node****ProvideImageProperty's image**
NeedleImageSolution > Resources > Bitmaps > NeedleBmp
NeedleEffectImageSolution > Resources > Bitmaps > Needle\_LighterBmp
#### Configuring the Gauge Needle's Rotation Behavior 1. In the Scene Tree panel select the NeedleImage node. In the Scene Tree panel's right side rename the existing SetRotation behavior according to the table below. Repeat the same steps for the NeedleEffectImage node. - The SetRotation behaviors of NeedleImage and NeedleEffectImage have been renamed.
**Node****New Name of SetRotation Behavior**
NeedleImageSetRotation\_Needle
NeedleEffectImageSetRotation\_Effect
2. In the Scene Tree panel select the **Custom\_Gauge** node. In the Scene Tree panel's right side select the **InterpolateValue** behavior. In the Properties panel's **\[Receivers\]** section press the **\[+\]** button in the top right corner. This **\[+\]** button is marked in orange in the image of step 4. - In the Properties panel's Receivers section you can see that a new line for a **new Receiver** is added for the InterpolateValue behavior. 3. Press the magnifying glass icon next to the new **Receivers 1** entry. - The **\[Choose Item\]** dialog will be opened. 4. Select the behavior SetRotation\_Effect, which can be found under the path given below, and click **\[OK\]**. - The NeedleEffectImage's **SetRotation\_Effect** is referenced as one of the Receivers of the **CustomGauge's InterpolateValue** behavior as you can see in the imaged below.
**Set Rotation\_Effect****Path**
Custom\_Gauge > Group\_Bitmaps > NeedleEffectImage > **SetRotation\_Effect**
#### Configuring Effects and MapValue Behavior's Limits
1. In the Scene Tree panel select the **NeedleEffectImage** node. In the Scene Tree panel's right side under **\[Behaviors\]** select "**Blend Mode**" and press Delete on your keyboard to delete this behavior. - The behavior Blend Mode has been deleted. 2. While **NeedleEffectImage** is selected in the Scene Tree panel select the **BitmapBrushColorBlend** effect in the Scene Tree panel's right side and adjust its properties in the Properties panel according to the table below. - The BitmapBrushColorBlend effect is configured correctly. - In the Scene Editor you can see that the **NeedleEffectImage** is not a white gradient anymore. You can rather **perceive a slight change of color** compared to the original BackgroundImage (see image below, the needle is pointing to 3 o'clock).
**BitmapBrushColorBlend** **Property** **Value**
ColorBlendFactorSrcDestColor
ColorBlendFactorDstSourceAlpha
3. In the Scene Tree panel select the **Custom\_Gauge** node. In the Scene Tree panel's right side select the **MapValue** behavior. In the **Properties** panel configure its properties according to the table below. - The MapValue behavior's minimum and maximum value have been configured.
**MapValue Properties** **Value**
OutputMin-128.50
OutputMax128.50
# Advanced Cluster Part 3 In part 3 of this Best Practice the Custom\_Gauge control will be further customized adding controls: - A **TextValue control** to display the gauge's current value numerically - A **Text control** above of the numeric value to display the gauge's scope (e.g. speed) - Another **Text control** below the numeric value, which can be used to display the unit (e.g. km/h) In order to make our control more versatile, various properties of our configured Custom\_Gauge (like all images and text styles) will be made public.

**Public Control Properties** are those that can be configured when using a Custom\_Gauge in a scene.

#### Create and Configure Two TextNodes and a TextValue Node 1. In Scene Composer's Solution Explorer navigate to the path below and double-click on the "Custom\_Gauge" control. - The Scene Tree panel shows the Custom\_Gauge control's tree. - Scene editor displays the Custom\_Gauge control.
**Path in Solution Explorer****Control**
Solution/ControlsCustom\_Gauge
2. From the **Toolbox** panel's **Nodes 2D** section drag and drop a **StackLayout** into the Scene Tree panel directly onto the Custom\_Gauge node. - In the Scene Tree panel you can see that a **StackLayout** has been created directly under the Custom\_Gauge node. 3. From the **Toolbox** panel's **Controls** section under Common drag and drop **2 Text** controls and **1 Text Value** control into the Scene Tree panel directly onto the StackLayout. - In the Scene Tree panel you can see the **2 Text** controls and the **Text Value** control directly under the StackLayout. 4. In the Scene Tree panel select the **StackLayout** as well as the **2 Text** controls one after the other and rename them according to the table below either via the context menu entry "Rename" or by pressing <F2> on your keyboard. - In the Scene Tree panel you can see that the Controls have been renamed.
**Target Item****New Name**
StackLayoutStackLayout\_Texts
TextText\_Top
Text\_1Text\_Bottom
5. In the Scene Tree panel re-arrange StackLayout\_Texts and its contents via drag and drop until it looks like in the image below. - The Scene Tree looks as in the image below.
6. In the Scene Tree panel select StackLayout\_Texts controls. In the **Properties** panel under **Layouter** and **Layout** adjust the properties as in the table below. - In the Properties panel you can see that the correct values are set.
**Property****Value**
**Layouter**
ArrangementVertical
**Layout**
Vertical AlignmentVCenter
MinimumSize**X**250.00
**Y**0.00
7. In the Scene tree panel select **Text\_Top**, **Text Value** and **Text\_Bottom** one after the other. In the **Properties** panel under Layout and Control configure the properties as in the table below. - In the Properties panel you can see that the correct values are set. - In the Scene Editor the texts are centered and the Text Value appears in a bigger font.
**Property****Text\_Top****Text Value****Text\_Bottom**
**Layout**
VerticalAlignmentVCenterVCenterVCenter
HorizontalAlignmentHCenterHCenterHCenter
**Control**
TextRPM-<empty String>
Text StyleOpenSans35 Vera96OpenSans35
Text AlignmentCenterCenterCenter
Text Format-%04d-
#### Configure the TextNodes' and TextValue Node's Position 1. In the Scene Tree panel select **StackLayout\_Texts**. In the Scene Tree panel's right side click on the **\[Fusion...\]** button. - Fusion will be opened covering the Scene Editor. - StackLayout\_Texts Fusion diagram will be displayed. It only has one Fusion Node. 2. In Fusion use the StackLayout\_Texts' "Behaviors" connector to add 2 new Fusion Nodes: Connect **2 Value Processing > Value** behaviors to the StackLayout\_Texts Fusion Node.

Please check [Fusion's Basic Operations ](https://doc316en.candera.eu/books/fusion/page/basic-operations#bkmrk-adding-a-fusion-node)documentation on how to add Fusion Nodes.

- In Fusion 2 new Fusion Nodes "**Value**" and "**Value\_1**" have been created. 3. In Fusion select and right-click on the behavior nodes and rename them according to the table below. - In Fusion the Value behavior fusion nodes have been renamed.
**Target Item****New Name**
ValueValue\_TextPos\_X
Value\_1Value\_TextPos\_Y
4. In Fusion use the Value behaviors' "Receivers" connectors to add a **Value Processing > Transformation > SetPosition** Fusion Node to each of them. - In Fusion 2 new Fusion Nodes "**Set Position**" have been created, one of which is connected to Value\_TextPos\_X, the other to Value\_TextPos\_Y. 5. In Fusion select and right-click on the behavior nodes and rename them according to the table below. - In Fusion the **Set Position** behavior fusion nodes have been renamed.
**Target Item****New Name**
Value\_TextPos\_X > Set PositionSet Position\_X
Value\_TextPos\_Y > Set PositionSet Position\_Y
6. In Fusion configure the behaviors' Fusion Nodes according to the table below. - In Fusion the Fusion Nodes' Properties have been changed. - In Scene Editor the position of StackLayout\_Texts has been changed. The texts are now neatly placed inside the Custom\_Gauge control as you can see in the image below.
**Fusion Node**
**Property****Set Position\_X****Set Position\_Y**
TargetNodeCustom\_Gauge > StackLayout\_Texts Custom\_Gauge > StackLayout\_Texts
TranslationAxis2DAxisXAxisY
**Property****Value\_TextPosX****Value\_TextPosY**
Variant(Float) 205(Float) 230
#### Configure Value Forwarding and Maximum Value 1. In Fusion add a **Value Processing > Forward Value** behavior to the **Behaviors** connector of the **Custom\_Gauge** Fusion Node. Configure its **TargetNode** according to the table below. - In Fusion the property will be changed accordingly.
**Forward Value Fusion Node**
**Property****Value**
TargetNodeCustom\_Gauge > StackLayout\_Texts > Text Value
2. In Fusion in the **ControlValueProvider** Fusion Node configure the property **Maximum** according to the table below. - In Fusion the the property is changed accordingly. - Custom\_Gauge's Fusion diagram will look as in the image below.
**ControlValueProvider**
**Property****Value**
Maximum(Float) 8000.00
#### Configure Public Control Properties 1. In the Scene Tree panel right click "Custom\_Gauge" and select "**Control Properties...**" from the context menu. - The Configure Public Control Properties dialog will be opened. 2. In the Configure Public Properties dialog the Properties which should be public to the user of the Custom\_Gauge control need to be marked with the "Is Public" checkbox. Check the "Is Public" checkbox and eventually change the image properties' names according to the table and images below. - Image properties necessary for using and configuring the Custom\_Gauge will be made public. - The Custom\_Gauge control is now fully configured and ready to use.
**Custom\_Gauge > Group\_Bitmaps >**
**Property** **Is Public****Source****Name**
BackgroundImage > ProvideImagePropertyxImageBackgroundImage
NeedleImage > ProvideImagePropertyxImageNeedleImage
NeedleEffectImage > ProvideImagePropertyxImageNeedleEffectImage
ForegroundImage > ProvideImagePropertyxImageForegroundImage
3. In the Configure Public Properties dialog check the "Is Public" checkbox and perform other configurations according to the table and images below. - Image properties necessary for using and configuring the Custom\_Gauge will be made public. - The Custom\_Gauge control is now fully configured and ready to use.

The properties made public in this **Configure Public Properties** dialog will be configurable in the **Properties panel's Controls section**.

**Custom\_Gauge > StackLayout\_Texts >**
**Property****IsPublic****Source****Name**
TextBottomxTextBottom\_Text
xTextColorBottom\_TextColor
xTextStyleBottom\_TextStyle
Text\_TopxTextTop\_Text
xTextColorTop\_TextColor
xTextStyleTop\_TextStyle
Text ValuexFormatTextValue\_FormatText
xStyleValue\_Style
xTextColorValue\_TextColor
Behaviors > Value\_TextPos\_XxVariantTextPosX
Behaviors > Value\_TextPos\_YxVariantTextPosY
# Advanced Cluster Part 4 The following steps describe how to use the Custom\_Gauge control in a scene. Speed gauge and RPM gauge are realized with the same control. Using the public properties for customization these Gauge controls appear similar yet different. Once the advanced cluster scene is fully configured, it's time to test its functionality using the Scene Composer's [Player](https://doc316en.candera.eu/books/player "Player"). #### Create a Cluster Scene with 2 Custom\_Gauge Controls 1. In the Solution Explorer navigate to the Scene2D and double click it. - Scene2D will be opened and visible in Scene Editor and Scene Tree panel. - In Scene Tree panel you can see that the scene contains a camera. 2. In the **Scene Editor's bottom toolbar** make sure that "**active rendering**" and "**widgets updating**" is enabled. - In the Scene Editor's bottom toolbar "**active rendering**" and "**widgets updating**" are highlighted as seen in the image below.
3. From the Toolbox panel under **\[Nodes 2D\]** drag a **Group node** into the Scene Tree panel or the Scene Editor. - In the Scene Tree panel you can see the newly created Group node. - In the Scene Editor you can see an indicator of the Group node's current position. 4. **Rename** the **Group node** according to the table below either via the context menu "Rename" or the keyboard shortcut <F2>. - The Group node has been renamed accordingly.
**Old Name****New Name**
GroupGroup\_Content
5. In the Scene Tree panel select the Group node. In the Properties panel's **\[Transformations\]** section reset the Position property according to the table below. - In the Scene Editor you can see the Group node's current position.

A property can easily be **reset** in the Properties panel by clicking on the **curled arrow icon** on the property's left.

**Target Item****Position**
**X****Y**
Group\_Content0.000.00
6. From the Solution Explorer **drag** the **image** according to the table below into the Scene Tree panel **directly onto the Group\_Content** node. - In Scene Tree panel you can see that a new RenderNode2D with a BitmapBrushBlend effect has been created inside Group\_Content. - In Scene Editor you can see the rendered background image.
**Path in Solution Explorer****Image**
Solution > Resources > BitmapsBackgroundBmp
7. From the Solution Explorer drag **two** **Custom\_Gauge** into the Scene Tree panel directly onto the **Group\_Content**. The path to the Custom\_Gauge control is given in the table below. - In the Scene Editor only one Custom\_Gauge will be displayed since both controls are located at the same position and therefore are completely overlapping. One Custom\_Gauge is hiding the other. - In the Scene Tree panel the Group\_Content node contains a RenderNode2D and the newly created Custom\_Gauges.
**Path in Solution Explorer****Control**
Solution > ControlsCustom\_Gauge
8. **Rename** the **Custom\_Gauge** nodes according to the table below either via the context menu "Rename" or the keyboard shortcut <F2>. - The Custom\_Gauge node has been renamed accordingly.
**Old Name****New Name**
Custom\_GaugeCustom\_Gauge\_Speed
Custom\_Gauge\_1Custom\_Gauge\_RPM
9. Select the **Custom\_Gauge controls** one after the other. In the Properties panel **configure the properties** as given in the tables below. - In the Scene Editor the gauge controls for RPM and Speed are both visible. - The Scene2D starts to look like a cluster, see image below.
**Custom\_Gauge\_RPM Property****Value**
**Transformation**
Position X965.00
Position Y30.00
**Custom\_Gauge\_Speed Property****Value**
**Transformation**
Position X60.00
Position Y30.00
**Control**
Value120
Input Max240
Top\_TextSpeed
Value\_Format Text%d
Bottom\_Textkm/h
BackgroundImageSolution/Resources/Bitmaps/Points\_BlueBmp
ForegroundImageSolution/Resources/Bitmaps/Numbers\_0-240Bmp
#### Check the Scene in the Player 1. **Save** your work and **start** the **Player** to test the functionality of your configuration. To do this, please perform similar steps to the ones described in the [GettingStartedControls Best Practice](https://doc316en.candera.eu/books/best-practice/page/gettingstartedcontrols-part-1#bkmrk-check-the-first-scen). - The Speed Gauge can be tested by manipulating Custom\_Gauge\_Speed's Value Property (The property is changed to 50 in the image below). - The RPM Gauge can be tested by manipulating Custom\_Gauge\_RPM's Value Property.