From db3f67784a4d79b43c8df2d4682d3ae5b9e97ff8 Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Sat, 28 Oct 2023 09:16:42 +0100 Subject: [PATCH] Update docs --- .../modules/ROOT/pages/tui/events/key.adoc | 12 ++- .../modules/ROOT/pages/tui/events/mouse.adoc | 10 ++- .../modules/ROOT/pages/tui/intro/index.adoc | 7 +- .../ROOT/pages/tui/intro/terminalui.adoc | 30 +++++++- .../shell/docs/KeyHandlingSnippets.java | 33 +++++++++ .../shell/docs/MouseHandlingSnippets.java | 33 +++++++++ .../shell/docs/TerminalUiSnippets.java | 73 ++++++++++++------- 7 files changed, 160 insertions(+), 38 deletions(-) create mode 100644 spring-shell-docs/src/test/java/org/springframework/shell/docs/KeyHandlingSnippets.java create mode 100644 spring-shell-docs/src/test/java/org/springframework/shell/docs/MouseHandlingSnippets.java diff --git a/spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc b/spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc index 7c1285a2..87e42d85 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc +++ b/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. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc b/spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc index 69eb4e60..b9d2ea4f 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc +++ b/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. diff --git a/spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc b/spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc index 23309433..37d0d3f9 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc +++ b/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] ----- diff --git a/spring-shell-docs/modules/ROOT/pages/tui/intro/terminalui.adoc b/spring-shell-docs/modules/ROOT/pages/tui/intro/terminalui.adoc index c80f56d9..9fa3a46a 100644 --- a/spring-shell-docs/modules/ROOT/pages/tui/intro/terminalui.adoc +++ b/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 <>. + +[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] ---- diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/KeyHandlingSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/KeyHandlingSnippets.java new file mode 100644 index 00000000..8d557fc3 --- /dev/null +++ b/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[] + } + +} diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/MouseHandlingSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/MouseHandlingSnippets.java new file mode 100644 index 00000000..b15e9ccf --- /dev/null +++ b/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[] + } + +} diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/TerminalUiSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/TerminalUiSnippets.java index 1c40bd4e..78dbeb54 100644 --- a/spring-shell-docs/src/test/java/org/springframework/shell/docs/TerminalUiSnippets.java +++ b/spring-shell-docs/src/test/java/org/springframework/shell/docs/TerminalUiSnippets.java @@ -20,6 +20,7 @@ import org.jline.terminal.Terminal; 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 @@ import org.springframework.shell.geom.VerticalAlign; 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 @@ class TerminalUiSnippets { 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 @@ class TerminalUiSnippets { }); 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[] } }