Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move all key bindings into a single subsection #677

Merged
merged 12 commits into from
Nov 10, 2024
87 changes: 68 additions & 19 deletions doc/architecture.md
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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:
Expand All @@ -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`.
Expand Down Expand Up @@ -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"/>

Expand Down
Loading