feat: translate scenegraph to cn_zn

Author: Crazyokd

src/docs/asciidoc/index_zh.asc

@@ -13,7 +13,7 @@
 
 include::zh/introduction.asc[]
 
-include::scenegraph.asc[]
+include::zh/scenegraph.asc[]
 
 include::ui-controls.asc[]
 

src/docs/asciidoc/zh/scenegraph.asc

@@ -0,0 +1,340 @@
+= Scene Graph
+
+== 概述
+
+一个 scene graph 就是一种树形数据结构，用于排列（和分组）图形对象以便于逻辑表示。 它还允许图形引擎通过完全或部分跳过在最终图像中看不到的对象，以最有效的方式渲染对象。
+下图展示了 JavaFX scene graph 的体系结构。
+
+image::images/scenegraph/scene_graph.jpg[title="JavaFX Scene Graph"]
+
+在体系结构的最上层有一个 `Stage`。
+一个 stage 就是一个本机操作系统窗口的 JavaFX 表示。
+在任意给定时刻，stage 都可以附带一个单独的 `Scene`。
+一个 scene 就是一个 JavaFX scene graph 的容器。
+
+以下将直译 `scene graph` 为“场景图”。
+
+在 JavaFX 场景图中所有元素都作为 `Node` 对象展示。
+有三种类型的结点（Node）：root，branch 和 leaf。
+如上图所示，root 是唯一没有父结点的结点并直接被 scene 所包含。
+branch 和 leaf 之间的不同主要是 leaf 节点没有孩子节点（children）。
+
+在场景图中，父结点的许多属性都会共享给子结点。
+比如，一个应用于父结点上的变换或事件也会递归的应用于它的子结点。
+因此，可以将复杂的节点层次结构视为单个节点以简化编程模型。
+在稍后的部分我们将探索变换（transformation）和事件（event）。
+
+下图是一个“Hello World”的场景图示例。
+
+image::images/scenegraph/specific_scene_graph.jpg[title="Hello World Scene Graph"]
+
+产生与上图匹配的场景图的一种可能实现如下。
+
+[source,java]
+.HelloApp.class
+----
+public class HelloApp extends Application {
+
+    private Parent createContent() {
+        return new StackPane(new Text("Hello World"));
+    }
+
+    @Override
+    public void start(Stage stage) throws Exception {
+        stage.setScene(new Scene(createContent(), 300, 300));
+        stage.show();
+    }
+
+    public static void main(String[] args) {
+        launch(args);
+    }
+}
+----
+
+下面这张图就是运行代码的结果。
+
+image::images/scenegraph/hello_world.jpg[title="Hello World"]
+
+重要的注意事项：
+
+* 一个节点最多有一个父节点
+* ”active“（附加到一个当前可见的 scene）场景图中的节点只能从 JavaFX 应用程序线程中修改。
+
+== 变换
+
+我们将使用下面的应用程序作为一个示例去演示3种最常见的变换。
+
+[source,java]
+.TransformApp.class
+----
+public class TransformApp extends Application {
+
+    private Parent createContent() {
+        Rectangle box = new Rectangle(100, 50, Color.BLUE);
+
+        transform(box);
+
+        return new Pane(box);
+    }
+
+    private void transform(Rectangle box) {
+        // we will apply transformations here
+    }
+
+    @Override
+    public void start(Stage stage) throws Exception {
+        stage.setScene(new Scene(createContent(), 300, 300, Color.GRAY));
+        stage.show();
+    }
+
+    public static void main(String[] args) {
+        launch(args);
+    }
+}
+----
+
+运行应用程序将导致下面图片中的结果。
+
+image::images/scenegraph/transform_base.jpg[title="Blue Box"]
+
+在 JavaFX中，一个简单的变换可以发生在 3 个轴（X、Y 或 Z）之一。
+示例是个2D应用程序，所以我们将仅考虑 X 轴和 Y 轴。
+
+=== 移动
+
+在 JavaFX 和计算机图形学中，`translate` 意味着移动。
+我们可以把我们的 box 在 X 轴移动100像素，在 Y 轴移动200像素。
+
+[source,java]
+----
+private void transform(Rectangle box) {
+    box.setTranslateX(100);
+    box.setTranslateY(200);
+}
+----
+
+image::images/scenegraph/transform_translate.jpg[title="Translate"]
+
+=== 缩放
+
+你可以使用缩放去使得一个节点变大或缩小。
+缩放值是一个比率。
+默认情况下，一个节点在每个轴上的缩放值为1。
+我们可以通过在 X 轴 和 Y 轴上应用 1.5 倍缩放来放大我们的 box 。
+
+[source,java]
+----
+private void transform(Rectangle box) {
+    // previous code
+    
+    box.setScaleX(1.5);
+    box.setScaleY(1.5);
+}
+----
+
+image::images/scenegraph/transform_scale.jpg[title="Scale"]
+
+=== 旋转
+
+一个节点的旋转决定了渲染节点的角度。
+在2D中，唯一有意义的的旋转轴是 Z 轴。
+我们来让这个 box 旋转 30 度。
+
+[source,java]
+----
+private void transform(Rectangle box) {
+    // previous code
+    
+    box.setRotate(30);
+}
+----
+
+image::images/scenegraph/transform_rotate.jpg[title="Rotate"]
+
+== 事件处理
+
+一个事件通知某些重要的事情发生了。
+事件通常是一个事件系统中的“primitive”（又称事件总线）。
+一般地，事件系统有下面3项责任：
+
+* `fire` (触发)一个事件。
+* 通知 `listeners` （利益相关方）事件相关
+* `handle` (处理)事件
+
+事件通知机制由 JavaFX 平台自动完成。
+因此，我们将仅考虑如何触发事件，监听事件和如何处理他们。
+
+首先，让我们来创建一个自定义的事件。
+
+[source,java]
+.UserEvent.class
+----
+public class UserEvent extends Event {
+
+    public static final EventType<UserEvent> ANY = new EventType<>(Event.ANY, "ANY");
+
+    public static final EventType<UserEvent> LOGIN_SUCCEEDED = new EventType<>(ANY, "LOGIN_SUCCEEDED");
+
+    public static final EventType<UserEvent> LOGIN_FAILED = new EventType<>(ANY, "LOGIN_FAILED");
+
+    public UserEvent(EventType<? extends Event> eventType) {
+        super(eventType);
+    }
+    
+    // any other fields of importance, e.g. data, timestamp
+}
+----
+
+因为事件类型是固定的，它们通常在相同的源文件中作为事件创建。
+我们可以看到有两个具体的事件类型：`LOGIN_SUCCEEDED` 和 `LOGIN_FAILED`。
+我们可以监听此类特定类型的事件。
+
+[source,java]
+----
+Node node = ...
+node.addEventHandler(UserEvent.LOGIN_SUCCEEDED, event -> {
+    // handle event
+});
+----
+
+或者，我们可以处理任何 `UserEvent`：
+
+[source,java]
+----
+Node node = ...
+node.addEventHandler(UserEvent.ANY, event -> {
+    // handle event
+});
+----
+
+最后，我们能够构造和触发我们自己的事件：
+
+[source,java]
+----
+UserEvent event = new UserEvent(UserEvent.LOGIN_SUCCEEDED);
+Node node = ...
+node.fireEvent(event);
+----
+
+例如，当一个用户尝试去登录一个 app ，`LOGIN_SUCCEEDED` 或 `LOGIN_FAILED` 可能被触发。
+根据登录结果我们可以允许用户访问应用程序或将他锁定在应用程序之外。
+同时，相同的功能可以用一条简单的 `if` 语句实现。
+事件系统有一个重要的优势。
+在一个没有紧密耦合的应用程序中，事件系统被设计为能够在不同的模块（子系统）之间进行通信。
+像这样，当用户登录时声音可能通过音响系统播放。
+因此，可以在它自己的模块中维护所有的声音相关代码。
+然而，我们不会去深入研究架构风格。
+
+=== 输入事件
+
+按键和鼠标事件是 JavaFX 中的最常用的事件类型。
+每个 `Node` 为处理这些事件提供了所谓的“convenience methods”（方便方法）。
+比如，当一个按钮被按下时我们可以运行一些代码。
+
+[source,java]
+----
+Button button = ...
+button.setOnAction(event -> {
+    // button was pressed
+});
+----
+
+为了得到更大的灵活性，我们也可以使用下面的代码：
+
+[source,java]
+----
+Button button = ...
+button.setOnMouseEntered(e -> ...);
+button.setOnMouseExited(e -> ...);
+button.setOnMousePressed(e -> ...);
+button.setOnMouseReleased(e -> ...);
+----
+
+上面的对象 `e` 是一种 `MouseEvent` 类型并可以被查询以获得有关事件的各种信息。
+比如，`x` 和 `y` 的坐标，点击次数等等。
+最后，我们可以用按键做相同的事情：
+
+[source,java]
+----
+Button button = ...
+button.setOnKeyPressed(e -> ...);
+button.setOnKeyReleased(e -> ...);
+----
+
+这里的对象 `e` 是一种 `KeyEvent` 类型，它携带有键码的相关信息，这些信息可以被映射到键盘上的真实物理按键。
+
+== 时间安排
+
+理解 JavaFX UI 控件的创建和控件的展示之间的时间差异性是很重要的。当创建 UI 控件时——既可以直接通过 API 对象创建也可以通过 FXML 创建——你可能会缺少某些屏幕的几何值比如窗口尺寸。稍后，当屏幕显示给用户时，它就可以使用。该显示事件称为 OnShown，是分配窗口并完成最终布局计算的时间。
+
+为了证明这些，考虑以下程序，它在创建 UI 控件和显示屏幕时分别显示屏幕尺寸。下面的截图展示了正在运行的程序。当 UI 控件被创建时（new VBox(), new Scene(), primaryStage.setScene()），正如未定义的“NaN”值所证明的那样，没有可用的实际窗口高度和宽度值。
+
+image::images/scenegraph/scenegraph_startvshown.png[title="Screen Geometry Not Available Before OnShown"]
+
+然而，一旦窗口被显示出来宽度和高度值就是可用的。程序为 OnShown 事件注册了一个事件处理器并准备了相同的输出。
+
+下面是论证程序的 Java 类。
+
+[source,java]
+.StartVsShownJavaFXApp.class
+----
+public class StartVsShownJavaFXApp extends Application {
+
+    private DoubleProperty startX = new SimpleDoubleProperty();
+    private DoubleProperty startY = new SimpleDoubleProperty();
+    private DoubleProperty shownX = new SimpleDoubleProperty();
+    private DoubleProperty shownY = new SimpleDoubleProperty();
+
+    @Override
+    public void start(Stage primaryStage) throws Exception {
+
+        Label startLabel = new Label("Start Dimensions");
+        TextField startTF = new TextField();
+        startTF.textProperty().bind(
+                Bindings.format("(%.1f, %.1f)", startX, startY)
+        );
+
+        Label shownLabel = new Label("Shown Dimensions");
+        TextField shownTF = new TextField();
+        shownTF.textProperty().bind(
+                Bindings.format("(%.1f, %.1f)", shownX, shownY)
+        );
+
+        GridPane gp = new GridPane();
+        gp.add( startLabel, 0, 0 );
+        gp.add( startTF, 1, 0 );
+        gp.add( shownLabel, 0, 1 );
+        gp.add( shownTF, 1, 1 );
+        gp.setHgap(10);
+        gp.setVgap(10);
+
+        HBox hbox = new HBox(gp);
+        hbox.setAlignment(CENTER);
+
+        VBox vbox = new VBox(hbox);
+        vbox.setAlignment(CENTER);
+
+        Scene scene = new Scene( vbox, 480, 320 );
+
+        primaryStage.setScene( scene );
+
+        // before show()...I just set this to 480x320, right?
+        startX.set( primaryStage.getWidth() );
+        startY.set( primaryStage.getHeight() );
+
+        primaryStage.setOnShown( (evt) -> {
+            shownX.set( primaryStage.getWidth() );
+            shownY.set( primaryStage.getHeight() );  // all available now
+        });
+
+        primaryStage.setTitle("Start Vs. Shown");
+        primaryStage.show();
+    }
+
+    public static void main(String[] args) {
+        launch(args);
+    }
+}
+----
+
+有时，你会提前知道屏幕的尺寸，然后在 JavaFX 程序中的任何时候使用这些值。这包括 OnShown 事件之前。然而，如果你的初始化序列包含了需要这些值的逻辑，你将需要处理 OnShown 事件。一个用例可能正在使用最后保存的尺寸或基于程序输入的尺寸。