Update modal docs

- Relates #825

spring-shell-core/src/main/java/org/springframework/shell/component/view/control/ViewService.java

@@ -24,9 +24,25 @@ import org.springframework.lang.Nullable;
  */
 public interface ViewService {
 
+	/**
+	 * Gets a current modal view.
+	 *
+	 * @return current modal view
+	 */
+	@Nullable
 	View getModal();
 
-	void setModal(View view);
+	/**
+	 * Sets a new modal view. Setting modal to {@code null} clears existing modal.
+	 *
+	 * @param view a view to use as modal
+	 */
+	void setModal(@Nullable View view);
 
+	/**
+	 * Sets a view to be focused. Setting focus to {@code null} clears focused view.
+	 *
+	 * @param view a view to be focused
+	 */
 	void setFocus(@Nullable View view);
 }

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

@@ -41,3 +41,16 @@ events and request _interrupt_.
 ----
 include::{snippets}/TerminalUiSnippets.java[tag=exitingfromloop]
 ----
+
+== Modal View
+
+`TerminalUI` supports having one active modal view. Modal view is placed
+on top of all other views and takes all input events.
+
+[source, java, indent=0]
+----
+include::{snippets}/TerminalUiSnippets.java[tag=uimodal]
+----
+
+NOTE: As views should not directly know anything about `TerminalUi` and
+interface `ViewService` exposes modal related functions.

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

@@ -22,6 +22,7 @@ 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.control.DialogView;
 import org.springframework.shell.component.view.event.EventLoop;
 import org.springframework.shell.component.view.event.KeyEvent.Key;
 import org.springframework.shell.geom.HorizontalAlign;
@@ -111,4 +112,19 @@ class TerminalUiSnippets {
 		// end::uirun[]
 	}
 
+	class SampleUiModal {
+
+		// tag::uimodal[]
+		TerminalUI ui;
+
+		void sample() {
+			DialogView dialog = new DialogView();
+			// set modal
+			ui.setModal(dialog);
+			// clear modal
+			ui.setModal(null);
+		}
+		// end::uimodal[]
+	}
+
 }