Scene2d.ui 

Overview

scene2d is libgdx's 2D scene graph. At its core, it provides basic 2D scene graph functionality: actors, groups, drawing, events, and actions. 
//
This is a lot of utility that applications can leverage, but it is reasonably low level. For games this is fine because most actors are application specific. 
For building UIs, the scene2d.ui package provides common UI widgets and other classes built on top of scene2d.

Widget and WidgetGroup
UIs often have many UI widgets to be sized and positioned on the screen. Doing this manually is time consuming, makes code difficult to read and maintain, and doesn't easily adapt to different screen sizes. The Layout interface defines methods that allow for more intelligent layout for actors.
//UI通常有大量的UI 物件需要定义大小和位置在屏幕上。手动的操作比较浪费时间，使得代码很困难去阅读和维护，而且不容易适应不同的屏幕大小。这个Layout接口定义了方法，允许更智能的布局actors。

The Widget and WidgetGroup classes extend Actor and Group respectively, and they both implement Layout. These two classes are the basis for actors that will participate in layout. UI widgets should extend WidgetGroup if they have child actors, otherwise they should extend Widget.
//Widget和WidgetGroup 类分别继承了Actor and Group类。他们都实现了Layout接口。这两个类是基础，参与了布局。UI物件应当继承WidgetGroup，如果他们有孩子actors，否则，即没有孩子，继承Widget。

Layout

UI widgets do not set their own size and position. Instead, the parent widget sets the size and position of each child. Widgets provide a minimum, preferred, and maximum size that the parent can use as hints. Some parent widgets, such as Table and Container, can be given constraints on how to size and position the children. To give a widget a specific size in a layout, the widget's minimum, preferred, and maximum size are left alone and size constraints are set in the parent.
//UI物件不设置大小和位置。相反，父母物件设置孩子节点的大小和位置。
//Widgets提供一个最小，首选，最大的尺寸。一些父母物件，比如Table和 Container，可以给限制如何设置孩子的大小和位置。
//给一个物件一个特定的大小在布局中，物件的最小，首选，最大的尺寸不用管。
Before each widget is drawn, it first calls validate. If the widget's layout is invalid, its layout method will be called so that the widget (and any child widgets) can cache information needed for drawing at their current size. The invalidate and invalidateHierarchy methods both invalidate the layout for a widget.
//在一个物件被绘制之前，它首先调用证实方法。如果这个物件的布局无效，它的布局方法将被调用，以致这个物件可以缓存绘制的信息。
invalidate should be called when the widget's state has changed and the cached layout information needs to be recalculated, but the widget's minimum, preferred, and maximum size are unaffected. This means that the widget needs to be laid out again, but the widget's desired size hasn't changed so the parent is unaffected.

invalidateHierarchy should be called when the widget's state has changed that affects the widget's minimum, preferred, or maximum size. This means that the parent's layout may be affected by the widget's new desired size. invalidateHierarchy calls invalidate on the widget and every parent up to the root.

Stage setup

Most scene2d.ui layouts will use a table that is the size of the stage. All other widgets and nested tables are placed in this table.
//大部分scene2d.ui布局使用一个table，就是这个stage的尺寸。所有其他物件和网状table被放在这个table中。
Here is an example of the most basic scene2d.ui application with a root table:

private Stage stage;

public void create () {
    stage = new Stage();
    Gdx.input.setInputProcessor(stage);

    Table table = new Table();
    table.setFillParent(true);
    stage.addActor(table);

    // Add widgets to the table here.
}

public void resize (int width, int height) {
    stage.getViewport().update(width, height, true);
}

public void render () {
    Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT);
    stage.act(Gdx.graphics.getDeltaTime());
    stage.draw();

    Table.drawDebug(stage); // This is optional, but enables debug lines for tables.
}

public void dispose() {
    stage.dispose();
}
Note that setFillParent is used on the root table, causing it to be sized to its parent (in this case, the stage) when validated. Normally a widget's size is set by its parent and setFillParent must not be used. setFillParent is for convenience only when the widget's parent does not set the size of its children (such as the stage).
//记住，setFillParent方法被用在root table上，因为它定义父亲stage的大小，当有效时。
正常的，一个物件的大小被父亲设置，setFillParent是禁止使用的。
//setFillParent为了方便起见，只有当这个物件的父亲不是指它的孩子的大小时用，比如stage。
Tables automatically adapt to various screen resolutions, so this sets up a stage that uses pixel coordinates. See stage viewport setup for setting up a stage that scales.
//Table 自动适应不同的屏幕分辨率，所以建立一个stage使用像素坐标。

Skin

Most UI widgets are made up of a few configurable resources: images, fonts, colors, etc. All the resources needed to render a widget is called a "style". Each widget defines its own style class (usually a static member class) and has constructors for setting the initial style and a setStyle method for changing the style later.
//大部分UI物件由这些可配置的资源组成，images, fonts, colors等。
//所有资源需要渲染一个物件，叫做style。
//每一个物件定义它自己的style类，有构造方法for初始化style。和setStyle方法。
Skin files from the libgdx tests can be used as a starting point. You will need: uiskin.png, uiskin.atlas, uiskin.json, and default.fnt. This enables you to quickly get started using scene2d.ui and replace the skin assets later.
//来自libgdx tests 的Skin文件可以被用来作为一个开始点。
//你将需要uiskin.png, uiskin.atlas, uiskin.json, and default.fnt.
//这个使你scene2d.ui ，以后替换skin资源。

Note the same style can be used for multiple widgets. Also note that all images needed by UI widgets are actually implementations of the Drawable interface.
相同style可以被用于多个物件。所有用于UI的图片都实现了Drawable接口。
The Skin class can be used to more conveniently define the styles and other resources for UI widgets. See the Skin documentation for more information. It is very strongly recommended to use Skin for convenience, even if not defining styles via JSON.
Skin类能更方便的定义style和其他资源。

ChangeEvents

Most widgets fire a ChangeEvent when something changes. This is a generic event, what actually changed depends on each widget. Eg, for a button the change is that the button was pressed, for a slider the change is the slider position, etc.

ChangeListener should be used to detect these events:

actor.addListener(new ChangeListener() {
    public void changed (ChangeEvent event, Actor actor) {
        System.out.println("Changed!");
    }
});
ChangeListener should be used when possible instead of ClickListener, eg on buttons. 
//尽量使用ChangeListener ，当可能的代替ClickListener
//原地按下，原地抬起 出发changed事件。
//因为ChangeEvent可以被取消。
ClickListener reacts to input events on the widget and only knows if the widget has been clicked. 
The click will still be detected if the widget is disabled and doesn't handle the widget being changed by a key press or programmatically. 
Also, for most widgets the ChangeEvent can be cancelled, allowing the widget to revert the change.


Clipping

Clipping is most easily done using setClip(true) on a Table. Actors in the table will be clipped to the table's bounds. Culling is done so actors completely outside of the table's bounds are not drawn at all.

Actors added to a table using the add Table methods get a table cell and will be sized and positioned by the table. Like any group, actors can still be added to a table using the addActor method. The table will not size and position actors added this way. This can be useful when using a table solely for clipping.

Rotation and scale

As described previously, a scene2d group that has transform enabled causes a SpriteBatch flush before drawing its children. 
A UI often has dozens, if not hundreds, of groups. Flushing for each group would severely limit performance, so most scene2d.ui groups have transform set to false by default. 
一个UI通常有很多groups。刷新将要严重的限制了性能，因此大部分groups默认不设置。
Rotation and scale is ignored when the group's transform is disabled.

Transforms can be enabled as needed, with some caveats. Not all widgets support all features when rotation or scaling is applied. Eg, transform can be enabled for a Table and then it can be rotated and scaled. Children will be drawn rotated and scaled, input is routed correctly, etc. 
//变形transform有时候开启，不是所有的物件支持所有的特性，当旋转和方法应用的时候。
However, other widgets may perform drawing without taking rotation and/or scale into account. A workaround for this problem is to wrap a widget in a table or container with transform enabled and set the rotation and scale on the table or container, not on the widget:

TextButton button = new TextButton("Text Button", skin);
Container wrapper = new Container(button);
wrapper.setTransform(true);
wrapper.setOrigin(wrapper.getPrefWidth() / 2, wrapper.getPrefHeight() / 2);
wrapper.setRotation(45);
wrapper.setScaleX(1.5f);
Note that scene2d.ui groups that perform layout, such as Table, will use the unscaled and unrotated bounds of a transformed widget when computing the layout.

Widgets that perform clipping, such as ScrollPane, use glScissor which uses a screen aligned rectangle. These widgets cannot be rotated.


Layout widgets

Table

The Table class sizes and positions its children using a logical table, similar to HTML tables. Tables are intended to be used extensively in scene2d.ui to layout widgets, as they are easy to use and much more powerful than manually sizing and positioning widgets. Table-based layouts don't rely on absolute positioning and therefore automatically adjust to different widget sizes and screen resolutions.
//表格类定义它的孩子的大小和位置，使用一个逻辑的表格，和HTML table很像。
Table类广泛的用于scene2d.ui 中布局物件，因为它很容易使用，比手工布局更方便。
//基于表格的布局不用依赖绝对坐标，因此自动的适应不同的物件大小和屏幕像素。
It is highly recommended to read the Table documentation before building a UI using scene2d.ui.
//非常推荐

Container

The Container class is equivalent to a Table with only a single child, but is more lightweight. Container has all of the constraints of a table cell and are useful for setting the size and alignment of a single widget.
//Container类 与 只有一个孩子的table类很像，但是更轻量级。
Container有一个table 格子的所有限制，有用的设置大小和排列。


Stack

Stack is a WidgetGroup that lays out each child to be the size of the stack. This is useful when it is necessary to have widgets stacked on top of each other. The first widget added to the stack is drawn on the bottom, and the last widget added is drawn on the top.
//栈 ，一个堆着一个，第一个在下，最后一个在上。

ScrollPane

//ScrollPane滚动一个孩子物件。
//当一个物件大于ScrollPane使用，滚动自动可以用。
ScrollPane scrolls a child widget using scrollbars and/or mouse or touch dragging. 
Scrolling is automatically enabled when the widget is larger than the scroll pane. 
If the widget is smaller than the scroll pane in one direction, it is sized to the scroll pane in that direction. ScrollPane has many settings for if and how touches control scrolling, fading scrollbars, etc. ScrollPane has drawables for the background, horizontal scrollbar and knob, and vertical scrollbar and knob. 
If touches are enabled (the default), all the drawables are optional.
//如果能够触摸，所有的drawables都可以选择。
The ScrollPane preferred width

SplitPane
//和java类似。
SplitPane contains two widgets and is divided in two either horizontally or vertically. The user may resize the widgets with a draggable splitter. The child widgets are always sized to fill their half of the splitpane. SplitPane has a drawable for the draggable splitter.

Tree

Tree displays a hierarchy of nodes. Each node may have child nodes and can be expanded or collapsed. Each node has an actor, allowing complete flexibility over how each item is displayed. Tree has drawables for the plus and minus icons next to each node's actor.

VerticalGroup
//竖直Group 等于 只有一列的table。可以使物件插入中间，或者出去。
The VerticalGroup class is equivalent to a Table with only a single column, but is more lightweight. VerticalGroup allows widgets to be inserted in the middle and removed, while Table does not.

HorizontalGroup
//只有一行的table
The HorizontalGroup class is equivalent to a Table with only a single row, but is more lightweight. HorizontalGroup allows widgets to be inserted in the middle and removed, while Table does not.

Widgets  //物件。

Label

//用来展示文字和颜色，Word wrap应该开启。有父亲定义宽。
Label displays text using a bitmap font and a color. The text may contain newlines. Word wrap may be enabled, in which case the width of the label should be set by the parent. The lines of text can be aligned relative to each other, and also all of the text aligned within the label widget.
//使用同样的字体在同样的大小，可能颜色不同。
//建议不同大小的font，使用不同的Bitmap fonts。
//bitmap font image 应当被打包进skin's atlas。
The labels that use the same font will be the same size, though they may have different colors. Bitmap fonts don't typical scale well, especially at small sizes. It is suggested to use a separate bitmap font for each font size. The bitmap font image should be packed into the skin's atlas to reduce texture binds.
Label.setWrap(false);
//false的话，只包裹字符串中出现的几行。
//true的话，包裹所有字符串。



Image

Image simply displays a drawable. The drawable can be a texture, texture region, ninepatch, sprite, etc. The drawable may be scaled and aligned within the image widget bounds in various ways.

Button

//Button 本身是个空的。但是它继承了table，所以它可以加入其他物件。
//它的up background 是正常情况下显示的，它的down background是 按下时显示的。
//它有一个checked 状态，是toggle的。
//它有一个offset偏移，
Button by itself it is just an empty button, but it extends table so other widgets can be added to it. It has an up background that is normally displayed, and a down background that is displayed when pressed. It has a checked state which is toggled each time it is clicked, and when checked it will use the checked background instead of up, if defined. It also has pressed/unpressed offsets, which offset the entire button contents when pressed/unpressed.

TextButton
//TextButton继承Button，并且包含一个Label。
//Button继承table，所以他们都可以使用table的方法加入物件。
TextButton extends Button and contains a label. TextButton adds to Button a bitmap font and a colors for the text in the up, down, and checked states.

TextButton extends Button which extends Table, so widgets can be added to the TextButton using the Table methods.

ImageButton
//加入一个drawable对象。
ImageButton extends Button and contains an image widget. ImageButton adds to Button a drawables for the image widget in the up, down, and checked states.
//记住，有3种状态的3个图片了。一个icon在最上面。
Note that ImageButton extends Button, which already has a background drawable for the up, down, and checked states. ImageButton is only needed when it is desired to have a drawable (such as an icon) on top of the button background.

ImageButton extends Button which extends Table, so widgets can be added to the ImageButton using the Table methods.

CheckBox
//继承TextButton，增加了一个图片在左边。
//它有一个drawable 图片 来标示 选择还是没选择的状态。
CheckBox extends TextButton and adds an image widget to the left of the label. It has a drawable for the image widget for the checked and unchecked states.

ButtonGroup
//ButtonGroup不是一个actor，没有视图。用来加入Button。
//它可以加入多种Button。
ButtonGroup is not an actor and has no visuals. Buttons are added to it and it enforces a minimum and maximum number of checked buttons. This allows for buttons (button, text button, checkbox, etc) to be used as "radio" buttons.

TextField
//仅仅是一个单行文本条目。有drawables背景，文本游标，字体，颜色。
//当字段是空的时候，还可以有文字提示。
//可以开启password模式。可以代替。
TextField is a single line text entry field. It has drawables for the background, text cursor, and text selection, a font and font color for the entered text, and a font and font color for the message displayed when the text field is empty. Password mode can be enabled, where it will display asterisks instead of the entered text.

TextArea
//允许多行
TextArea is similiar to a TextField, but allows multiple line text entry.

List
//List 是一个列表盒子，显示本的条目，高亮选择的条目。
//有一个字体，选择条目背景drawable，字体颜色for 选的，或者未选择的。
####一个列表本身不会scroll，但是它通常放在一个scrollpane中。
############################################################
List is a list box that displays textual items and highlights the selected item. List has a font, selected item background drawable, and a font color for selected and unselected items. A list does not scroll on its own, but is often put in a scrollpane.

SelectBox
//是一个下拉列表，它允许选择其中一个。
//当不激活的时候，选中的条目显示。激活时，显示一个下拉列表。
//有背景drawables，list背景，选择条目的背景。共3个。
//还有字体和颜色。两个条目之间的空隙多大也有。
SelectBox is a drop-down list, it allows one of a number of values to be chosen from a list. When inactive, the selected value is displayed. When activated, it shows the list of values that may be selected. SelectBox has drawables for the background, list background, and selected item background, a font and font color, and a setting for how much spacing is used between items.

ProgressBar
//有一个最大最小值。竖直 向右和水平 向上。
Progress Bar is a widget that visually displays the progress of some activity or a variable value within a given range. The progress bar has a range (min, max) and a stepping between each value it represents. The percentage of completeness typically starts out as an empty progress bar and gradually becomes filled in as the task or value increases towards upper limit.
//使用Animation改变progress bar value，使得看起来很平滑。
A progress bar can be setup to be of horizontal or vertical orientation, although the increment direction is always the same. For horizontal progress bar, is grows to the right, for vertical, upwards. Animation for changes to the progress bar value can be enabled to make the bar fill more smoothly over time.

Slider
//是一个水平指示器，允许使用者设置一个值。
//有背景，按钮，和 按钮前后的部分。
Slider is a horizontal indicator that allows a user to set a value. The slider his a range (min, max) and a stepping between each value the slider represents. Slider has drawables for the background, the slider knob, and for the portion of the slider before and after the knob.

A slider with touches disabled, a drawable before the knob, and without the knob can be used as a substitute for progress bar, as both widgets share the same codebase and use same visual style. Animation for changes to the slider value can be enabled to make the progress bar fill more smoothly.

Window

//是一个上面标题栏区域的table。它可以选择地做一个对话框，
//有背景drawable，标题字体和颜色。
Window is a table with a title bar area above the contents that displays a title. It can optionally act as a modal dialog, preventing touch events to widgets below. Window has a background drawable and a font and font color for the title.

Touchpad
//是一个屏幕上的游戏杆，在一个圆圈的区域中移动。
//有背景，和 按钮背景。
Touchpad is an onscreen joystick that moves in a circular area. It has a background drawable and a drawable for the knob that the user drags around.
getX()15.0 //整个面板的左下角的（x，y值）
getY()15.0
KnobPercentX0.0 //面板的中心为0，向右为+正，向左为-负。（-1,1）
KnobX50.0  //（10,90） 最左端接近10，最右端接近90。
/////////////////////



Dialog
//是一个window 带着一个内容table 和下面有一个按钮table。
任何东西可以加入dialog中，但是方便的方法提供了 增加label 和button。
Dialog is a window with a content table and a button table underneath. Anything can be added to the dialog, but convenience methods are provided to add a label to the content table and buttons to the button table.

Widgets without scene2d.ui

Widgets can be used as simple actors in scene2d, without using tables or the rest of scene2d.ui. Widgets have a default size and can be positioned absolutely, the same as any actor. If a widget's size is changed, the invalidate Widget method must be called so the widget will relayout at the new size.

//有些物件，比如table，在构造后没有默认的大小，因为他们的首选大小 是基于他们包含的物件的大小而定的。
//在物件增加之后，pack方法被使用来设置。
//一个物件大小被改变后，调用validate方法，如果无效，重新定义自己的大小。
Some widgets, such as Table, don't have a default size after construction because their preferred size is based on the widgets they will contain. After the widgets have been added, the pack method can be used to set the width and height of the widget to its preferred width and height. This method also calls invalidate if the widget's size was changed, and then calls validate so that the widget adjusts itself to the new size.