Merge pull request #677 from o-sdn-o/gui-bridge

Move all key bindings into a single subsection
directvt · Nov 10, 2024 · 0641dd5 · 0641dd5
2 parents 7594c9e + 0e4ba1c
commit 0641dd5
Show file tree

Hide file tree

Showing 13 changed files with 387 additions and 312 deletions.
diff --git a/doc/architecture.md b/doc/architecture.md
@@ -1,9 +1,10 @@
 # Text-based Desktop Environment Architecture
 
+- [UI concept](#ui-concept)
 - [Process model](#process-model)
 - [Runtime modes](#runtimemodes)
 - [Desktop applets](#desktopapplets)
-- [TUI modes](#tui-modes)
+- [IO modes](#io-modes)
   - [DirectVT mode](#directvt-mode)
   - [ANSI/VT mode](#ansivt-mode)
     - [Input](#input)
@@ -20,16 +21,64 @@
     - [Run a CUI application inside the Terminal Console](#run-a-cui-application-inside-the-terminal-console)
   - [Remote access](#remote-access)
     - [Run a standalone CUI application remotely over SSH](#run-a-standalone-cui-application-remotely-over-ssh)
-    - [Run remote vtm desktop in DirectVT mode over SSH](#run-remote-vtm-desktop-in-directvt-mode-over-ssh)
-    - [Run remote vtm desktop in ANSI/VT mode over SSH](#run-remote-vtm-desktop-in-ansivt-mode-over-ssh)
-    - [Run remote vtm desktop in DirectVT mode using netcat](#run-remote-vtm-desktop-in-directvt-mode-using-netcat-posix-only-unencrypted-for-private-use-only)
-    - [Run remote vtm desktop in DirectVT mode using inetd + ncat](#run-remote-vtm-desktop-in-directvt-mode-using-inetd--ncat-posix-only-unencrypted-for-private-use-only)
+    - [Run remote vtm desktop in DirectVT IO mode over SSH](#run-remote-vtm-desktop-in-directvt-io-mode-over-ssh)
+    - [Run remote vtm desktop in ANSI/VT IO mode over SSH](#run-remote-vtm-desktop-in-ansivt-io-mode-over-ssh)
+    - [Run remote vtm desktop in DirectVT IO mode using netcat](#run-remote-vtm-desktop-in-directvt-io-mode-using-netcat-posix-only-unencrypted-for-private-use-only)
+    - [Run remote vtm desktop in DirectVT IO mode using inetd + ncat](#run-remote-vtm-desktop-in-directvt-io-mode-using-inetd--ncat-posix-only-unencrypted-for-private-use-only)
     - [Local standard I/O redirection using socat](#local-standard-io-redirection-using-socat-posix-only)
   - [Standard I/O stream monitoring](#standard-io-stream-monitoring)
 - [Desktop taskbar customization](#desktop-taskbar-customization)
 - [Desktop Live Panel](panel.md)
 - [Desktop objects and built-in applications](apps.md)
 
+## UI concept
+
+```mermaid
+graph TB
+  subgraph GUI[Native GUI Window]
+    subgraph TUI[TUI Matrix]
+      subgraph DESK[Desktop UI]
+        direction LR
+        subgraph APP1[Desktop Application]
+          direction LR
+          App1[Application UI]
+        end
+        subgraph APP2[Desktop Application]
+          direction LR
+          App2[Application UI]
+        end
+      end
+    end
+  end
+  subgraph GUI2[Generic Text Console]
+    subgraph TUI2[TUI Matrix]
+      subgraph DESK2[Desktop UI]
+        direction LR
+        subgraph APP21[Desktop Application]
+          direction LR
+          App21[Application UI]
+        end
+        subgraph APP22[Desktop Application]
+          direction LR
+          App22[Application UI]
+        end
+      end
+    end
+  end
+  subgraph GUI3[Native GUI Window]
+    subgraph TUI3[TUI Matrix]
+      subgraph APP33[Standalone Application]
+        direction LR
+        App33[Application UI]
+      end
+    end
+  end
+```
+
+In vtm, the entire user interface is represented by a mosaic of identically sized text cells, forming a TUI matrix. The resulting TUI matrix is then rendered either into its own GUI window or into a compatible text console. Currently, rendering into a native GUI window is only available on the Windows platform; on Unix platforms, a terminal emulator is required.
+
+The desktop and applications in vtm are completely abstracted from the graphical interface and do not depend on it.
+
 ## Process model
 
 ```mermaid
@@ -128,7 +177,7 @@ graph TB
 - Multiple connected users can share a focused application, while each user can have multiple applications focused.
 - Users can disconnect from the session and reconnect later.
 - Sessions with different ids can coexist independently.
-- To maximize rendering efficiency and minimize cross-platform issues, along with character-oriented xterm-compatible TUI mode called `ANSI/VT`, vtm supports an additional message-based binary TUI mode called `DirectVT`.
+- To maximize rendering efficiency and minimize cross-platform issues, along with character-oriented xterm-compatible IO mode called `ANSI/VT`, vtm supports an additional message-based binary IO mode called `DirectVT`.
 - All running applications are connected to the desktop environment using `DirectVT Gateway` windows as DirectVT endpoints.
   - A DirectVT-aware application directly connected to the environment can seamlessly send and receive the entire set of desktop events, as well as render themselves in binary form, avoiding expensive ANSI/VT parsing.
   - To run a non-DirectVT application, an additional vtm host process is launched in `Desktop Applet` mode with the `Teletype Console` or `Terminal Console` applet as a DirectVT bridge to the desktop environment.
@@ -137,7 +186,7 @@ graph TB
 
 ### Runtime modes
 
-Runtime mode    | TUI mode                 | Environment role
+Runtime mode    | IO mode                  | Environment role
 ----------------|--------------------------|------------------
 Desktop Applet  | auto detected            | A desktop applet of an arbitrary type running in its own process that accepts user input and renders itself. Used to place a heavy (complex) desktop object in a separate process in order to optimize desktop resource consumption.
 Desktop Client  | auto detected            | A desktop client running in its own process that forwards user input to the desktop and renders the corresponding desktop region with a taskbar overlay.
@@ -157,13 +206,13 @@ Terminal Console           | `term` | CUI applications.
 DirectVT Gateway           | `dtvt` | DirectVT-aware applications.
 DirectVT Gateway with TTY  | `dtty` | CUI applications that redirect DirectVT flow to standard IO streams and require user input via platform's TTY.
 
-## TUI modes
+## IO modes
 
-A vtm process instance running in `Desktop Client` or `Desktop Applet` mode can operate in one of two TUI modes: either `ANSI/VT` mode or `DirectVT`(`dtvt`) mode.
+A vtm process instance running in `Desktop Client` or `Desktop Applet` mode can operate in one of two IO modes: either `ANSI/VT` mode or `DirectVT`(`dtvt`) mode.
 
 ### DirectVT mode
 
-In DirectVT TUI mode, vtm process multiplexes the following data channels:
+In DirectVT IO mode, vtm process multiplexes the following data channels:
 - Keyboard event channel
 - Mouse event channel
 - Focus event channel
@@ -178,7 +227,7 @@ The DirectVT stream can be wrapped in any transport layer protocol suitable for
 
 #### Input
 
-In ANSI/VT TUI mode, vtm process parses input from multiple standard sources, and forwards it to the desktop server using the DirectVT transport. The set of input sources varies by platform.
+In ANSI/VT IO mode, vtm process parses input from multiple standard sources, and forwards it to the desktop server using the DirectVT transport. The set of input sources varies by platform.
 
 ##### Unix input sources
 
@@ -308,7 +357,7 @@ Do not confuse the `Desktop Applet` names with the desktop object names, even th
 
 In general, the local and remote platforms may be different.
 
-When the DirectVT mode is used, all keyboard, mouse and other input events are transmitted between hosts in a binary endianness-aware form.
+When the DirectVT IO mode is used, all keyboard, mouse and other input events are transmitted between hosts in a binary endianness-aware form.
 
 The following examples assume that vtm is installed on both the local and remote sides.
 
@@ -328,7 +377,7 @@ The following examples assume that vtm is installed on both the local and remote
     vtm ssh user@server vtm </path/to/console/app...>
     ```
 
-### Run remote vtm desktop in DirectVT mode over SSH
+### Run remote vtm desktop in DirectVT IO mode over SSH
 
 - Remote side
     - Run SSH-server if it is not running.
@@ -345,7 +394,7 @@ The following examples assume that vtm is installed on both the local and remote
     # The `-r dtty` option is auto added if the first command-line argument starts with `ssh` keyword.
     ```
 
-### Run remote vtm desktop in ANSI/VT mode over SSH
+### Run remote vtm desktop in ANSI/VT IO mode over SSH
 
 - Remote side
     - Run SSH-server if it is not running.
@@ -361,7 +410,7 @@ The following examples assume that vtm is installed on both the local and remote
     # The ssh's `ssh -t ...` option is required to allocate TTY on remote host.
     ```
 
-### Run remote vtm desktop in DirectVT mode using `netcat` (POSIX only, unencrypted, for private use only)
+### Run remote vtm desktop in DirectVT IO mode using `netcat` (POSIX only, unencrypted, for private use only)
 
 - Remote side
     - Run command:
@@ -379,7 +428,7 @@ The following examples assume that vtm is installed on both the local and remote
     # Note: Make sure `ncat` is installed.
     ```
 
-### Run remote vtm desktop in DirectVT mode using `inetd + ncat` (POSIX only, unencrypted, for private use only)
+### Run remote vtm desktop in DirectVT IO mode using `inetd + ncat` (POSIX only, unencrypted, for private use only)
 
 - Remote side
     - Install `inetd`.
@@ -431,9 +480,9 @@ The taskbar menu can be configured using a settings file `~/.config/vtm/settings
             <!-- <item*/> --> <!-- Clear default item list -->
             <item splitter label="Remote Access"/>
 
-            <item id="Run remote vtm desktop in DirectVT mode over SSH" type=dtty cmd="ssh user@server vtm"/>
-            <item id="Run console app in remote terminal over SSH"      type=dtty cmd="ssh user@server vtm -r term </path/to/console/app...>"/>
-            <item id="Run console app remotely over SSH w/o extra UI"   type=dtty cmd="ssh user@server vtm </path/to/console/app...>"/>
+            <item id="Run remote vtm desktop in DirectVT IO mode over SSH" type=dtty cmd="ssh user@server vtm"/>
+            <item id="Run console app in remote terminal over SSH"         type=dtty cmd="ssh user@server vtm -r term </path/to/console/app...>"/>
+            <item id="Run console app remotely over SSH w/o extra UI"      type=dtty cmd="ssh user@server vtm </path/to/console/app...>"/>
 
             <item splitter label="Another Examples"/>