Babylon.GUI官方文档翻译

　　Babylon.GUI是一个基于Babylon.js的WebGL库，可以用来在WebGL3D场景中生成交互性UI与动态纹理。相比于html ui，Babylon.GUI的功能较为简化，但使用起来也更加简单，并且具备一些适用于3D编程的独有特性。如果你正寻找一款适用于h53d场景的ui库，这也许正是你所需要的。

　　为了减少误解，翻译正文使用中英文对照方式呈现，官方教程原地址：http://doc.babylonjs.com/overviews/gui

　　

overviews

概述

Babylon.GUI: How to create 2D and 3D UI

如何建立2D和3D的UI

Table of contents

内容列表

1. Introduction   简介
2. AdvancedDynamicTexture        高级动态纹理
3. General properties        一般属性
1. Events              事件
1. Bubbling Phase         冒泡阶段
2. Parameters          参数
2. Alignments              分组对齐
3. Position and size            位置和尺寸
4. Tracking positions          追踪位置
5. Adaptive scaling            适应性缩放
6. Rotation and Scaling            姿态和缩放
4. Controls         被控对象
1. TextBlock        文本框
1. Resize to Fit              重新调整大小以适应内容
2. InputText         文本输入框
3. Button              按钮
1. Visual animations             可视的动画
2. Custom button          自定义的按钮
4. Checkbox         复选框
5. RadioButton           单选框
6. Slider                滑块
7. Line           线
8. Image        图片
9. VirtualKeyboard            虚拟键盘
1. Keys            按键
2. Layouts       布局
3. Events         事件
5. Containers             容器
1. Rectangle         矩形
2. Ellipse              椭圆
3. StackPanel              堆栈面板
4. ColorPicker      拾色器
6. Helpers           帮助
7. Focus management             焦点管理 

Babylon.GUI

The Babylon.js GUI library is an extension you can use to generate interactive user interface. It is build on top of the DynamicTexture.

Babylonjs的GUI库是一个可以用来建立交互性用户接口的扩展。它建立在动态材质的基础上

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 repo: https://github.com/BabylonJS/Babylon.js/tree/master/gui.

同时代码可以在Babylonjs的主报告找到。

You can find a complete demo here: http://www.babylonjs.com/demos/gui/

你可以在这里找到一个完整的示例

 

Introduction

简介

Babylon.GUI uses a DynamicTexture to generate a fully functionnal user interface.

Babylon.GUI使用一个动态纹理来建立一个具有完全功能的用户接口。

The user interface can be full screen or projected onto any 3d object.

这个用户接口可以是全屏的也可以在一个3D对象上编制。

AdvancedDynamicTexture

高级动态纹理

To begin with Babylon.GUI, you first need an AdvancedDynamicTexture object.

要开始使用Babylon.GUI,你首先需要一个高级动态纹理对象。

Babylon.GUI has two modes:

Babylon.GUI具有两种模式

• Fullscreen mode: In this mode, Babylon.GUI will cover the entire screen and will rescale to always adapt to your rendering resolution. It will also intercept clicks (including touches). To create an AdvancedDynamicTexture in fullscreen mode, just run this code:
• 全屏模式：在这种模式下，Babylon.GUI将覆盖整个屏幕，并且将一直根据渲染的分辨率自动缩放。它将捕获点击（包括触摸）。要建立一个全屏模式的高级动态材质，只需运行以下代码：

var advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("myUI");

Here is an example of a simple fullscreen mode GUI: https://www.babylonjs-playground.com/#XCPP9Y#1 -

这里是一个全屏模式GUI的例子

• Texture mode: In this mode, BABYLON.GUI will be used as a texture for a given mesh. You will have to define the resolution of your texture. To create an AdvancedDynamicTexture in texture mode, just run this code:
• 纹理模式：在这种模式下，BABYLON.GUI将作为某一个网格的纹理被使用。你必须定义你的纹理的分辨率。要建立一个纹理模式的高级动态纹理，只需运行以下代码：

var advancedTexture2 = BABYLON.GUI.AdvancedDynamicTexture.CreateForMesh(myPlane, 1024, 1024);

Here is an example of a simple texture mode GUI: https://www.babylonjs-playground.com/#ZI9AK7#1 -

这里是一个纹理模式GUI的例子

Please note that handling pointer move events could be costly on complex meshes, so you can turn off supporting pointer move events with a fourth parameter:

请注意在复杂的网格上处理指针移动事件对性能的消耗很大，所以你可以通过第四个参数来关闭对指针移动事件的支持：

var advancedTexture2 = BABYLON.GUI.AdvancedDynamicTexture.CreateForMesh(myPlane, 1024, 1024, false);

Once you have an AdvancedDynamicTexture object, you can start adding controls.

在你拥有一个高级动态纹理对象之后，你可以开始添加被管对象

General properties

通用的属性

Events

事件

All controls have the following observables:

所有的被管对象都具有以下的可监听项：

Observables 可监听项	Comments 注释
onPointerMoveObservable	Raised when the cursor moves over the control. Only available on fullscreen mode 当光标从被管对象上经过时触发。只在全屏模式下有用
onPointerEnterObservable	Raised when the cursor enters the control. Only available on fullscreen mode 当光标进入被管对象时触发。只在全屏模式下有用。
onPointerOutObservable	Raised when the cursor leaves the control. Only available on fullscreen mode 当光标离开被管对象时触发。只在全屏模式下有用
onPointerDownObservable	Raised when pointer is down on the control. 在指针在被管对象上按下时触发。
onPointerUpObservable	Raised when pointer is up on the control. 当指针在被管对象上抬起时触发。
onDirtyObservable	Raised when the control is marked as dirty. 当被管对象被标记为垃圾时触发
onAfterDrawObservable	Raised after control is drawn. 当被管对象绘制完成时触发

You can also define that a control is invisble to events (so you can click through it for instance). To do so, just call control.isHitTestVisible.

你也可以将一个被管对象定义为对事件不可见（比如你可以让点击穿过它）。要做到这一点，只需使用control.isHitTestVisible属性

Please note that onPointerMoveObservable, onPointerDownObservable and onPointerUpObservable will receive a Vector2WithInfo parameter containing the pointer coordinates (x, y) and the index of the button pressed (buttonIndex). If you want to get the pointer coordinates in local control space, you have to call control.getLocalCoordinates(coordinates).

请注意onPointerMoveObservable、onPointerDownObservable和onPointerUpObservable将获取一个带有信息的二元向量参数，这个参数包含光标的坐标（x，y）以及被按下的按钮的索引（buttonIndex）。如果你想要在本地控制空间（指这个被控对象的局部坐标系，以左上角为零点）获得光标坐标，你必须使用control.getLocalCoordinates(coordinates).

Here is an example of how to use observables: https://www.babylonjs-playground.com/#XCPP9Y#281 -

这是一个如何使用监听器的例子：

Bubbling Phase

冒泡阶段

onPointerMoveObservable, onPointerEnterObservable, onPointerDownObservable, onPointerUpObservable have a bubbling phase. When an event is notified in one of these observables inside a control, it'll subsequently be notified from the same observable in its parent, recursively, until there are no more parents.

onPointerMoveObservable, onPointerEnterObservable, onPointerDownObservable, onPointerUpObservable具有一个冒泡阶段。当一个事件被一个被控对象内的监听器发现时，它也将随后被这个被控对象的父元素的监听器发现，递归的向上传播，直到没有更多的父元素。

The EventState passed as the second argument to the callback contains the properties target and currentTarget that allow you to track the bubbling phase.

事件状态被作为回调函数的第二个参数传递，它包含这个事件的所属目标和当前目标，这允许你追踪冒泡阶段。

Parameters

参数

Property 属性	Type 类型	Default 默认	Comments 注释
target	any	null	The object that originally notified the event 最初发现这个事件的对象
currentTarget	any	null	The current object in the bubbling phase 冒泡阶段中的当前对象

Here is an example of bubbling: http://www.babylonjs-playground.com/#7EPK2H -

这是一个冒泡的例子

Alignments

分组对齐

You can define the alignments used by your control with the following properties:

你可以使用下列的属性定义你的被控对象使用的分组

Property 属性	Default 默认	Comments 注释
horizontalAlignment	BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER	Can be set to left, right or center. 可以被设为左右或中间
verticalAlignment	BABYLON.GUI.Control.VERTICAL_ALIGNMENT_CENTER	Can be set to top, bottom and center. 可以被设为顶部底部或中间

Here is an example of how to use alignments: https://www.babylonjs-playground.com/#XCPP9Y#13 -

这是一个如何使用分组对齐的例子

Position and size

位置和尺寸

You can set controls' position with the following properties:

你可以使用如下的属性设置被控对象的位置：（这里的位置设定是在分组对齐基础上的修正位置，类似于dom中的相对定位）

Property	Type	Default	Default unit
left	ValueAndUnit	0	Pixel
top	ValueAndUnit	0	Pixel

Size can be set with:

可以这样设置尺寸

Property	Type	Default	Default unit
width	ValueAndUnit	100%，1，“1024px”	Percentage
height	ValueAndUnit	100%	Percentage

Paddings can be set with:

可以这样设置内边距

Property	Type	Default	Default unit
paddingTop	ValueAndUnit	0px	Pixel
paddingBottom	ValueAndUnit	0px	Pixel
paddingLeft	ValueAndUnit	0px	Pixel
paddingRight	ValueAndUnit	0px	Pixel

Please note that paddings are inside the control. This means that the usableWidth = width - paddingLeft - paddingRight. Same for usableHeight = height - paddingTop - paddingBottom.

请注意内边框是在被控对象内部的。这意味着可用的宽度=被控对象宽度-左侧内边距-右侧内边距。同样的，可用高度=被控对象高度-顶部内边距-底部内边距

All these properties can be defined using pixel or percentage as unit. To set value as pixel, use this construct: control.left = "50px" To set value as percentage, use this construct: control.left = "50%"

所有的这些属性可以以像素或百分比为单位进行定义。要把值设为像素数时，使用这个表达式：control.left = "50px" ，要把值设为百分比时，使用这个表达式：control.left = "50%"

You can also not define the unit (In this case the default unit will be used): control.width = 0.5 (which is equivalent to control.width = "50%").

你也可以不定义这个单位（这时使用默认的单位）：control.width = 0.5（等效于control.width = "50%"）

For all properties of type ValueAndUnit, you can find an associated readonly property named xxxInPixels. For instance, left works with leftInPixels which is a the left property in pixels. So if left = "50%" and the control's parent width is 150px then leftInPixels will be 75.

对于所有“值和单位”类型的属性，你可以找到一个相关的只读属性叫做xxxInPixels。举例来说，left属性具有leftInPixels属性，这个子属性使用像素表示的left属性的值。所以如果设置left = "50%"而被控对象的父元素的宽度是150像素则leftInPixels的值是75

Here is an example of how to use positions and sizes: https://www.babylonjs-playground.com/#XCPP9Y#14 -

这是一个如何使用位置和尺寸的例子

Tracking positions

位置追踪

All controls can be moved to track position of a mesh. To do this, just call control.linkWithMesh(mesh). You can then offset the position with control.linkOffsetX and control.linkOffsetY.

所有的被管对象都可以移动来追踪一个网格的位置。要做到这一点，只需要调用control.linkWithMesh(mesh).然后你可以通过control.linkOffsetX 和 control.linkOffsetY来设置被管对象与网格之间的相对位置。

Here is an example of a trackable label: https://www.babylonjs-playground.com/#XCPP9Y#16 -

这里是一个具有追踪能力的标签的例子

Please note that controls that want to track position of a mesh must be at root level (at AdvancedDynamicTexture level).

请注意，追踪网格位置的被管对象必须是在根层（直接被高级动态纹理这一层管理）的

You can also move a control to a specific coordinates in your scene with control.moveToVector3(position). Please note that the control will not stick with the vector if you change it afterwards.

你也可以将一个被管对象移动到场景中一个特定的坐标，通过control.moveToVector3(position).请注意这个被管对象将不会保持在这个三元向量的位置（而是保持在全屏ui的位置？）如果你稍后修改它的话

For Line control, you can also attach the second point to a control with line.connectedControl = control. In this case the x2 and y2 properties are used to offset the second point from the connected control.

对于线段被管对象，你还可以通过line.connectedControl = control将线段的第二个点绑定到另一个被管对象上。在这时x2和y2属性被用来设定第二个点相对于被连接的被管对象的位置。

With these 2 options, you can create a complete trackable label: https://www.babylonjs-playground.com/#XCPP9Y#20 -

使用这两个选项，你可以建立一个具有完全追踪能力的标签：

（这些标签的一个不足是不能使用超文本标记语言来更方便的定义，而只能使用js对象方式定义）

Adaptive scaling

适应性缩放

When in fullscreen UI, you can decide to define your UI with a fixed resolution. To define this resolution, just set myAdvancedDynamicTexture.idealWidth = 600 or myAdvancedDynamicTexture.idealHeight = 400.

在全屏UI中，你可以选择给UI定义一个固定的分辨率。要定义这个分辨率，只需设置myAdvancedDynamicTexture.idealWidth = 600 或 myAdvancedDynamicTexture.idealHeight = 400.

If both are set, the idealWidth will be used.

如果都设置了，将以idealWidth为主（看来改变分辨率后全屏ui仍然是铺满整个视口的，顶层UI的宽高比是视口的宽高比）

When ideal resolution is set, all values expressed in pixels are considered relatively to this resolution and scaled accordingly to match the current resolution.

在设置了理想分辨率之后，所有用像素表示的值都被认为是相对于这个分辨率的，并且会依此调整来适应当前的分辨率。（也就是比例不变？）

Even when ideal size is set, the fullscreen UI will be rendered at the same resolution of your canvas, but you can decide (mostly for performance reason) to force the texture to use the ideal size for resolution as well. To do so, just call myAdvancedDynamicTexture.renderAtIdealSize = true.

即使设定了理想尺寸，全屏UI仍会按照你的canvas的大小来绘制，但是你也可以决定强制纹理使用这个理想的尺寸作为分辨率（主要是为了性能）。要做到这一点，只需设置myAdvancedDynamicTexture.renderAtIdealSize = true.

Here is an example of how to use horizontal adaptive scaling: https://www.babylonjs-playground.com/#XCPP9Y#39 -

这里是一个如何使用水平适应性缩放的例子

Rotation and Scaling

旋转和缩放

Controls can be transformed with the following properties:

被管对象可以通过下列属性进行变形

Property	Type	Default	Comments
rotation	number	0	Value is in radians 弧度值
scaleX	number	1
scaleY	number	1
transformCenterX	number	0.5	Define the center of transformation on X axis. Value is between 0 and 1 定义X方向变形中心的位置，取值在0到1之间。（以这个点为轴旋转）
transformCenterY	number	0.5	Define the center of transformation on Y axis. Value is between 0 and 1

Please be aware that transformations are done at rendering level so after all computations. This means that alignment or positioning will be done first without taking transform in account.

请明确这一点，这些变形是在渲染层（APU）进行的，它们发生在这一帧所有的计算（CPU）之后。这意味着分组和定位会在不考虑变形的情况下先发生

Here is an example of how to use rotation and scaling: https://www.babylonjs-playground.com/#XCPP9Y#22 -

这里是一个如何使用旋转和缩放的例子

Controls

被控制对象

A control is an abstraction of a piece of UI. There are two kinds of controls:

被控制对象是UI的一片区域的抽象。有两种被控制对象：

• Pure controls: A pure control defines an action or an information useful for the user. It could be a TextBlock or a Button.
• 纯粹的被控制对象：纯粹的被控制对象定义一个对用户有用的行为或者信息。它可能是一个文本框或者一个按钮。
• Containers: Containers are used to organize your UI. They can contain other controls or containers.
• 容器：容器被用来组织你的UI，它们可以包含其他的被控制对象或者容器。

All controls share the following properties:

所有的被控制对象具有以下的属性

Property	Type	Default	Comments
alpha	number	1	Between 0 and 1. 0 means completely transparent. 1 means fully opaque 在0和1之间，0意为着完全的透明，1意味着完全的不透明
color	string	Black	Foreground color 前景颜色
fontFamily	string	Arial	Font family can be inherited. This means that if you set it on a container, it will be transmitted to all children of the container 字体可以是继承的。这意味着如果你在一个容器上设置了它，它将被传递到这个容器的所有子元素上。
fontStyle	string	Empty string	Can be inherited. Value can be "italic", "bold" or "oblique" 字形可以被继承。取值可以是“细斜体”、“粗体”或者“斜体”
fontSize	number	18	Can be inherited 字号可以被继承
zIndex	number	0	the zIndex can be used to reorder controls on the z axis 可以被用来在z轴上对被管对象进行排序

Controls can be added directly to the AdvancedDynamicTexture or to a container with:

被管对象可以被直接添加给高级动态纹理或者容器，通过：

container.addControl(control);

They can be removed with:

它们可以被移除

container.removeControl(control);

You can also control the control visibility with control.isVisible = false.

你也可以控制被管对象的可见性通过control.isVisible = false.

TextBlock

文本框

The TextBlock is a simple control used to display text: https://www.babylonjs-playground.com/#XCPP9Y#2 -

文本框是一个用来显示文字的简单被管对象：

Here are the properties you can define:

这里是你可以定义的属性

Property	Type	Default	Comments
text	string	null	Text to display 要显示的文字
textWrapping	boolean	false	Can be set to true to enable text wrapping 可以设置为true来允许换行
resizeToFit	boolean	false	Can be set to true to enable resize to fit 可以设置为true来允许根据内容改变尺寸
textHorizontalAlignment	number	BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER	Can be set to left, right or center可以设为左右或中间
textVerticalAlignment	number	BABYLON.GUI.Control.VERTICAL_ALIGNMENT_CENTER	Can be set to top, bottom or center 可以设为上下或中间

The control currently provides 1 observable:

暂时这种被管对象只提供一个专有的监听器

Observables	Comments
onTextChangedObservable	Raised when the text has changed 在文字内容改变时触发

Resize to Fit

适应性尺寸调整

When resizeToFit is set to true, the width and height of the rendered text will be automatically measured and applied to the TextBlock.

当适应性尺寸调整被设为true时，被渲染的文字的宽度和高度将被自动的计算，然后应用到文本框上（也就是字的大小不变，改变文本框的大小）

This property allows you to change the text and font of a TextBlock without having to worry about manually setting the estimated rendered width and height.

这个属性允许你改变文本框的文字和字体，而不必担心人工的设置文本框预计渲染的宽度和高度

Notice that textWrapping is ignored when resizeToFit is set to true. It doesn't make sense logically for both properties to be used at the same time as they contradict each other.

注意当适应性尺寸调整被设为真时，文字换行将被忽略。同时使用这两个属性在逻辑上没有意义，因为它们相互矛盾。

InputText

文本输入框

The InputText is a control used to let users insert text in a single line: https://www.babylonjs-playground.com/#UWS0TS -

文本输入框是一个被管对象，用来支持用户在一个单行中插入文字：

（实际测试发现这个输入和删除是有延迟的，并不完全可信）

Here are the properties you can define:

这里是你可以定义的属性

Property	Type	Default	Comments
text	string	null	Text to display 要显示的文字
color	string	white	Foreground color 前景颜色
background	string	#222222	Background color 背景颜色
focusedBackground	string	black	Background color to use when the control is focused 在这个被管对象获得焦点时使用的背景颜色
placeholderText	string	null	Text to display as placeholder (when there is no text defined and the control is not focused) 作为占位显示的文本（当输入框中没有定义文本并且没有获得焦点时）
placeholderColor	string	gray	Foreground color to use when the placeholder text is displayed 在显示占位文本时使用的前景色
autoStretchWidth	boolean	true	The control will resize horizontally to adapt to text size 被管对象将水平调整大小来适应文本尺寸
maxWidth	ValueAndUnit	100%	The maximum width allowed if autoStretchWidth is set to true 在自动调整宽度被启用时所允许的最大宽度
margin	ValueAndUnit	10px	Margin to use on left and right inside the control itself. This margin is used to determine where the text will be drawn 在被管对象内部文字左右两侧的外边距。这个外边距用来决定文字绘制在哪里。
thickness	number	1	Thickness of the border 边框的厚度

The InputText is a focusable control. This means you can click / touch it in order to give it the focus and control over the keyboard events. You can remove the focus from the control by hitting enter or clicking outside of the control.

文本输入框是一个可以获取焦点的被管对象。这意味着你可以通过点击或者触摸把焦点赋予这个被管对象，然后可以通过键盘事件进行控制。你可以从被管对象移除这个焦点，通过敲击回车或者点击被管对象的外部。

The control provides several observables to track its state:

这种被管对象提供了一些监听器来追踪它的状态：

Observables	Comments
onTextChangedObservable	Raised when the text has changed 当文字改变时触发
onFocusObservable	Raised when the control loses the focus 失去焦点时触发
onBlurObservable	Raised when the control gets the focus 获得焦点时触发

Please note that the InputText has pretty limited edition support. Here are the supported keys:

请注意这个文本输入框只具有有限的编辑支持。这里是它支持的按键：

• Delete
• Backspace
• Home
• End
• Enter
• Left / Right (used to move the cursor)

Furthermore, please note that due to JavaScript platform limitation, the InputText cannot invoke the onscreen keyboard. On mobile, the InputText will use the prompt() command to get user input. You can define the title of the prompt by setting control.promptMessage.

更进一步的，请注意因为JavaScript的平台限制性，这个文本输入框不能借助显示在屏幕上的键盘（操作系统提供的虚拟键盘）。在移动端，这个文本输入框将使用prompt()命令来获取用户的输入。你可以定义prompt命令的标题，通过设置control.promptMessage.

Button

按钮

A button can be used to interact with your user. Please see the events chapter to see how to connect your events with your buttons.

按钮可以用来与你的用户交互。请浏览事件的章节去了解如何将事件与你的按钮连接

There are four kinds of buttons available out of the box:

有四种可用的按钮

• ImageButton: An image button is a button made with an image and a text. You can create one with:
• 图片按钮:图片按钮是用一张图片（图片与按钮的左边对齐，然后接着是文本）和一段文本组成的按钮。你可以用以下代码建立它：

var button = BABYLON.GUI.Button.CreateImageButton("but", "Click Me", "textures/grass.png");

You can try it here: https://www.babylonjs-playground.com/#XCPP9Y#3 -

你可以在这里试用它

• ImageWithCenterTextButton: An image button made with a image background and a centered text.
• 图片以及居中文本按钮：一个用图片作为背景并且具有一段居中文本的图片按钮

var button = BABYLON.GUI.Button.CreateImageWithCenterTextButton("but", "Click Me", "textures/grass.png");

You can try it here: https://www.babylonjs-playground.com/#PLTRBV -

在这里试用

• SimpleButton: A simple button with text only
• 简单按钮：简单按钮只有文本

var button = BABYLON.GUI.Button.CreateSimpleButton("but", "Click Me");

You can try it here: https://www.babylonjs-playground.com/#XCPP9Y#4 -

在这里试用

• ImageOnlyButton:
• 只有图片的按钮

var button = BABYLON.GUI.Button.CreateImageOnlyButton("but", "textures/grass.png");

You can try it here: https://www.babylonjs-playground.com/#XCPP9Y#28 -

在这里试用

Visual animations

可视动画

By default a button will change its opacity on pointerover and will change it scale when clicked. You can define your own animations with the following callbacks:

默认情况下一个按钮将在指针经过时改变不透明度，并且将在被点击时改变缩放。你可以使用以下的回调函数来定义你自己的动画效果

• pointerEnterAnimation
• pointerOutAnimation
• pointerDownAnimation
• pointerUpAnimation

Custom button

用户自定义按钮

You can also create a complete custom button by manually adding children to the button. Here is how the ImageButton is built:

你也可以通过手动的为按钮添加子元素来建立一个完全自定义的按钮。以下是如何构建图片按钮：

var result = new Button(name);

// Adding text

var textBlock = new BABYLON.GUI.TextBlock(name + "_button", text);

textBlock.textWrapping = true;

textBlock.textHorizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER;

textBlock.paddingLeft = "20%";

result.addControl(textBlock);   

// Adding image

var iconImage = new BABYLON.GUI.Image(name + "_icon", imageUrl);

iconImage.width = "20%";

iconImage.stretch = BABYLON.GUI.Image.STRETCH_UNIFORM;

iconImage.horizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;

result.addControl(iconImage);            

return result;

Checkbox

复选框

The checkbox is used to control a boolean value. You can specify the value with checkbox.isChecked.

复选框用来控制一个布尔值。你可以通过checkbox.isChecked来设定这个值。

Changing the isChecked property will raise an observable called checkbox.onIsCheckedChangedObservable.

改变是否被选中属性将触发一个叫做checkbox.onIsCheckedChangedObservable的监听。

The control is rendered using the following properties:

这个被管对象使用如下的属性渲染：

Property	Type	Default	Comments
color	string	white	Foreground color 前景颜色
background	string	black	Background color 背景颜色
checkSizeRatio	number	0.8	Define the ratio used to compute the size of the inner checkbox (0.8 by default, which means the inner check size is equal to 80% of the control itself) 定义用来计算复选框内部尺寸的比率（默认是0.8，这意味着内部的区域占被管对象尺寸的80%）

Here is an example of a checkbox: https://www.babylonjs-playground.com/#U9AC0N#2 -

这里是一个复选框的例子

RadioButton

单选按钮

The radio button is used to define a value among a list by using a group of radio buttons where only one can be true. You can specify the selected value with radiobutton.isChecked.

单选按钮通过一组只能有一个为真的单选按钮来在一个列表中选取一个值。你可以通过radiobutton.isChecked来指定选中的值。

Changing the isChecked property will raise an observable called checkbox.onIsCheckedChangedObservable. Furthermore, if you select a radio button, all other radio buttons within the same group will turn to false.

修改是否选定属性将触发一个叫做checkbox.onIsCheckedChangedObservable的事件。更进一步的，如果你选中了一个单选按钮，所有在同一个组里的单选按钮将转变为假

The control is rendered using the following properties:

这个被管对象使用下列的属性渲染：

Property	Type	Default	Comments
color	string	white	Foreground color
background	string	black	Background color
checkSizeRatio	number	0.8	Define the ratio used to compute the size of the inner checkbox (0.8 by default, which means the inner check size is equal to 80% of the control itself)
group	string	empty string	Use the group property to gather radio buttons working on the same value set 使用分组属性来收集为同一个值工作的单选按钮

Here is an example of a radiobutton: https://www.babylonjs-playground.com/#U9AC0N#13 -

这里是一个单选按钮的例子：

Slider

滑块

The slider is used to control a value within a range. You can specify the range with slider.minimum and slider.maximum.

滑块用来在一个范围内控制一个值。你可以使用slider.minimum 和 slider.maximum来指定这个范围

The value itself is specified with slider.value and will raise an observable everytime it is changed (slider.onValueChangedObservable).

这个值本身使用slider.value指定，并且将在它每次改变时触发一个事件（slider.onValueChangedObservable）

The control is rendered using the following properties:

这个被控对象使用下列属性渲染：

Property	Type	Default	Comments
borderColor	string	white	Color used to render the border of the thumb 用来渲染小滑块的边缘的颜色
color	string	white	Foreground color 前景色
background	string	black	Background color 背景色
barOffset	ValueAndUnit	5px	Offset used vertically to draw the background bar 绘制背景条的垂直偏移
thumbWidth	ValueAndUnit	30px	Width of the thumb 小滑块的宽度

 Here is an example of a slider: https://www.babylonjs-playground.com/#U9AC0N#1 -

这里是一个滑块的例子：

Line

线段

The line will draw a line (!!) between two points.

线段被管对象将在两个点之间画一条线。

Here are the properties you can define:

这里是你可以定义的属性：

Property	Type	Default	Comments
x1	number	0	X coordinate of the first point 第一个点的X坐标
y1	number	0	Y coordinate of the first point
x2	number	0	X coordinate of the second point
y2	number	0	Y coordinate of the second point
dash	array of numbers	Empty array	Defines the size of the dashes 定义虚线的尺寸
lineWidth	number	1	Width in pixel 以像素表示的宽度

Here is an example of a line: https://www.babylonjs-playground.com/#XCPP9Y#6 -

这是一个线段的例子

Image

图片

Use the image control to display an image in your UI. You can control the stretch used by the image with image.stretch property. You can set it to one of these values:

使用图像被控对象在你的UI里显示一张图片。你可以使用image.stretch属性控制这个图片使用的拉伸方式。你可以把它设置为这些值中的一个

• BABYLON.GUI.Image.STRETCH_NONE: Use original size
• 使用原始尺寸
• BABYLON.GUI.Image.STRETCH_FILL: Scale the image to fill the container (This is the default value)
• 缩放图片来填满容器（默认值）
• BABYLON.GUI.Image.STRETCH_UNIFORM: Scale the image to fill the container but maintain aspect ratio
• 缩放图片填满容器，但是保持宽高比
• BABYLON.GUI.Image.STRETCH_EXTEND: Scale the container to adapt to the image size.
• 缩放容器来适应图片的尺寸。

You may want to have the Image control adapt its size to the source image. To do so just call image.autoScale = true.

你可能希望让图片被管对象按照源图片调整尺寸。要做到这一点只需调用image.autoScale = true.

You can change image source at any time with image.source="myimage.jpg".

你可以随时修改图片源通过image.source="myimage.jpg".

You can also define which part of the source image you want to use with the following properties:

你也可以使用以下属性定义你要使用源图片的哪个部分：

• sourceLeft: x coordinate in the source image (in pixel)
• 在源图片中的x坐标（以像素表示）
• sourceTop: y coordinate in the source image (in pixel)
• sourceWidth: width of the source image you want to use (in pixel)
• 你希望使用的部分的宽度
• sourceHeight: height of the source image you want to use (in pixel)

Here is an example of an image: https://www.babylonjs-playground.com/#XCPP9Y#7 -

这是一个使用图片的例子

VirtualKeyboard

虚拟键盘

The VirtualKeyboard is a control used to display simple onscreen keyboard. This is mostly useful with WebVR scenarios where the user cannot easily use his keyboard.

虚拟键盘是一个用来在屏幕上显示简单键盘的被管对象。它通常被使用在WebVR场景中，因为那时用户往往不能方便的使用他的键盘

Keys

按键

You can define the keys provided by the keyboard with the following code:

你可以通过如下的代码定义从键盘提供的按键

var keyboard = new BABYLON.GUI.VirtualKeyboard();

keyboard.addKeysRow(["1", "2", "3", "4", "5", "6", "7", "8", "9", "0","u2190"]);

Every key will be created using default values specified by the following properties:

所有的按键将使用默认值建立，可以通过以下属性设定默认值：

Property	Default
defaultButtonWidth 默认按钮宽度	40px
defaultButtonHeight 默认按钮高度	40px
defaultButtonPaddingLeft 默认按钮左内边距	2px
defaultButtonPaddingRight 默认按钮右内边距	2px
defaultButtonPaddingTop 上内边距	2px
defaultButtonPaddingBottom 下内边距	2px
defaultButtonColor 颜色(前景？)	#DDD
defaultButtonBackground 背景	#070707

You can also override each property by providing an array containing properties for keys (or null):

你也可以通过提供一个包含按键属性的数组来覆盖每一个属性

addKeysRow(["a", "b"], [null, { width: "200px"}]);

You can define each default properties based on the following class:

你可以基于以下的类来定义每个默认属性：

class KeyPropertySet {

      width?: string;

      height?: string;

      paddingLeft?: string;

      paddingRight?: string;

      paddingTop?: string;

      paddingBottom?: string;

      color?: string;

      background?: string;

  }

Layouts

布局

The VirtualKeyboard provides a static method to create a default layout:

虚拟键盘提供一个静态方法来建立默认的布局

var keyboard = BABYLON.GUI.VirtualKeyboard.CreateDefaultLayout();

The default layout is equivalent to:

默认的布局是这样的：

addKeysRow(["1", "2", "3", "4", "5", "6", "7", "8", "9", "0","u2190"]);

addKeysRow(["q", "w", "e", "r", "t", "y", "u", "i", "o", "p"]);

addKeysRow(["a", "s", "d", "f", "g", "h", "j", "k", "l",";","'","u21B5"]);

addKeysRow(["z", "x", "c", "v", "b", "n", "m", ",", ".", "/"]);

addKeysRow([" "], [{  "200px"}]);

Events

事件

Every time a key is pressed the onKeyPressObservable observable is triggered. But you can also rely on keyboard.connect(inputText) to automatically connect a VirtualKeyboard to an InputText. In this case, the keyboard will only appear when the InputText will be focused and all key pressed events will be sent to the InputText.

每次有按键被按下时onKeyPressObservable事件被触发。但是你也可以依靠keyboard.connect(inputText)来自动的把一个虚拟键盘和一个输入文本框连接起来，这个键盘将只在这个文本输入框获得焦点时出现，并且所有的按键按下事件将被发送到这个文本输入框。

You can find a complete demo here: https://www.babylonjs-playground.com/#S7L7FE -

你可以在这里找到一个完整的示例：

Containers

容器

The containers are controls used to host other controls. Use them to organize your UI. Containers has one specific property: container.background. Use it to define the background color of your container.

容器是用来主持其他被管对象的被管对象。使用他们来组织你的UI。容器有一个独有的属性：container.background.使用它来定义你的容器的背景颜色

Rectangle

矩形

The Rectangle is a rectangular container with the following properties:

矩形是一个具有以下属性的长方形的容器

Property	Type	Default	Comments
thickness	number	1	Thickness of the border 边框的厚度
cornerRadius	number	0	Size in pixel of each corner. Used to create rounded rectangles 用像素表示的每个边角的尺寸。用来建立圆角矩形

Here is an example of a rectangle control: https://www.babylonjs-playground.com/#XCPP9Y#8 -

这里是一个矩形被管对象的例子

Ellipse

椭圆

The Ellipse is a ellipsoidal container with the following properties:

椭圆是一种椭圆的具有以下属性的容器

Property	Type	Default	Comments
thickness	number	1	Thickness of the border 边框的厚度

Here is an example of an ellipse control: https://www.babylonjs-playground.com/#XCPP9Y#10 -

这里是一个椭圆被管对象的例子

StackPanel

堆栈面板

The StackPanel is a control which stacks its children based on its orientation (can be horizontal or vertical). All children must have a defined width or height (depending on the orientation).

堆栈面板是一种基于排列方向（水平或竖直）来堆积子元素的被管对象。所有的子元素都必须具有一个定义好的宽度或高度（基于排列方向）

The height (or width) of the StackPanel is defined automatically based on children.

堆栈面板的高度（或宽度）基于子元素自动定义

Here is an example of a StackPanel: https://www.babylonjs-playground.com/#XCPP9Y#11 -

这里是一个堆栈面板的例子

ColorPicker

拾色器

The color picker control allows users to set colors in your scene.

拾色器被管对象允许用户在你的场景内设置颜色。

Whenever a user interacts with the color picker an observable is triggered (colorPicker.onValueChangedObservable) which returns the current value (Color3) of the color picker.

当用户和拾色器交互时一个事件被触发(colorPicker.onValueChangedObservable)，它将返回拾色器当前的值（Color3）

The control is rendered using the following properties:

这个被管对象基于以下属性渲染：

Property	Type	Default	Comments
size	string or number	"200px"	The size, width, and height property will always be the same value since the color picker can only be a square. 尺寸，宽度和高度属性必须是相同的值因为拾色器必须是一个方块

Here is an example of a color picker: https://www.babylonjs-playground.com/#91I2RE#1 -

这里是一个拾色器的例子：

Helpers（Header？）

帮助

To reduce the amount of code required to achieve frequent tasks you can use the following helpers:

为了降低频繁的任务所需的代码数量，你可以使用如下的帮助

• BABYLON.GUI.Control.AddHeader(control, text, size, options { isHorizontal, controlFirst }): This function will create a StackPanel (horizontal or vertical based on options) and will add your control plus a TextBlock in it. Options can also be used to specify if the control is inserted first of after the header. Depending on the orientation, size will either specify the widht or the height used for the TextBlock.

BABYLON.GUI.Control.AddHeader(control, text, size, options { isHorizontal, controlFirst }):这个方法将建立一个堆栈面板（基于选项确定水平还是竖直），然后将把你的被管对象和一个文本框一起放在这个堆栈面板里面。同样可以通过选项设置这个被管对象插入到标题的前面还是后面。根据方向，文本框的宽度或者高度尺寸也将被自动设定。

Focus management

焦点管理

The current focused control can be found using advancedDynamicTexture.focusedControl. You can also manually move the focus to a focusable control by calling advancedDynamicTexture.moveFocusToControl(control).

可以使用advancedDynamicTexture.focusedControl找到当前保有焦点的被管对象。你也可以人工的将焦点移动到一个可以获得焦点的被管对象上，通过调用advancedDynamicTexture.moveFocusToControl(control)。