Update docs

Author: jvalkeal

spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc

@@ -4,4 +4,14 @@
 
 ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs]
 
-tbd
+Views have their own default bindings which can be changed.
+
+You can subscribe into all key events:
+
+[source, java, indent=0]
+----
+include::{snippets}/KeyHandlingSnippets.java[tag=sample]
+----
+
+`KeyEvent` is a record containing info about a binding coming out
+from a terminal.

spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc

@@ -4,4 +4,12 @@
 
 ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs]
 
-tbd
+You can subscribe into all mouse events:
+
+[source, java, indent=0]
+----
+include::{snippets}/MouseHandlingSnippets.java[tag=sample]
+----
+
+`MouseEvent` is a record wrapping _x_ and _Y_ coordinates and
+`org.jline.terminal.MouseEvent` from JLine library.

spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc

@@ -7,13 +7,8 @@ ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/she
 Lets start with a simple app which prints "hello world" in a view.
 [source, java, indent=0]
 ----
-include::{snippets}/TerminalUiSnippets.java[tag=snippet1]
+include::{snippets}/TerminalUiSnippets.java[tag=introsample]
 ----
 
 There is not much to see here other than `TerminalUI` is a class handling
 all logic aroung views and uses `View` as it's root view.
-
-[source, java, indent=0]
-----
-include::{snippets}/TerminalUiSnippets.java[tag=snippet2]
-----

spring-shell-docs/modules/ROOT/pages/tui/intro/terminalui.adoc

@@ -4,7 +4,33 @@
 ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs]
 
 `TerminalUI` is a main implementation to drive ui execution logic.
-Running `TerminalUI` execution loop is a blocking operation.
+
+== Create TerminalUI
+You can build `TerminalUI` manually but recommended way is to use `TerminalUIBuilder`
+build is autoconfigured for you and will set needed services.
+
+[source, java, indent=0]
+----
+include::{snippets}/TerminalUiSnippets.java[tag=uibuilderautowire]
+----
+
+== Configuring Views
+`TerminalUI` has a helper method _configure(View)_ which can be used to set
+needed integrations into _eventloop_ and other services.
+
+[source, java, indent=0]
+----
+include::{snippets}/TerminalUiSnippets.java[tag=configureview]
+----
+
+== Running UI Loop
+Running `TerminalUI` execution loop is a blocking operation. You're going to need
+a way to exit from a loop, for example <<Exiting App>>.
+
+[source, java, indent=0]
+----
+include::{snippets}/TerminalUiSnippets.java[tag=uirun]
+----
 
 == Exiting App
 
@@ -13,5 +39,5 @@ events and request _interrupt_.
 
 [source, java, indent=0]
 ----
-include::{snippets}/TerminalUiSnippets.java[tag=snippet3]
+include::{snippets}/TerminalUiSnippets.java[tag=exitingfromloop]
 ----

spring-shell-docs/src/test/java/org/springframework/shell/docs/KeyHandlingSnippets.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2023 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.shell.docs;
+
+import org.springframework.shell.component.view.event.EventLoop;
+import org.springframework.shell.component.view.event.KeyEvent;
+
+class KeyHandlingSnippets {
+
+	EventLoop eventLoop;
+
+	void dump1() {
+		// tag::sample[]
+		eventLoop.keyEvents().subscribe((KeyEvent event) -> {
+			// do something with key event
+		});
+		// end::sample[]
+	}
+
+}

spring-shell-docs/src/test/java/org/springframework/shell/docs/MouseHandlingSnippets.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2023 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.shell.docs;
+
+import org.springframework.shell.component.view.event.EventLoop;
+import org.springframework.shell.component.view.event.MouseEvent;
+
+class MouseHandlingSnippets {
+
+	EventLoop eventLoop;
+
+	void dump1() {
+		// tag::sample[]
+		eventLoop.mouseEvents().subscribe((MouseEvent event) -> {
+			// do something with mouse event
+		});
+		// end::sample[]
+	}
+
+}

spring-shell-docs/src/test/java/org/springframework/shell/docs/TerminalUiSnippets.java

@@ -20,6 +20,7 @@
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.shell.component.message.ShellMessageBuilder;
 import org.springframework.shell.component.view.TerminalUI;
+import org.springframework.shell.component.view.TerminalUIBuilder;
 import org.springframework.shell.component.view.control.BoxView;
 import org.springframework.shell.component.view.event.EventLoop;
 import org.springframework.shell.component.view.event.KeyEvent.Key;
@@ -28,14 +29,14 @@
 
 class TerminalUiSnippets {
 
-	class Sample1 {
+	class SampleIntro {
 
-		// tag::snippet1[]
+		// tag::introsample[]
 		@Autowired
-		Terminal terminal;
+		TerminalUIBuilder builder;
 
 		void sample() {
-			TerminalUI ui = new TerminalUI(terminal);
+			TerminalUI ui = builder.build();
 			BoxView view = new BoxView();
 			view.setDrawFunction((screen, rect) -> {
 				screen.writerBuilder()
@@ -46,33 +47,12 @@ void sample() {
 			ui.setRoot(view, true);
 			ui.run();
 		}
-		// end::snippet1[]
-	}
-
-	class Sample2 {
-
-		// tag::snippet2[]
-		@Autowired
-		Terminal terminal;
-
-		void sample() {
-			TerminalUI ui = new TerminalUI(terminal);
-			BoxView view = new BoxView();
-			view.setDrawFunction((screen, rect) -> {
-				screen.writerBuilder()
-					.build()
-					.text("Hello World", rect, HorizontalAlign.CENTER, VerticalAlign.CENTER);
-				return rect;
-			});
-			ui.setRoot(view, false);
-			ui.run();
-		}
-		// end::snippet2[]
+		// end::introsample[]
 	}
 
 	class Sample3 {
 
-		// tag::snippet3[]
+		// tag::exitingfromloop[]
 		@Autowired
 		Terminal terminal;
 
@@ -89,7 +69,44 @@ void sample() {
 				});
 			ui.run();
 		}
-		// end::snippet3[]
+		// end::exitingfromloop[]
+	}
+
+	@SuppressWarnings("unused")
+	class SampleUiAutowire {
+
+		// tag::uibuilderautowire[]
+		@Autowired
+		TerminalUIBuilder builder;
+
+		void sample() {
+			TerminalUI ui = builder.build();
+			// do something with ui
+		}
+		// end::uibuilderautowire[]
+	}
+
+	class SampleConfigureView {
+
+		// tag::configureview[]
+		TerminalUI ui;
+
+		void sample() {
+			BoxView view = new BoxView();
+			ui.configure(view);
+		}
+		// end::configureview[]
+	}
+
+	class SampleUiLoop {
+
+		// tag::uirun[]
+		TerminalUI ui;
+
+		void sample() {
+			ui.run();
+		}
+		// end::uirun[]
 	}
 
 }