GettingStartedControls Part 2

Part 2 of the GettingStartedControls Tutorial covers the creation of a scene for climate control using various predefined Scene Composer controls. As basis for part 2 of our GettingStartedControls creation tutorial please use your own created solution from part 1.

The final result of our ClimateControl Scene will look like this:

---

Preparing the Climate Scene

1. Create a new scene via the menu "Scene" - "New 2D Scene" or press < Ctrl+2 > on your keyboard
   
   • The "Add New Scene 2D" dialog will be opened.
     
2. In the first row select "/Scenes" from the drop-down menu. Enter "SceneClimate" as name and press [ OK ]. We use the prefix "Scene" to have all scenes listed next to each other in the Solution Explorer panel.
   • A new scene "SceneClimate" is created and visible in the Solution Explorer panel in folder "Scenes".
   • The new scene is opened in the Scene Editor and in the Scene Tree panel.
   • In the Scene Tree panel you can see that the scene already has a camera.
   • In the Render Targets panel you can see that the camera is already added to the RenderTarget.
     
     

     
     

3. In the Render Targets panel check the checkbox of "SceneClimate\Camera" in order to enable rendering.

Configure the ClimateScene's Layout

For the climate scene we will use a more realistic setup of the scene than before, because very often the layout of the elements of a scene are dependent to the screen size or language. Some languages for example are written from right to left and others from left to right. This for sure will influence the layout of texts and controls. Instead of absolute positioning of all elements, we will use a GridLayout.

1. In the Toolbox panel under [ Nodes 2D ] drag and drop a GridLayout (see image below) into the Scene Editor or into the Scene Tree panel on the SceneClimate node.
   • A GridLayout is visible in the Scene Tree panel.
   • It is also available in the Scene Editor, but only its pivot point is visible when it is selected.
     

     
     

2. In the Scene Tree panel right-click on the GridLayout to open the context menu and choose "Configure Layouter...".
   • The "Grid Layouter Editor" will popup where the GridLayout can be configured.
     

     
     

3. On the Grid Layout Editor's lower left corner, use the [ + ] buttons to add rows and columns (see image below). Configure 6 rows and 4 columns.
   • The GridLayout is configured with 6 rows and 4 columns.
     

     
     

4. Configure the columns' widths and the rows' heights according to the table below using the input fields on the top and right.
   • Rows and columns are configured as in the image above.

     Column	Width		Row	Width
     Column 1	0.05		Row 1	0.20
     Column 2	0.30		Row 2	0.20
     Column 3	0.50		Row 3	0.20
     Column 4	0.05		Row 4	0.20
     			Row 5	0.20
     			Row 6	0.20

5. When you're done configuring, press the [ OK ] button.
   • The Grid Layout Editor will be closed.

     Be aware that you cannot see the GridLayout. Its size is 0 as long as no size and no content for its cells has been configured.

     
     

6. In the Properties panel's [ Transformations ] section configure the following position of the GridLayout.
   
   • The position of the GridLayout in the Scene Editor has changed.
     

     Target Item	Setting Value
     Position X	0
     Position Y	0

7. In the Properties panel's [ Transformations ] section configure the following size of the GridLayout.

   The size is currently calculated automatically. In order to be able to change the values for the size, you have to click on the [ A ] button to disable the automatic calculation of the size.

    

   • The size of the GridLayout has changed.
   • The GridLayout's grid is now visible.
     

     Target Item	Setting Value
     Size X	1024
     Size Y	714

     

     
     

8. It is recommended to save the Scene Composer solution.
   

---

Creating and Configuring the Labels

Each of the Controls in the Climate Control Scene has a label, telling the user which setting he is able to change with it.

1. From the Toolbox panel drag and drop a "Text" control into the Scene Tree panel directly onto the "GridLayout" node. The "Text" control can be found in the Toolbox panel's [ Control ] section in the list of "Common" controls.
   • The "Text" Control can be seen in the Scene Editor's top left corner.
   • It is also visible in the SceneTree panel, hierarchically ordered below the GridLayout.
2. In the Properties panel's [ Control ] section click on the magnifying glass icon next to the "Text Style" property.
   
   • The "Text Style Palette" dialog will be opened displaying a list of text styles. The currently configured "OpenSans35" is selected.
     
3. In this "Text Style Palette" dialog select "OpenSans25" and click [ OK ]
   • In the Scene Editor the size of the "Text" control's text has decreased.
4. In the Scene Tree right-click on the "Text" control to open the context menu and select "Clone".
   • The "Clone Item" dialog is opened.
5. In the "Clone Item" dialog set the "Number of Copies" to 5 and click [ OK ].
   • In the Scene Tree panel you can see that 5 new "Text" controls have been added, named "Text_1", "Text_2" ...
     
6. In the Scene Tree panel right-click on the "GridLayout" and choose "Configure Layouter..." from the context menu.
   • The Grid Layout Editor will be opened.
   • The 6 "Text" controls are listed in the panel on the left.
   • By default the 6 "Text" controls are also positioned in the top left cell of the GridLayout.
7. In the "Grid Layout Editor" drag and drop the "Text" controls from the left into their destination cells one by one as seen in the image below and click [ OK ].
   • The "Text" controls' position in the GridLayout are now configured correctly.
   • In the Scene Editor you can see that the "Text" controls are now neatly positioned in the Scene.
   • The layout is done by the GridLayout according to its configuration.
     
8. In the Scene Tree panel select all "Text" nodes. Keeping the <SHIFT> key pressed allows you to add items to your selection. In the Properties panel's [ Layout ] section configure VerticalAlignment to "VCenter"
   • "VertigalAlignment" is configured to "VCenter" for all "Text" controls.
   • In the Scene Editor all "Text" controls are vertically centered in their cell.
     
     
9. In the Scene Tree panel select the "Text" controls one after the other and rename them either via the context menu entry "Rename" or by pressing <F2> on your keyboard. Apply the names provided in the table below.
   • In the Scene Tree panel you can see that the "Text" controls have been renamed.

     Target Item	Name
     Text	Text_Temperature
     Text_1	Text_Steering wheel heating
     Text_2	Text_Air Condition
     Text_3	Text_Fan
     Text_4	Text_Seat heater
     Text_5	Text_Heating

10. In the Scene Tree panel select the "Text" controls one after the other again and change text that is displayed by the "Text" controls according to the table below. This can be done in the Property panel's [ Control ] section.
    
    • In the Scene Editor you can see that the "Text" controls display different texts.

      Target Item	Text
      Text_Temperature	Temperature
      Text_Steering wheel heating	Steering wheel heating
      Text_Air Condition	Air Condition
      Text_Fan	Fan
      Text_Seat heater	Seat heater
      Text_Heating	Heating

      

Importing Images

This scene uses the built-in Scene Composer controls but they will be customized with new images. Therefore these images have to be imported into the Scene Composer solution.

1. In the main menu select Import > Import Resources...
   • The "Import Resources" dialog will be opened.
2. In the "Import Resources" dialog navigate to the path given in the table below. Select all 36 files and press [ Open ]
   • The "Import Images" dialog will be opened.

     Import Resources	Path
     	/cgi_studio_content/Resources/GettingStartedControls/Climate

3. In the "Import Images" dialog select folder "/Resources", make sure to create a new folder "Climate" for the imported images and click [ OK ].
   • In the Solution Explorer you can see that there is a new folder "Climate" in folder "Resources" that contains the 36 imported images.
   • The images have been imported and can be used in the Scene Composer solution.
     
     

Configuring the Layout for the Temperature

The temperature setting for this sample is composed by

• a Text Value control that will displays the current value
• a Slider control that shows the current value as well as the range of the possible values
• a Button control to decrease the currently set value
• a Button control to increase the currently set value
• a GridLayout that layouts the controls above.

The following steps show how to arrange all these fragments to a temperature configuration item.

1. From the Toolbox panel's [ 2D Nodes ] drag and drop a "GridLayout" into the Scene Tree panel directly onto the already configured "GridLayout" node.
   
   • In the Scene Tree the new GridLayout will be inserted as element of the already existing GridLayout.
2. From the Toolbox panel drag and drop a "Text Value" control into the Scene Tree panel directly onto the new GridLayout. The "TextValue" control can be found in the Toolbox panel's [ Controls ] section under "Common".
   • In the Scene Tree panel the "Text Value" control is visible as subordinates to the new GridLayout.
3. From the Toolbox panel drag and drop 2 "Button" controls and a "Slider" control into the Scene Tree panel directly onto the new GridLayout. "Button" and "Slider" control can be found in the Toolbox panel's [ Controls ] section under "Touchable".
   • In the Scene Tree panel the Buttons and the Slider are visible as subordinates to the new GridLayout.
4. In the Scene Tree panel rename the newly created controls according to the table below using the context menu or pressing <F2> on your keyboard.
   • In the Scene Tree panel the controls appear with their new names.

     Target Item	Name
     GridLayout	GridLayout_Slider
     Text Value	Text Value
     Button	Button_TempDec
     Button_1	Button_TempInc
     Slider	Slider_Temperature

5. In the Scene Tree panel right-click on GridLayout_Slider and choose "Configure Layouter..." from the context menu.
   • The "Grid Layout Editor" will be opened.
6. In the "Grid Layout Editor" configure 2 rows and 5 columns using the buttons on the bottom left.
   • In the "Grid Layout Editor" a grid with rows and columns will be displayed as configured.
7. In the "Grid Layout Editor" drag and drop the controls to their destination position as seen in the image below and click [ OK ].
   • The "Grid Layout Editor" is configured as in the image.
     
8. In the Scene Tree panel right-click on the (outer, older) GridLayout and choose "Configure Layouter..." from the context menu.
   
   • The "Grid Layout Editor" will be opened.
9. In the "Grid Layout Editor" drag and drop GridLayout_Slider into the cell right next to the "Text_Temperature" Text control. Then click [ OK ].
   • In Scene Editor GridLayout_Slider and all its content is now placed at the correct position.
     
     
     

Connect Slider and Text Value Control

The Temperature controls' functionality will be configured in the following steps: The slider's default, minimum and maximum values, the Text Value control's formatting text as well as the "Forward Value Behavior" that takes care that Slider and Text Value will display the same value at all times.

1. In the Scene Tree panel select the "Text Value" control. In the Properties panel apply the changes according to the table below.
   
   • In the Scene Editor, the "Text Value" will display "0.0°C" in the center.
     

     Item Name	Section	Property	Value
     Text Value	Control	Format Text	%2.1f°C
     	Layout	HorizontalAlignment	HCenter

2. In the Scene Tree panel select the Slider_Temperature. In the Properties panel in the [ Control ] section apply the changes according to the table below.
   
   • The slider's current value, its minimum and maximum value are configured.
   • In the Scene Editor the knob of the slider is on a different position than before.
     

     Item Name	Section	Property	Value
     Slider_Temperature	Control	Value	22
     		Minimum	15
     		Maximum	28

3. From the Toolbox panel's [ Behaviors ] section drag and drop a ForwardValue Behavior into the Scene Tree panel directly onto the Slider_Temperature. The ForwardValue Behavior can be found in the Toolbox panel's [ Behaviors ] section under "Value Processing".
   
   • In the Scene Tree an orange square appears next to the Slider_Temperature, indicating that this node has a behavior attached.
   • When selecting the Slider_Temperature in the Scene Tree, the attached Forward Value behavior is visible in the right side of the Scene Tree.
     
4. In the Scene Tree panel select Slider_Temperature and then select the Forward Value behavior in the right side of the Scene Tree panel. It's time to configure where the value should be forwarded to. In the Properties panel press the padlock icon on the top right to lock the Properties panel to the properties of the Forward Value behavior.
   • The pad lock icon changes to locked state.
   • The Properties panel is now locked to the properties of the Forward Value behavior.
5. From the Scene Tree panel drag and drop the Text Value control into the Properties panel directly onto the property "TargetNode".
   • In the Properties panel the textfield next to the property "TargetNode" will be filled with the path to the Text Value control.
6. In the Properties panel's top right, click on the padlock icon one more time to unlock the Properties panel again.
   • The padlock icon changes to unlocked state.
   • The Properties panel is unlocked again.
7. Press the <F5> key to trigger a refresh.
   • In the Scene Editor you can see that the Text Value will display "22°C", which is the value currently configured in the Slider control.
     

Beautifying Temperature Setting Controls

The default visual appearance of the Scene Composer's Slider does not fit to this sample's design. Luckily the Slider's images are exchangeable, so are the Button's images.

1. In the Scene Tree panel select Button_TempDec. In the Properties panel press the magnifying glass icon next to the property "Normal Image" to open the "Choose Item" dialog.
   • The "Choose Item" dialog will be opened.
2. Select image "/Resources/Climate/NewTempDecreaseBmp" and press OK.
   • The "Choose Item" dialog will be closed.
   • Property "Normal Image" is set to "NewTempDecreasBmp".
   • In the Scene Editor a new image will be displayed differently.
     
     
     
3. Repeat steps 1 and 2 to set a new "Pressed Image" for Button_TempDec. Finally, Button_TempDec should be configured according to the table below.
   
   • Button_TempDec is configured with new "Normal Image" and "Pressed Image" which completely changed its appearance.
     

     Target Item	Property	Image
     Button_TempDec	Normal Image	/Resources/Climate/NewTempDecreaseBmp
     	Pressed Image	/Resources/Climate/NewTempDecrease_pressedBmp

     
4. In the Scene Tree panel select Button_TempInc and repeat steps 1 to 3 above to configure new images for "Button_TempInc" according to the table below.
   
   • Button_TempInc is configured with new "Normal Image" and "Pressed Image" changing its appearance completely.
     

     Target Item	Property	Image
     Button_TempInc	Normal Image	/Resources/Climate/NewTempIncreaseBmp
     	Pressed Image	/Resources/Climate/NewTempIncreae_pressedBmp

     
5. In the Scene Tree panel select "Slider_Temperature". In the [ Control ] section of the Properties panel set new images according to the table below.
   • In the Properties panel the Slider Control's image properties are configured with new images.
   • In the Scene Editor you can see the final result of the configured Temperature Slider Control.

     Property	Image
     Knob Normal Image	/Resources/Climate/NewSliderKnobBmp
     Knob Pressed Image	/Resources/Climate/NewSliderKnobPressedBmp
     Track Image	/Resources/Climate/NewSliderBackgroundBmp
     Track Fill Image	/Resources/Climate/NewSliderBmp

     

Steering Wheel Heating

Setting up the Air Condition Controls

In this section we focus on the Radio Buttons for Air Condition (AC). Two Radio Buttons are configured inside a horizontal Stack Layout. They are grouped together in a GroupBox to help with the RadioButtons' functionality.

Configure the Steering Wheel Heating RadioButtons

To adjust the Radio Buttons to the general look and feel of the scene we will configure new images for them.

Remember: If you select both RadioButtons in a "multiple selection" in the Scene Tree panel, you can configure the properties that are the same for both RadioButtons at once.

Setting up the Fan Controls

Now we take care of the GridLayout_Fan. Open the "Configure Layouter…" dialog and configure the GridLayout as shown in the picture.
For the width of the third column, we are using the exact width of the MultiStateButton's image in order to get a pixel exact rendering of the image.

We now configure the images of the MultiStateButton. You can find a property "StateImages" in the Control section of the MultiStateButton's properties, where multiple images can be defined.

It is possible to add images using the "+" button or to remove images using the "x" button next to the image to be deleted (highlighted in the image above).
Please click on the magnifying glass to change the images. For our GettingStarted, we will configure the images from the climate folder of our resources ("NewClimate-0Bmp" - "NewClimate-7Bmp"). We have to change the Maximum State property to 7 in order to be able to display all selected images.

The MultiStateButton should be centered vertically, so we configure its layout accordingly.

To change the image of "Button_Fan Max" and "Button_Fan Off" use the resources available. A button needs two different images to be able to reflect a mouse press or a touch on a touch screen. Therefore we will change the normal and pressed image as shown below:

Improvement of Interactivity using Behaviors

We want to add the reset of the MultiStateButton_Fan to the off button and also we want to add the max functionality to the max button. To be able to do this we will need to use an Event Handler. When you select the "Button_Fan Off" you can recognize two tabs: an active "General" tab and an EventHandler tab:

Select this "Event Handler" tab to be able to attach functionality to the button. Use the "+" button next to "Actions" to add an action to the already attached "Click Event Handler".

Use the drop down menu to choose "Send Value As Event". Select the "MultiStateButton_Fan" as TargetNode using the magnifying glass.

The Event Handler tab should now look like this:

Due to the more complex possibilities of event handlers we will now explain in more detail what the different properties are usually used for.
With the Event drop down you can select on which type of event a certain action will be performed. In our case a click event(mouse click or touch) will trigger the action. For a description of available events please have a look inside the documentation FeatStd::Event. The Condition property can be used for some events to only react if a certain condition is evaluates to "true". For our case the "Check Click" will count the number of clicks happened and compares it with the given ClickCount property. We have provided AnyClick which means we will react on single, double and even triple clicks. With the Sender property we can give the Action Behavior additional information on who has executed the action. In our example we do not evaluate this and it is left empty.

The Value is used to specify the type of the value and the value itself which will be sent to the target node. ChangeValue states if the change of the value will be relative or absolute.
Last but not least the Target Node has to be specified to know who will be the receiver of the event.

We will now add a similar action to the "Button_Fan Max" button to always change the value of the MultiState button to its maximum value of 7.

Setting up the Seat Heater controls

For the Seat Heater controls, we just need to replace the images with new ones, as below:

Setting up the Heating controls

Last but not the least, we will configure the SpinBox. The SpinBox allows the user to change the values by clicking the uptick and downtick buttons.

We will configure the SpinBox control as follows. We will also change the images of the SpinBox Control.

Set the width of the SpinBox to 150. Please note that this is an automatically calculated property which has to be unlocked pressing the blue "A" button.

You have finished step 2 of our tutorial. Please save your solution before trying the result using the Player application. Generate an asset file as described at the end of Step 1. Load the generated asset into the Player and select the climate scene. You can now play around with the controls. Slide the temperature slider, use the check box and radio buttons. Click onto the fan multi state button and on off and max. Even the Seat heater will react on your actions.

Our next goal is to center all cell content vertically in order to have a similar distance between the lines. Even for multiple lines inside a cell the optical impression will be improved

We have already centered the text controls. Next, we will set VerticalAlignment of the following controls to VCenter:

Filling the GridLayout with Content

For the Steering heater text we adapt the settings to be able to use multiple lines. Check the "Multiline" property.

Please instantiate the following controls by dragging from the Toolbox to the SceneClimate root node:

Before structuring the Scene Tree, we rename the controls accordingly:

Now it's time to restructure the controls.

The following Radio Buttons will be placed inside the Stack Layout:

• RadioButton_AC On
  
• RadioButton_AC Off
  

And the StackLayout itself will be dragged into the content anchor of group box GroupBox_AC.

The elements for the fan will be dragged into the GridLayout_Fan:

• MultiStateButton_Fan
  
• Button_Fan Max
  
• Button_Fan Off

We will now remove all Solid Color Nodes and fill the GridLayout with our new controls.
Select all SolidColor Nodes and press the Delete key or use the context menu to delete them. Confirm deleting the SolidColorNodes in the delete items dialog with OK.
Drag all new items onto the "GridLayout" node. The resulting scene tree structure will look like this:

In the context menu of the GridLayout, click "Configure Layouter…".

Drag the elements to their positions.

The result should look like in the Scene Editor:

---

Setting up the Steering Wheel Heating Controls

To configure the heating controls, select the "CheckBox_Steering heater" and change its text to "On".
Finally, configure the images for "CheckBox_Steering heater" as below:

The configured "Checkbox_Steering heater" now looks like this.

---

Setting up the Air Condition Controls

In this section we focus on the radio buttons for Air Condition (AC). The Text of the Radio Buttons needs to be changed to "Off" and "On" in respect to their names. "RadioButton_AC Off" should be the one on the left, so you might have to change the order of the RadioButtons in the Scene Tree Panel.
Additionally, we have to configure the correct images for our RadioButtons. Remember if you select both RadioButtons in the Scene Tree panel, you can configure the images of both RadioButtons at once.

Keeping both RadioButtons selected, we will adjust the right margin to 100 so that there is enough space between them.

The default background of GroupBoxes makes them appear with a frame. As we don't want to see a frame in our design, we have to uncheck the "Enable Background" property of the GroupBox.

The height of our GroupBox_AC should be set to 40.
Currently the GroupBox height is calculated automatically based on the layout situation. Properties that are calculated automatically are displayed grayed out, the text "(Auto)" is displayed next to the value and you can see a button with an "A" on it next to it.
In order to be able to enter a value manually, you have disable the automatic calculation by pressing the blue "A" button first.

You can see the tooltip for the blue "A" button in the image below.

You might have wondered why we added a StackLayout previously. The reason is, the Stack Layout is able to layout child nodes horizontally or vertically. The "horizontal" arrangement is the one we need.

---

Setting up the Fan Controls

Now we take care of the GridLayout_Fan. Open the "Configure Layouter…" dialog and configure the GridLayout as shown in the picture.
For the width of the third column, we are using the exact width of the MultiStateButton's image in order to get a pixel exact rendering of the image.

We now configure the images of the MultiStateButton. You can find a property "StateImages" in the Control section of the MultiStateButton's properties, where multiple images can be defined.

It is possible to add images using the "+" button or to remove images using the "x" button next to the image to be deleted (highlighted in the image above).
Please click on the magnifying glass to change the images. For our GettingStarted, we will configure the images from the climate folder of our resources ("NewClimate-0Bmp" - "NewClimate-7Bmp"). We have to change the Maximum State property to 7 in order to be able to display all selected images.

The MultiStateButton should be centered vertically, so we configure its layout accordingly.

To change the image of "Button_Fan Max" and "Button_Fan Off" use the resources available. A button needs two different images to be able to reflect a mouse press or a touch on a touch screen. Therefore we will change the normal and pressed image as shown below:

---

Improvement of Interactivity using Behaviors

We want to add the reset of the MultiStateButton_Fan to the off button and also we want to add the max functionality to the max button. To be able to do this we will need to use an Event Handler. When you select the "Button_Fan Off" you can recognize two tabs: an active "General" tab and an EventHandler tab:

Select this "Event Handler" tab to be able to attach functionality to the button. Use the "+" button next to "Actions" to add an action to the already attached "Click Event Handler".

Use the drop down menu to choose "Send Value As Event". Select the "MultiStateButton_Fan" as TargetNode using the magnifying glass.

The Event Handler tab should now look like this:

Due to the more complex possibilities of event handlers we will now explain in more detail what the different properties are usually used for.
With the Event drop down you can select on which type of event a certain action will be performed. In our case a click event(mouse click or touch) will trigger the action. For a description of available events please have a look inside the documentation FeatStd::Event. The Condition property can be used for some events to only react if a certain condition is evaluates to "true". For our case the "Check Click" will count the number of clicks happened and compares it with the given ClickCount property. We have provided AnyClick which means we will react on single, double and even triple clicks. With the Sender property we can give the Action Behavior additional information on who has executed the action. In our example we do not evaluate this and it is left empty.

The Value is used to specify the type of the value and the value itself which will be sent to the target node. ChangeValue states if the change of the value will be relative or absolute.
Last but not least the Target Node has to be specified to know who will be the receiver of the event.

We will now add a similar action to the "Button_Fan Max" button to always change the value of the MultiState button to its maximum value of 7.

---

Setting up the Seat Heater controls

For the Seat Heater controls, we just need to replace the images with new ones, as below:

---

Setting up the Heating controls

Last but not the least, we will configure the SpinBox. The SpinBox allows the user to change the values by clicking the uptick and downtick buttons.

We will configure the SpinBox control as follows. We will also change the images of the SpinBox Control.

Set the width of the SpinBox to 150. Please note that this is an automatically calculated property which has to be unlocked pressing the blue "A" button.

You have finished step 2 of our tutorial. Please save your solution before trying the result using the Player application. Generate an asset file as described at the end of Step 1. Load the generated asset into the Player and select the climate scene. You can now play around with the controls. Slide the temperature slider, use the check box and radio buttons. Click onto the fan multi state button and on off and max. Even the Seat heater will react on your actions.

---