
## The Selection Panel Helper

A `SelectionPanel` contains groups of checkboxes, radio buttons and sliders. Though not as versatile 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 organization of groups numbered from the top starting at 0. Each group 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
const advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");

const 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
const advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");

const 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
const transformGroup = new BABYLON.GUI.CheckboxGroup("Transformation");
const colorGroup = new BABYLON.GUI.RadioGroup("Color");
const 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
const 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);
  }
};

const 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
const 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
const orientateY = function (angle) {
  box.rotation.y = angle;
};

const orientateX = function (angle) {
  box.rotation.x = angle;
};

//Format value
const displayValue = function (value) {
  return BABYLON.Tools.ToDegrees(value) | 0;
};
```

## Customize 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"/>



## 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 on our CDN at https://cdn.babylonjs.com/gui/babylon.gui.js.

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

And the source code is available on the main Babylon.js repo: https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/gui.

## 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
const 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.

The manager also supports a scaling option, `manager.useRealisticScaling`, that scales all added controls to a size more comfortable for XR interactions. Alternatively, a custom scaling can be applied to all controls by setting the value of `manager.controlScaling`. Scaling effects done in these ways can be overridden by updating the control's scale normally. Setting either of these values will apply the change to all existing and future controls the manager owns.

## 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 every time 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 (let index = 0; index < 30; index++) {
  const 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 every time 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
const 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
const 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
const 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
const 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
const 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 transform 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](/features/featuresDeepDive/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 callbacks:

- `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](/features/featuresDeepDive/gui):

```javascript
const button = new BABYLON.GUI.Button3D("reset");

const 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"/>

### MeshButton3D

This class is used to create an interactive object which will use a mesh coming from the current scene to render.

```javascript
const 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 it in action here: <Playground id="#8Y780Y#20" title="MeshButton3D Demo" description="Demo of the MeshButton3D control." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI8.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
const button = new BABYLON.GUI.HolographicButton("reset");
panel.addControl(button);

// Must be done AFTER addControl in order to overwrite the default content
const text1 = new BABYLON.GUI.TextBlock();
text1.text = "Reset";
text1.color = "Red";
text1.fontSize = 48;
button.content = text1;
```

### TouchHolographicButton

The `TouchHolographicButton` is a newer version `HolographicButton` that is more suited for Hololens 2 volume interactions.  
It has the same use as `HolographicButton`:

```javascript
const button = new BABYLON.GUI.TouchHolographicButton("reset");
panel.addControl(button);

// Must be done AFTER addControl in order to overwrite the default content
const text1 = new BABYLON.GUI.TextBlock();
text1.text = "Reset";
text1.color = "Red";
text1.fontSize = 48;
button.content = text1;
```

The main functional difference between the `TouchHolographicButton` and `HolographicButton` is that the `TouchHolographicButton` supports near interactions (such as touching the button directly with hand tracking).

### HolographicSlate

The `HolographicSlate` is used to display content. It can be dragged around, rotated and scaled. With 1 pointer you have to use the handles to rotate and scale the slate, with 2 pointers you can pinch and twist the title bar to rotate and scale.

The `HolographicSlate` hosts an `AdvancedDynamicTexture` to display content, simply set the `content` property to a `Control` or collection of `Control`s to adjust what is displayed. It also has an adjustable title bar at the top that can display a title by setting the `title` property.

The dimensions can be manually set at any time, but are also updated when the user adjusts the slate using the handles around the outside of the slate. The dimensions will never go below the minimum dimensions in either direction, but the minimum dimensions can be set separately. If using the slate handles to resize, the aspect ratio will be maintained even when trying to resize smaller than the minimum.

```javascript
// Create the 3D UI manager
const manager = new BABYLON.GUI.GUI3DManager(scene);

// Let's add a slate
const slate = new BABYLON.GUI.HolographicSlate("down");
slate.title = "Checkers";
slate.minDimensions = new BABYLON.Vector(5, 5);
slate.dimensions = new BABYLON.Vector2(10, 10);
slate.titleBarHeight = 1.5;
manager.addControl(slate);
// Must be done AFTER addControl in order to overwrite the default content
slate.content = new BABYLON.GUI.Image("checkers", "./textures/Checker_Albedo.png");
```

Content inside the slate can also be scrolled in X or Y directions. Use the `contentResolution` property to manipulate the resolution of the texture.

The slate natively provides 2 `TouchHolographicButton` on the top right, the leftmost enables the [FollowBehavior](/features/featuresDeepDive/behaviors/meshBehaviors#followbehavior) for the slate, and the rightmost destroys the slate.

<Playground id="#SYD2M2#10" title="HolographicSlate" description="Simple Holographic Slate example"/>

### Near Menu

The `NearMenu` is a small control that displays buttons close to the user. By default, it follows the user with [FollowBehavior](/features/featuresDeepDive/behaviors/meshBehaviors#followbehavior). It can be pinned in the world either by using the pin button, or whenever the user drags the backplate.

Below, an example of a horizontal 3-button near menu.

```javascript
// Create the 3D UI manager
const manager = new BABYLON.GUI.GUI3DManager(scene);

// Let's add a slate
const near = new BABYLON.GUI.NearMenu("near");
manager.addControl(near);

const button0 = new BABYLON.GUI.TouchHolographicButton("button0");
button0.imageUrl = "./textures/IconFollowMe.png";
button0.text = "Button 0";
near.addButton(button0);

const button1 = new BABYLON.GUI.TouchHolographicButton("button1");
button1.imageUrl = "./textures/IconClose.png";
button1.text = "Button 1";
near.addButton(button1);

const button2 = new BABYLON.GUI.TouchHolographicButton("button2");
button2.imageUrl = "./textures/IconFollowMe.png";
button2.text = "Button 2";
near.addButton(button2);
```

As `NearMenu` is a child class of `VolumeBasedPanel`, the direction of the layout can be changed by tweaking the parameters `rows` and `columns`.

For example, to make a near menu with `n` buttons vertical, use :

```javascript
near.rows = n;
```

### Hand Menu

The `HandMenu` is a `NearMenu` that uses the [HandConstraintBehavior](/features/featuresDeepDive/behaviors/meshBehaviors#handconstraintbehavior). It is useful for XR experiences to always have a 3D menu in hand range.

By default, the `HandMenu` positions itself on the outer side of the users left hand, and only activates when the user both has their palm facing them and is looking at (facing) their hand. These defaults can be changed by modifying the properties on the `HandConstraintBehavior` attached to the `HandMenu`.

### 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



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
const advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");
const 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
const advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");
const 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 parameter 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
const node = xmlLoader.getNodeById("firstContainer");
advancedTexture.removeControl(node);
```

Then attach it again

```javascript
const 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
const 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.
