
## How To Use Babylon 3D GUI

The Babylon.js 3D GUI library is an extension you can use to generate 3D interactive user interface.

The latest version can be found [here](https://github.com/BabylonJS/Babylon.js/tree/master/dist/preview%20release/gui)

And the source code is available on the main [Babylon.js GUI3D repo](https://github.com/BabylonJS/Babylon.js/tree/master/gui/src/3D)

## Introduction

Babylon.GUI uses meshes to create an interactive user interface, which is fully integrated in your scene.

## GUI3DManager

To begin with 3D GUI, you need to instantiate a `GUI3DManager` which will be responsible for connecting all the controls together:

```javascript
var manager = new BABYLON.GUI.GUI3DManager(scene);
```

The manager only requires the scene to work on. Once instantiated, the manager will create a utility layer which is a specific child scene that will host all the meshes used to render the controls. This way, your main scene won't get populated by the utility meshes.

You can reach the utility layer with `manager.utilityLayer`.

Once you have a manager, you can start adding controls with `manager.addControl(control)`. All controls will be added to the `manager.rootContainer`.

Please also note that the following functions are available:

- `containsControl()`: Gets a boolean indicating if the given control is in the root child list.
- `removeControl()`: Removes a control from the root child list.

## Containers

A container is used to organize controls in the scene. The base class for all containers is the `Container3D` class. The `manager.rootContainer` is a `Container3D` object.

All containers provide the following functions to handle controls:

- `addControl()`: Adds a control to the children of this container
- `containsControl()`: Gets a boolean indicating if the given control is in the root child list
- `removeControl()`: Removes a control from the root child list

By default, all containers will update their layout everytime you add a new control to it. But you can optimize this behavior if you plan to add multiple controls in a row with `container.blockLayout = true`:

```javascript
panel.blockLayout = true;
for (var index = 0; index < 30; index++) {
  var button = new BABYLON.GUI.Button3D("click me");
  panel.addControl(button);
}
panel.blockLayout = false;
```

The `Container3D` class will do nothing regarding layout of its controls. You need to use one of its children to get a specialized layout mechanism.

All specialized containers must implement the following function to provide layout mechanism:

- `_arrangeChildren()`: This function will be called everytime a new control is added. This is where children class can decide how to organize controls

### StackPanel

The `StackPanel` container can be used to stack items either horizontally or vertically:

```javascript
var panel = new BABYLON.GUI.StackPanel3D();
panel.isVertical = true;
```

The panel will automatically arrange its content every time you add a new control.

You can specify the distance between elements with `panel.margin = 0.02`.

See it in action here: <Playground id="#HJZBRG#0" title="3D GUI StackPanel" description="Simple example showing how to add a 3D GUI StackPanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI1.jpg"/>

### VolumeBasedPanel

VolumeBasedPanel are containers used to dispatch items on the surface of a volume (like sphere or cylinder).

The panels will automatically arrange its content every time you add a new control.

The panels can either be row or column first depending on which property you use:

```javascript
panel.columns = 5; // The panel will automatically compute the number of rows based on number of child controls
```

or

```javascript
panel.rows = 5; // The panel will automatically compute the number of columns based on number of child controls
```

By default a VolumeBasedPanel is set up with panel.columns = 10;

You can specify the distance between elements with `panel.margin = 0.02`.

You can also control how each cell is oriented:

| Value | Type                                                | Description                                                     |
| ----- | --------------------------------------------------- | --------------------------------------------------------------- |
| 0     | BABYLON.Container3D.UNSET_ORIENTATION               | Control rotation will remain unchanged                          |
| 1     | BABYLON.Container3D.FACEORIGIN_ORIENTATION          | Control will rotate to make it look at sphere central axis      |
| 2     | BABYLON.Container3D.FACEORIGINREVERSED_ORIENTATION  | Control will rotate to make it look back at sphere central axis |
| 3     | BABYLON.Container3D.FACEFORWARD_ORIENTATION         | Control will rotate to look at z axis (0, 0, 1)                 |
| 4     | BABYLON.Container3D.FACEFORWARDREVERSED_ORIENTATION | Control will rotate to look at negative z axis (0, 0, -1)       |

#### SpherePanel

The `SpherePanel` container can be used to dispatch items on the surface of a sphere:

```javascript
var panel = new BABYLON.GUI.SpherePanel();
panel.radius = 5;
```

The radius property is used to define the radius of the hosting sphere.

See it in action here: <Playground id="#HB4C01#9" title="3D GUI SpherePanel" description="Simple example showing how to add a 3D GUI SpherePanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI2.jpg"/>

![SpherePanel](/img/how_to/gui/SpherePanel.jpg)

#### CylinderPanel

The `CylinderPanel` container can be used to dispatch item on the surface of a cylinder:

```javascript
var panel = new BABYLON.GUI.CylinderPanel();
panel.radius = 5;
```

The radius property is used to define the radius of the hosting cylinder.

See it in action here: <Playground id="#HB4C01#8" title="3D GUI CylinderPanel" description="Simple example showing how to add a 3D GUI CylinderPanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI3.jpg"/>

![CylinderPanel](/img/how_to/gui/CylinderPanel.jpg)

#### PlanePanel

The `PlanePanel` container can be used to dispatch item on the surface of a plane:

```javascript
var panel = new BABYLON.GUI.PlanePanel();
```

See it in action here: <Playground id="#HB4C01#7" title="3D GUI PlanePanel" description="Simple example showing how to add a 3D GUI PlanePanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI4.jpg"/>

![PlanePanel](/img/how_to/gui/PlanePanel.jpg)

#### ScatterPanel

The `ScatterPanel` container can be used to dispatch items using a randomized planar mapping:

```javascript
var panel = new BABYLON.GUI.ScatterPanel();
panel.iterations = 100;
```

The iterations property is used to define the number of iteration to use to scatter the controls (100 by default)

![ScatterPanel](/img/how_to/gui/ScatterPanel.jpg)

See it in action here: <Playground id="#HB4C01#6" title="3D GUI ScatterPanel" description="Simple example showing how to add a 3D GUI ScatterPanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI5.jpg"/>

## Controls

All controls inherit from the `Control3D` class which provides a set of basic features:

- `position`: Gets or sets the control position in world space
- `scaling`: Gets or sets the control scaling in world space
- `parent`: Gets or sets the parent container
- `isVisible`: Gets or sets a boolean indicating if the control is visible
- `node`: Gets the transform node used by this control
- `mesh`: Gets the mesh used to render this control

You can attach a control to a mesh or tranform node from your scene with:

```javascript
control.linkToTransformNode(anchor);
```

This way the control will always follow the linked node or mesh. Please note that in this case, the `position` and `scaling` properties are considered local to the new parent node or mesh.
When linking a control to a transform node, please make sure that the control was first added to a container or to the root manager.

Some observables are also available to help tracking control state:

- `onPointerEnterObservable`: An event triggered when pointer enters the control
- `onPointerOutObservable`: An event triggered when the pointer move out of the control
- `onPointerDownObservable`: An event triggered when the pointer taps the control
- `onPointerUpObservable`: An event triggered when pointer is up
- `onPointerClickObservable`: An event triggered when a control is clicked on (with a mouse)
- `onPointerMoveObservable`: An event triggered when the pointer move over the control

All controls can also be the target of [behaviors](/divingDeeper/behaviors) so they expose the associated properties and functions:

- `behaviors`: Gets the list of attached behaviors
- `addBehavior()`: Attach a behavior to the control
- `removeBehavior()`: Remove an attached behavior
- `getBehaviorByName()`: Gets an attached behavior by name

All controls can also define a callback when specific event is happening. These callbacks will be called to let the user defines an animation for the control. Here is the list of available callbakcs:

- `pointerEnterAnimation`: Callback used to start pointer enter animation
- `pointerOutAnimation`: Callback used to start pointer out animation
- `pointerDownAnimation`: Callback used to start pointer down animation
- `pointerUpAnimation`: Callback used to start pointer up animation

All these callbacks are empty by default and will be implemented by specialized controls.

### Button3D

`Button3D` is a class used to create 3D buttons.

A button is a control with default animations for enter/out/down and up events.
It is based on a 2D GUI content.

You can specify the content through the `content` property and set it to any regular [2D GUI content](/divingDeeper/gui):

```javascript
var button = new BABYLON.GUI.Button3D("reset");

var text = new BABYLON.GUI.TextBlock();
text.text = "reset";
text.color = "white";
text.fontSize = 24;
button.content = text;
```

By default the `Button3D` control uses a 512x512 AdvancedDynamicTexture to render its content.
You can use the following properties to change the texture resolution:

- `contentResolution`: Gets or sets the texture resolution used to render content (512 by default)
- `contentScaleRatio`: Gets or sets the texture scale ratio used to render content (2 by default)

See it in action here: <Playground id="#2YZFA0#0" title="3D GUI Button3D Control" description="Simple example showing how to add a 3D GUI Button3D to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI6.jpg"/>

### HolographicButton

The `HolographicButton` is a specialized button that mimics the Mixed Reality Toolkit holographic button.

An `HolographicButton` can be defined with two properties:

- `text`: Gets or sets text for the button
- `imageUrl`: Gets or sets the image url for the button

![Babylon.GUI](/img/how_to/gui/MRTK_HolographicButton.jpg)

See it in action here: <Playground id="#2YZFA0#2" title="3D GUI HolographicButton Control" description="Simple example showing how to add a 3D GUI HolographicButton to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI7.jpg"/>

Please note that you can overwrite the default content but you need to do it after the call to addControl:

```javascript
var button = new BABYLON.GUI.HolographicButton("reset");
panel.addControl(button);

// Must be done AFTER addControl in order to overwrite the default content
var text1 = new BABYLON.GUI.TextBlock();
text1.text = "Reset";
text1.color = "Red";
text1.fontSize = 48;
button.content = text1;
```

### MeshButton3D

This class is used to to create an interactable object which will use a mesh coming from the current scene to render.

```javascript
var pushButton = new BABYLON.GUI.MeshButton3D(mesh, "pushButton");
```

Once created, you can use the new MeshButton3D to add animations:

```javascript
pushButton.pointerEnterAnimation = () => {
  mesh.material.albedoColor = hoverColor;
};
pushButton.pointerOutAnimation = () => {
  mesh.material.albedoColor = new BABYLON.Color3(0.5, 0.19, 0);
};
```

See a complete GUI3D Demo here: <Playground id="#8Y780Y#20" title="Full GUI3D Demo" description="Full demo of the Babylon 3D GUI system." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI8.jpg"/>

### Custom controls

You can create your own custom control by inheriting from the `Control3D` class and implementing the following functions:

- `_createNode()`: Called on controls to create a transform node or a mesh to represent the control
- `_affectMaterial()`: Called on controls to prepare and affect a material if a mesh is used to represent the control


# The Scroll Viewer

When you want to keep your user interface small and the information to present large you can use the **ScrollViewer** to contain the information.

![ScrollViewer](/img/gui/scroll1.jpg).

It consists of vertical and horizontal scroll bars and a viewing area. The information you want to present is created as a control that you add to your scroll viewer and is shown in the viewing area. If all the information control fits inside the scroll viewer no scroll bars will be shown.

From Babylon.js version 4.1 onwards it is possible to use an image for the thumb control and in the bars

![ScrollViewer with Image Bars](/img/gui/scroll4.jpg).

## Creating the Scroll Viewer

The scroll viewer base is a rectangle container holding the scroll bars and the viewing area. You create it with or without a name.

```javascript
var myScrollViewer = new BABYLON.GUI.ScrollViewer();
var myScrollViewer = new BABYLON.GUI.ScrollViewer("name");
```

and add it to an advanced texture as usual.

```javascript
var myAdvancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI(
  "UI"
);
myAdvancedTexture.addControl(myScollViewer);
```

You can then create your control or container of controls to add to the scroll viewer using the **addControl** method.

```javascript
myScrollViewer.addControl(myControl);
```

- <Playground id="#13CF95#1" title="Scroll Viewer Example" description="Simple example showing how to add a Scroll Viewer to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer1.jpg"/>

The default setting for width and depth of the scroll viewer is 100% of the parent control.

The following table shows the additional properties of a scroll viewer.

| Property      | Type   | Default     | Comments                                                     |
| ------------- | ------ | ----------- | ------------------------------------------------------------ |
| barColor      | string | grey        | Foreground color of the scroll bar and color of the thumb    |
| barBackground | string | transparent | Background color of the scroll bar and bottom right square   |
| thumbLength   | number | 0.5         | Proportion of thumb compared to scroll bar length (0 to 0.9) |
| barSize       | number | 20          | Height of scroll bar                                         |

**NOTE** All the padding values for the scroll viewer are set as 0. Any padding should be set on the control added to the scroll viewer.

- <Playground id="#C3RDBS#3" title="Scroll Viewer of Fixed Size" description="Simple example showing how to add a Scroll Viewer of fixed size to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer2.jpg"/>
- <Playground id="#C3RDBS#2" title="Scroll Viewer of Relative Size" description="Simple example showing how to add a Scroll Viewer of relative size to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer3.jpg"/>

## Scrollbars

Both scrollbars can be reached with:

- horizontalBar
- verticalBar

You can then set the scrollbar position with `scrollViewer.horizontalBar.value`. This value must be between 0 and 1.

## Image Scrollbars

In order to have images in the scroll bar you need to pass a name (can be empty string) and a parameter of true when creating the scroll viewer.

```javascript
var myScrollViewer = new BABYLON.GUI.ScrollViewer("", true);
```

Additional properties are available

| Property                                                 | Type      | Default | Comments                                                                                                         |
| -------------------------------------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| thumbImage<br/>horizontalThumbImage<br/>verticalThumbImage | GUI Image | none    | Image used for the thumb; required for image scroll bars                                                         |
| barImage<br/>horizontalBarImage<br/>verticalBarImage       | GUI Image | none    | Image for the scroll bars                                                                                        |
| thumbHeight                                              | number    | 1       | Proportion of thumb compared to bar height (0 to 1)                                                              |
| barImageHeight                                           | number    | 1       | Proportion of barImage compared to bar height (0 to 1)                                                           |
| scrollBackground                                         | string    | grey    | background color of scroll bars excluding the bottom right square; useful behind a thin or transparent bar image |

You do not have to have a barImage.

The images for the vertical bar and thumb are by default rotated copies of those used for the horizontal bar and thumb. You may want to keep the image sizes small if memory is an issue in your project.

You can also choose to have different images for the vertical and horizontal bar / thumb. In that case, use `horizontalThumbImage` / `verticalThumbImage` instead of `thumbImage` and `horizontalBarImage` / `verticalBarImage` instead of `barImage`.

- <Playground id="#4ZC0G4#2" title="Image Scroll Bars" description="Simple example showing how to add Image Scroll Bars to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer4.jpg"/>
- <Playground id="#4ZC0G4#1" title="Image Scroll Bars in a Grid" description="Simple example showing how to add Image Scroll Bars in a grid to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer5.jpg"/>

## Adding an Adjustable TextBlock Window

When you add a TextBlock of a given size to a scroll viewer both horizontal and vertical scroll bars are shown as needed.

![Contained TextBlock](/img/gui/scroll3.jpg)

- <Playground id="#FX6KVK#3" title="Scroll Viewer with Fixed TextBlock" description="Simple example showing how to add a Scroll Viewer with Fixed TextBlock to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer6.jpg"/>

However quite often you need to present text fitting the width of the viewing window and scrolling for the height. This is achieved by setting the `textWrapping` and `reSizeToFit` as follows

```javascript
myTextBlock.textWrapping = BABYLON.GUI.TextWrapping.WordWrap;
myTextBlock.resizeToFit = true;
```

![Adjusting TextBlock](/img/gui/scroll2.jpg)

- <Playground id="#3EF49E#5" title="Scroll Viewer with Adjusting TextBlock" description="Simple example showing how to add a Scroll Viewer with Adjusting TextBlock to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer7.jpg"/>

## Live-Updating and Child Containers

The ScrollViewer accepts only ONE child control. If that single child is a textBlock, then you can modify its _.text_ property (including \\n linebreaks), to add/remove text content to/from that single textBlock.

The ScrollViewer also accepts a single CONTAINER (such as a stackpanel) for its single child. In that container, you may add/remove any type of control(s). For certain types of containers, you might choose to add `container.ignoreLayoutWarnings = true;`, and you might need to set a non-percentage _height_ value to certain children within the container(s).

## Rendering optimization

If you have a lot of controls in your scroll viewer window, you may notice a slow down in the rendering time.

To help improving your fps, you can set `myScrollViewer.freezeControls = true`. This will "freeze" the controls in their current position (in the window) and will make their rendering faster when the window is scrolled. When controls are frozen, a change in their position/size may not work, so if you must do it, first set `freezeControls` to `false`, do your changes then revert `freezeControls` back to `true`.

You can further improve the rendering time by using the `setBucketSizes` method:

```javascript
myScrollViewer.setBucketSizes(100, 40);
```

When `freezeControls` is true, setting a non-zero bucket size will improve performances by updating only controls that are visible. The bucket sizes is used to subdivide (internally) the window area to smaller areas into which controls are dispatched. So, the size should be roughly equals to the average size of all the controls inside the window. To disable the usage of buckets, sets either width or height (or both) to 0.

Please note that using this option will raise the memory usage (the higher the bucket sizes, the less memory used), that's why it is not enabled by default.

You can also use the `ScrollViewer.forceHorizontalBar` and `ScrollViewer.forceVerticalBar` properties.

When set to true, they force the display of the corresponding bars. When you know your scroll viewer will end up with visible bars, you can set those properties to true to save some initialization time, as if it is the scroll viewer control that makes a bar visible in the course of the initialization, it will trigger a children layout rebuild, adding more time to the initialization process.

<Playground id="#KPLW9F" title="Rendering Optimization" description="Simple example showing how to optimize rendering in your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer8.jpg"/>


## The Selection Panel Helper

A `SelectionPanel` contains groups of checkboxes, radio buttons and sliders. Though not as versatile as as building your own interface with your own custom arrangement of controls it can be a quick way to construct a method of changing scene parameters for objects within your scene.

![selection panel](/img/GUI/selectPanel1.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 1

## Referencing a Selection Panel

As you can see in **Fig 1** a selection panel rectangle contains a vertical organisation of groups numbered from the top starting at 0. Each groups contains a header and a variable number of selectors. Each selector consists of a (or button) and a label. Within any one group all the selectors must be of the same type. You can refer to a selector by its group number and then the position of the selector within the group. So the checkbox labelled _High_ has reference 0, 1, ie. group 0, selector 1.

**NOTE** Adding or removing groups or selectors with change the reference number. The reference number always refers to the current positioning of the group and of the selector.

## Creating a Selection Panel

As usual with GUI containers you will need to create an advanced dynamic texture to add the selection panel to. You can set the dimensions and position of the selection panel. The format to construct a blank selection panel is

```javascript
new BABYLON.GUI.SelectionPanel(name);
```

After construction you can add groups of selectors, each newly added group is placed below any already added groups. For example

```javascript
var advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI(
  "UI"
);

var selectBox = new BABYLON.GUI.SelectionPanel("selectBox");
selectBox.width = 0.25;
selectBox.height = 0.52;
selectBox.horizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;
selectBox.verticalAlignment = BABYLON.GUI.Control.VERTICAL_ALIGNMENT_BOTTOM;

advancedTexture.addControl(selectBox);

selectBox.addGroup(rotateGroup);
selectBox.addGroup(transformGroup);
selectBox.addGroup(colorGroup);
```

- <Playground id="#9M6M2I" title="Selection Panel with Added Groups" description="Simple example showing how to add a selection panel with added groups to your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector1.jpg"/>

In addition if you have already constructed selector groups then you can then pass them in an array when you create the selection panel. The format for this is

```javascript
new BABYLON.GUI.SelectionPanel(name, [selector groups])
```

Example

```javascript
var advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI(
  "UI"
);

var selectBox = new BABYLON.GUI.SelectionPanel("selectBox", [
  transformGroup,
  colorGroup,
  rotateGroup
]);
selectBox.width = 0.25;
selectBox.height = 0.52;
selectBox.horizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;
selectBox.verticalAlignment = BABYLON.GUI.Control.VERTICAL_ALIGNMENT_BOTTOM;

advancedTexture.addControl(selectBox);
```

- <Playground id="#BXMTCD" title="Selection Panel and Groups on Creation" description="Simple example showing how to add a selection panel with added groups on creation." image="/img/playgroundsAndNMEs/divingDeeperSelector1.jpg"/>
- <Playground id="#BXMTCD#1" title="Selection Panel with Both Approaches" description="Simple example showing how to add a selection panel with both approaches." image="/img/playgroundsAndNMEs/divingDeeperSelector1.jpg"/>

## Creating Groups

There are three types of groups, a checkbox group, a radio group and a slider group, which are created using the structure

```javascript
new BABYLON.GUI.<Type>Group(header)
```

For example

```javascript
var transformGroup = new BABYLON.GUI.CheckboxGroup("Transformation");
var colorGroup = new BABYLON.GUI.RadioGroup("Color");
var rotateGroup = new BABYLON.GUI.SliderGroup("Rotation");
```

## Creating Selectors

Naturally there are three types of selectors and each can only be added to the appropriate group. External functions for each selector refer any changes in the value to properties of scene objects.

Checkbox and radio selectors are simply added to their group using two parameters, a label name and the external function reference. An optional third parameter can set the initial checked state of the selector to true (default value is false).

A slider selector is added to its group with a number of parameters, the first two being as before a label name and a reference to the external function. Due to the nature of a slider the following optional parameters can be set

| Parameter     | Description                                              | Default |
| ------------- | -------------------------------------------------------- | ------- |
| unit          | a string describing the units used, eg degrees or metres | "Unit"  |
| min           | the minimum value for the slider                         | 0       |
| max           | the maximum value for the slider                         | 100     |
| value         | the start value for the Slider between min and max       | 0       |
| onValueChange | the function used to format the value displayed          | void    |

New selectors are added below those already added.

Example usage

```javascript
transformGroup.addCheckbox("Small", toSize);
transformGroup.addCheckbox("High", toPlace);

colorGroup.addRadio("Blue", setColor, true);
colorGroup.addRadio("Red", setColor);

rotateGroup.addSlider(
  "Angle Y",
  orientateY,
  "degs",
  0,
  2 * Math.PI,
  0,
  displayValue
);
rotateGroup.addSlider(
  "Angle X",
  orientateX,
  "degs",
  0,
  2 * Math.PI,
  Math.PI,
  displayValue
);
```

## Selector Called Functions

### Checkbox Selector

One function for each selector. Each requires a Boolean parameter with actions depending whether the control is checked or not

Examples

```javascript
var toSize = function(isChecked) {
  if (isChecked) {
    box.scaling = new BABYLON.Vector3(0.5, 0.5, 0.5);
  } else {
    box.scaling = new BABYLON.Vector3(1, 1, 1);
  }
};

var toPlace = function(isChecked) {
  if (isChecked) {
    box.position.y = 1.5;
  } else {
    box.position.y = 0.5;
  }
};
```

### Radio Selector

Within a radio group the same function is used for all selectors. The function requires a number parameter which will match the selector position with actions for each selector

Examples

```javascript
var setColor = function(but) {
  switch (but) {
    case 0:
      box.material = blueMat;
      break;
    case 1:
      box.material = redMat;
      break;
  }
};
```

### Slider Selector

Each slider selector requires two functions, one to change scene object properties and one to set the display format within the slider label.

Examples

```javascript
// Change mesh
var orientateY = function(angle) {
  box.rotation.y = angle;
};

var orientateX = function(angle) {
  box.rotation.x = angle;
};

//Format value
var displayValue = function(value) {
  return BABYLON.Tools.ToDegrees(value) | 0;
};
```

## Customise the Selection Panel

### Colors and Font

For consistency of appearance you can only change the overall font and color of all headers, all labels and all selector buttons.

- <Playground id="#BXMTCD#4" title="Selection Panel with Font Change" description="Simple example showing how to add a selection panel with a font change." image="/img/playgroundsAndNMEs/divingDeeperSelector2.jpg"/>

Without any direct setting, the color of labels follows that of the selection panel.

It is possible to set the color of all headers, labels, separator bars and selector buttons and the background color of all selector buttons.

```javascript
selectBox.color = "blue";
selectBox.background = "#FFFF99";
selectBox.barColor = "#4F7DF2";
selectBox.headerColor = "blue";
selectBox.buttonColor = "orange";
selectBox.buttonBackground = "#684502";
selectBox.labelColor = "brown";
```

- <Playground id="#BXMTCD#2" title="Selection Panel with Color Changes no labels" description="Simple example showing how to add a selection panel with color changes apart from labels." image="/img/playgroundsAndNMEs/divingDeeperSelector3.jpg"/>
- <Playground id="#BXMTCD#3" title="Selection Panel with Color Changes" description="Simple example showing how to add a selection panel with a color change." image="/img/playgroundsAndNMEs/divingDeeperSelector4.jpg"/>

Individual headers and labels can have their text changed.

```javascript
selectBox.setHeaderName("Move", 0);
selectBox.relabel("Theta", 2, 0);
```

- <Playground id="#BXMTCD#5" title="Selection Panel Change Group Header" description="Simple example showing how to add a selection panel and change the group header." image="/img/playgroundsAndNMEs/divingDeeperSelector5.jpg"/>
- <Playground id="#BXMTCD#6" title="Selection Panel Change Selector Label" description="Simple example showing how to add a selection panel and change the selector label." image="/img/playgroundsAndNMEs/divingDeeperSelector5.jpg"/>

### Groups and Selectors

As stated earlier you can add groups at the bottom of the selection panel at any time. You can also remove a group by reference to its position in the list, eg

```javascript
selectBox.removeGroup(2);
```

**Note** Groups below the removed group will have new positions and so need to be referenced by their new position.

In the same way a selector of the correct type can be added to the bottom of a group at any time using the `add<Type>` method.

```javascript
transformGroup.addCheckbox("Across", toLeft);
```

- <Playground id="#BXMTCD#7" title="Selector Group Add Selector" description="Simple example showing how to add a selector group and add a selector to your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector6.jpg"/>

A selector can be removed from a group at any time using its position in the group, eg

```javascript
transformGroup.removeSelector(1);
colorGroup.removeSelector(0);
rotationGroup.removeSelector(0);
```

- <Playground id="#BXMTCD#8" title="Selector Group Add Selector" description="Simple example showing how to add a selector group and remove a selector from your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector6.jpg"/>

For a selector within a group that is contained within a selection panel you can add a selector by use of the group position and correct parameters, eg

```javascript
selectBox.addToGroupSlider(
  2,
  "Angle X",
  orientateX,
  "degs",
  0,
  2 * Math.PI,
  Math.PI,
  displayValue
);
```

- <Playground id="#BXMTCD#9" title="Selector Panel Add Selector" description="Simple example showing how to add a selector panel and add a selector to your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector6.jpg"/>

and remove a selector by using its reference position, ie. group and selector position in the group. For example

```javascript
selectBox.removeFromGroupSelector(0, 0);
```

- <Playground id="#BXMTCD#10" title="Selector Group Remove Selector" description="Simple example showing how to add a selector group and remove a selector from your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector6.jpg"/>


When you want to create GUI layouts in an easy and structured way you may want to take a look at the Xml Loader.

## Creating the Xml Loader

The xml Loader is able to load Babylon GUI layouts directly from xml. You create it with

```javascript
var advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");
var xmlLoader = new BABYLON.GUI.XmlLoader();
```

The XmlLoader might be used as part of a javascript class or function. In order for the class to correctly map observables and dynamic attributes with the class methods and attributes, it is necessary to provide the class object in the constructor. This would be how the XmlLoader would be initialized inside a class.

```javascript
var advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");
var xmlLoader = new BABYLON.GUI.XmlLoader(this);
```

You can then proceed to load a layout using the **loadLayout** method.

```javascript
xmlLoader.loadLayout("layouts/testgui.xml", advancedTexture);
```

This is what is needed to initialize and load a layout. There may be cases when you may need to load a layout without attaching it to the advancedTexture. In this case, it suffices to set the second paramenter null like the following.

```javascript
xmlLoader.loadLayout("layouts/testgui.xml", null);
```

The third parameter in the loadLayout function, is a callback which is called once the layout has been parsed. Inside the callback, it is possible to retrieve elements and add events to them. This would be an example of how it would be used.

```javascript
xmlLoader.loadLayout("layouts/testgui.xml", advancedTexture, function() {
    xmlLoader.getNodeById("helloButton").onPointerClickObservable.add(clickEvent);
});
```

After the layout has been loaded there is a couple of methods available to you.

```javascript
xmlLoader.getNodeById("helloButton"); // Gets a node by ID. Similar to how DOM elements are retrieved.
xmlLoader.getNodes(); // Gets all parsed nodes.
xmlLoader.isLoaded(); // Returns true or false depending whether the layout has finished loading.
```

If you need to detach a container from the scene

```javascript
var node = xmlLoader.getNodeById("firstContainer"); 
advancedTexture.removeControl(node);
```
Then attach it again
```javascript
var node = xmlLoader.getNodeById("firstContainer"); 
advancedTexture.addControl(node);
```
## XML Layouts

The structure for an XML layout is very straightforward. This is what a simple XML layout would look like

```xml
<?xml version="1.0"?>
<root>
    <Rectangle id="firstContainer" verticalAlignment="Control.HORIZONTAL_ALIGNMENT_TOP" background="yellow" width=".8" height=".4" color="Orange">
        <Button id="imageButton" name="imageButton" width="0.2" background="red" height="0.3">
                <Image id="image" source="assets/icon.png" width="1" height="1" name="image" stretch="Image.STRETCH_FILL" horizontalAlignment="Control.HORIZONTAL_ALIGNMENT_LEFT" />
        </Button>
    </Rectangle>
</root>
```

The Controls names in the layouts follow rigorously the names in the BABYLON.GUI library. The same stands for the attributes as well. The only usecase when this differs, is in the Grid element. This is what a Grid element looks like in the layout.

```xml
<Grid id="grid" name="grid" top="50px" background="black" height="200px" width="200px">
        <Row height="0.5" >
            <Column width="0.2">
            </Column>
            <Column width="0.5">
                <Rectangle id="1rect" thickness="0" name="1rect" background="green"></Rectangle>
            </Column>
        </Row>
        <Row height="0.5">
            <Column>
            </Column>
            <Column>
                <Rectangle id="2rect" thickness="0" name="2rect" background="red" ></Rectangle>
            </Column>
        </Row>
</Grid>
```

In the Grid's case, the rows and the columns are not controls in the babylon GUI. It is important to add the maximum number of columns in the first row as all the subsequent rows will have the same number of columns. This is because the xml loader creates the column definitions of the Grid from the first row. However, after the first row, it is possible to add less columns to the subsequent rows. The width and height attributes for Rows and the Columns of the first row are mandatory, for the columns of the subsequent rows the value will not be taken into consideration by the loader. The isPixel attribute is mandatory if the width and height is in Pixels.

## Dynamic Attributes

It is possible to add dynamic attributes to your XML layouts. These attributes can either be class attributes or global variables. The following is how to set a value in your xml layout referencing a class attributes or a global variable.

```xml
<?xml version="1.0"?>
<root>
    <Rectangle name="firstContainer" id="firstContainer" verticalAlignment="Control.HORIZONTAL_ALIGNMENT_TOP" background="blue" id="popupContainer" width=".8" height=".4" color="Orange" >
        <InputText id="inputText1" width="{{textWidth}}" maxWidth="0.3"  height="40px" color="white"/>
        <Button id="helloButton" width="0.2" verticalAlignment="Control.VERTICAL_ALIGNMENT_BOTTOM" height="0.2" name="helloButton" background="green" onPointerUpObservable="storeUsernameEvent" >
            <TextBlock  text="Store Input" color = "white" />
        </Button>
    </Rectangle>
</root>
```

By wrapping the attributes value with double curly brackets `{{}}`, it is given the value of the class attribute or global variable with that name.

## Linking Control to Mesh

It is possible to link a control to a mesh directly from Xml. This can be very easily done by setting the attribute `linkWithMesh="meshName"` to the Control you want to add. Even though the curly brackets are not needed, this is also a dynamic attribute. If the xml loader has been initiated with a class / function context it will use that context to retrieve the mesh, otherwise it will look for it globally.

## Dynamic Array and Object source

It is also possible to connect a structure like an Array or Object directly to XML. This would be handy in a case when we may need to fill a StackPanel from an array of values or object of key value pairs. However, this can be used whenever we need to repeat a specific xml block by filling in values from An Array or an Object. The only not implemented usecase would be the Grid.

Let's suppose we have the following object in your javascript :

```javascript
var objTexts = {
        first: {
            name: "john",
            surname: "smith"
        },
        second: {
            name: "ben",
            surname: "Stiller"
        }
};
```

Let's also suppose the following list retains the users of your application and you may want to show them listed in the GUI. This would be possible JS side but this would mean copying the control over and over again. XmlLoader makes it much more easier and cleaner directly from XML. This would be how you iterate the aforementioned structure :

```xml
<StackPanel background="#ffffff" width="300px" top="100px" left="200px" id="panel" dataSource="text in {objTexts}">
       <Container  width="1" height="40px" >
           <TextBlock id="myImage" height="1" text="{{text.name}}" color="red" resizeToFit="true" fontSize="24"/>
           <TextBlock left="50px" height="1" text="{{text.surname}}" color="black" resizeToFit="true" fontSize="24"/>
       </Container>
</StackPanel>
```
Or
```javascript
xmlLoader.getNodeById("myName").text = "john";
xmlLoader.getNodeById("mySurname").text = "smith";
```

```xml
<StackPanel background="#ffffff" width="300px" top="100px" left="200px" id="panel" dataSource="text in {objTexts}">
       <Container  width="1" height="40px" >
           <TextBlock id="myName"  height="1" text="{{text.name}}" color="red" resizeToFit="true" fontSize="24"/>
           <TextBlock id="mySurname" left="50px" height="1" text="{{text.surname}}" color="black" resizeToFit="true" fontSize="24"/>
       </Container>
</StackPanel>
```

The source is associated to the StackPanel by using the dataSource attribute. The dataSource attribute should always have 3 values in it, the variable name, the keyword `in` and structure name. For an object structure the name must be wrapped in curly brackets `{}` like the example above. For an array structure the name can be wrapped up in normal brackets but it is not mandatory. When the dataSource is an array it can be written as `dataSource="text in [objTexts]` or simply `dataSource="text in objTexts"`

The variable part of the dataSource attribute is how you access the source values. Notice in the above example the section `text="{{text.surname}}"` is how you set a value from the source to your XML.


# How To Use Promises

## Introduction

Starting with v3.2, we introduced (without breaking backward compatibility of course) a new pattern: the promises.
To learn more about promises, please read this great [MDN web documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)

In a nutshell, the basic idea is to rely on promises instead of having to deal with pyramids of callbacks intricated in a non easy to maintain way.
Regarding portability, Babylon.js provides a custom polyfill for browsers where promises are not supported so you can blindly use them.

## Examples

### Basic usage

```javascript
BABYLON.SceneLoader.LoadAssetContainerAsync("https://playground.babylonjs.com/scenes/", "skull.babylon", scene).then(function (container) {
    container.addAllToScene();
});
```

<Playground id="#JA1ND3#63" title="Simple Promise Example" description="Simple example loading an asset into a scene after the file has been loaded." image="/img/playgroundsAndNMEs/divingDeeperPromises1.jpg"/>

### Chaining multiple promises together

```javascript
var scene = new BABYLON.Scene(engine);
var xrPromise = scene.createDefaultXRExperienceAsync();
xrPromise
    .then((xrExperience) => {
        return BABYLON.SceneLoader.AppendAsync("https://playground.babylonjs.com/scenes/", "skull.babylon", scene);
    })
    .then(function () {
        // xr resolved, skull added to the scene
    });
```

### Using async/await with promises

Note: This is not supported in all browsers

```javascript
var main = async function () {
    var scene = new BABYLON.Scene(engine);
    var helper = scene.createDefaultVRExperience();
    var supported = await helper.webVRCamera.useStandingMatrixAsync();
    console.log(supported);
    await BABYLON.SceneLoader.AppendAsync("https://playground.babylonjs.com/scenes/", "skull.babylon", scene);
};
```

### Loading two glTF assets in parallel

```javascript
var scene = new BABYLON.Scene(engine);

var baseUrl = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/";

Promise.all([
    BABYLON.SceneLoader.ImportMeshAsync(null, baseUrl + "BoomBox/glTF/", "BoomBox.gltf", scene).then(function (result) {
        result.meshes[0].position.x = 0.01;
    }),
    BABYLON.SceneLoader.ImportMeshAsync(null, baseUrl + "Avocado/glTF/", "Avocado.gltf", scene).then(function (result) {
        result.meshes[0].position.x = -0.01;
        result.meshes[0].position.y = -0.01;
        result.meshes[0].scaling.scaleInPlace(0.25);
    }),
]).then(() => {
    scene.createDefaultCameraOrLight(true, true, true);
    scene.activeCamera.alpha += Math.PI;
});
```

<Playground id="#U2KKMK#1" title="Load 2 Asset At Once" description="Simple example of loading 2 assets at once inside of a promise." image="/img/playgroundsAndNMEs/divingDeeperPromises2.jpg"/>


GUI

Coming next

The Babylon GUI

Learn all about the Babylon.js 2D GUI system.

Scroll Viewer

Learn about Scroll Viewer in Babylon.js.

XML Loader

Learn about the Babylon.js XML Loader.

Selector

Learn about the selector in Babylon.js.

Babylon 3D GUI

Learn all about the Babylon.js 3D GUI System.