From e3a9853cd0e553a9e3fe595a8acd8201d9f4c9e9 Mon Sep 17 00:00:00 2001 From: Dmitry Sapozhnikov <11535558+o-sdn-o@users.noreply.github.com> Date: Fri, 8 Nov 2024 17:38:38 +0500 Subject: [PATCH 1/3] Fix mermaid in docs --- doc/architecture.md | 40 ++++++++++++++++++++-------------------- readme.md | 2 +- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/doc/architecture.md b/doc/architecture.md index 30d52e8dd2..e19d88870c 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -37,13 +37,13 @@ graph TB subgraph IE10[Generic Text Console 1] subgraph IE1[Input] direction LR - C1[keybd, mouse, focus\nwinsize, clipboard,\nos signals] + C1[keybd, mouse, focus
winsize, clipboard,
os signals] end subgraph OU1[Output] - TC1[scrollback\nbuffer] + TC1[scrollback
buffer] end subgraph CS1[Desktop Client 1] - VTM1[vtm\nprocess 1] + VTM1[vtm
process 1] end C1 --> CS1 TC1 --- CS1 @@ -52,13 +52,13 @@ graph TB subgraph IE20[Generic Text Console 2] subgraph IE2[Input] direction LR - C2[keybd, mouse, focus\nwinsize, clipboard,\nos signals] + C2[keybd, mouse, focus
winsize, clipboard,
os signals] end subgraph OU2[Output] - TC2[scrollback\nbuffer] + TC2[scrollback
buffer] end subgraph CS2[Desktop Client 2] - VTM2[vtm\nprocess 2] + VTM2[vtm
process 2] end C2 --> CS2 TC2 --- CS2 @@ -67,43 +67,43 @@ graph TB subgraph IE30[Generic Text Console 3] subgraph IE3[Input] direction LR - C3[keybd, mouse, focus\nwinsize, clipboard,\nos signals] + C3[keybd, mouse, focus
winsize, clipboard,
os signals] end subgraph OU3[Output] - TC3[scrollback\nbuffer] + TC3[scrollback
buffer] end subgraph CS3[DirectVT Gateway] - VTM3[vtm\nprocess 3] + VTM3[vtm
process 3] end C3 --> CS3 TC3 --- CS3 end subgraph APP0x[Standalone DirectVT-aware Application] - APP01[DirectVT App4\napp: process 9] + APP01[DirectVT App4
app: process 9] end - CS3 <-->|DirectVT I/O\nsend: Events\nrecv: Render| APP01 + CS3 <-->|DirectVT I/O
send: Events
recv: Render| APP01 subgraph NP[Connection Point] - TS["system-wide\nnamed pipe"] + TS["system-wide
named pipe"] end subgraph SS[Desktop Server] - VTMs[vtm\nprocess 0] + VTMs[vtm
process 0] subgraph SE[Desktop Session] subgraph APPx[running application windows] subgraph APP1[DirectVT Gateway] - eAPP1[DirectVT App1\napp: process 4] + eAPP1[DirectVT App1
app: process 4] end subgraph APP2[DirectVT Gateway] - eAPP2["App2 (Teletype+App2)\nvtm: process 5\napp: process 6"] + eAPP2["App2 (Teletype+App2)
vtm: process 5
app: process 6"] end subgraph APP3[DirectVT Gateway] - eAPP3["App3 (Terminal+App3)\nvtm: process 7\napp: process 8"] + eAPP3["App3 (Terminal+App3)
vtm: process 7
app: process 8"] end end subgraph APPu[connected users] - USR1["Desktop Client 1\nViewport\nTaskbar"] - USR2["Desktop Client 2\nViewport\nTaskbar"] + USR1["Desktop Client 1
Viewport
Taskbar"] + USR2["Desktop Client 2
Viewport
Taskbar"] end USR1 --->|keyboard focus| APP1 USR2 --->|keyboard focus| APP2 @@ -112,8 +112,8 @@ graph TB VTMs === SE end - CS1 <-->|DirectVT I/O\nsend: Events\nrecv: Render| TS - CS2 <-->|DirectVT I/O\nsend: Events\nrecv: Render| TS + CS1 <-->|DirectVT I/O
send: Events
recv: Render| TS + CS2 <-->|DirectVT I/O
send: Events
recv: Render| TS TS === VTMs ``` diff --git a/readme.md b/readme.md index 12b865a0d4..57a5541925 100644 --- a/readme.md +++ b/readme.md @@ -11,7 +11,7 @@ vtm is a text-based desktop environment. # Supported platforms - Windows - - Windows 8.1 or later + - Windows 8.1 and later - Unix - Linux - macOS From 066beb214efcc76ad6526f1d9c94c628e529561d Mon Sep 17 00:00:00 2001 From: Dmitry Sapozhnikov <11535558+o-sdn-o@users.noreply.github.com> Date: Fri, 8 Nov 2024 18:36:23 +0500 Subject: [PATCH 2/3] Update doc\architecture.md --- doc/architecture.md | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/doc/architecture.md b/doc/architecture.md index e19d88870c..5bd1ae22ed 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -117,8 +117,7 @@ graph TB TS === VTMs ``` -- vtm is a text-based desktop environment that comes with a single executable. -- Due to the fact that a typical desktop environment is a dynamic long-living construct of interacting processes, vtm has a number of mutually exclusive runtime modes to parallelize this functionality by launching multiple interacting vtm processes. +- Vtm is a text-based desktop environment that comes with a single executable. - Due to the fact that a typical desktop environment is a dynamic, long-lived construct of interacting processes, vtm has a number of runtime modes for running multiple vtm processes in parallel to form the environment. - Each desktop session is a vtm process running in `Desktop Server` mode. - Desktop environment users connect to an existing desktop session through an additional vtm process running in `Desktop Client` mode. @@ -131,8 +130,8 @@ graph TB - 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`. - All running applications are connected to the desktop environment using `DirectVT Gateway` windows as DirectVT endpoints. - - DirectVT-aware applications are connected directly to the environment and 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 non-DirectVT applications, 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. + - 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. - The desktop environment server can receive and execute script commands relayed from other vtm processes running on behalf of the session creator. - In the case of a vtm process with redirected standard input, all standard input is directly relayed to the desktop environment server as a script command flow. @@ -140,10 +139,10 @@ graph TB Runtime mode | TUI mode | Environment role ----------------|--------------------------|------------------ -Desktop Applet | auto detected | Desktop applet of an arbitrary type running in its own process that accepts user input and renders itself. Used to run heavy desktop objects in parallel processes to optimize desktop resource consumption. -Desktop Client | auto detected | Desktop client in its own process that forwards user input to the desktop and renders the corresponding desktop region with a taskbar overlay. +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. Desktop Server | n/a
command line only | The desktop environment core that manages connected users, runs desktop applications, routes user input, and forwards renders to desktop clients. -Desktop Monitor | n/a
command line only | Desktop monitor that outputs the desktop session log and relays script commands to the desktop server via piped redirection. +Desktop Monitor | n/a
command line only | A desktop log monitor which outputs desktop session logs and relays script commands to the desktop server via piped redirection. The runtime mode can be selected using command-line options. By default, `Desktop Client` mode will be used, with `Desktop Server` implicitly running in parallel if it is not running. @@ -160,11 +159,11 @@ DirectVT Gateway with TTY | `dtty` | CUI applications that redirect DirectVT ## TUI modes -An instance of the vtm process in `Desktop Client` or `Desktop Applet` mode can operate in one of two TUI modes, either in `ANSI/VT` mode, or in `DirectVT`(`dtvt`) mode. +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. ### DirectVT mode -In DirectVT TUI mode, the vtm process, communicating with the desktop server, multiplexes the following data channels: +In DirectVT TUI mode, vtm process multiplexes the following data channels: - Keyboard event channel - Mouse event channel - Focus event channel @@ -179,7 +178,7 @@ The DirectVT stream can be wrapped in any transport layer protocol suitable for #### Input -In ANSI/VT TUI mode, the 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 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. ##### Unix input sources @@ -225,9 +224,9 @@ In ANSI/VT TUI mode, the vtm process parses input from multiple standard sources #### Output -Console UI applications running as external processes are instantly rendered into their host `DirectVT Gateways ` windows running directly in the desktop server address space. +Console UI applications running as external processes are instantly rendered into their host `DirectVT Gateways` windows running directly in the desktop server address space. -The desktop server receives and caches the window rasters and sends the corresponding projection rendering to desktop clients at each internal timer tick. +The desktop server receives and caches window bitmaps and sends incremental changes to desktop clients every tick of an internal timer. The binary render stream received from the desktop server to output is converted by the desktop client to the format suitable for the console being used to output. The console type is detected at the desktop client startup and can be one of the following: - XTerm-compatible terminal with truecolor support @@ -241,11 +240,11 @@ The desktop client outputs the received render to the hosting console only when Term | Description --------------------|--------------- -`colored character` | A character depicted with rendition attributes such as background and foreground color. +`colored character` | A character depicted with rendition attributes such as background and foreground colors. `text console` | A cellular rectangular surface designed to display colored monospaced characters in cells. `text cell` | A text console cell containing a colored monospaced character or its fragment. `bitmap` | A rectangular block of text cells. -`canvas` | A rectangular buffer for text cells output. +`canvas` | A rectangular buffer for bitmap output. Internally the desktop is represented by the parent-child object tree with a single root object that maintains a desktop-wide configuration, a list of connected users, and a list of running windows. The root object broadcasts a fixed number of ticks every second to update the tree state and to do something else in sync. @@ -264,8 +263,8 @@ Desktop object | Description Teletype Console
`teletype` | A solid rectangular truecolor text canvas depicting a freely scrollable buffer of the text runs generated by an xterm-compatible parser from the standard output of an attached CUI application. It can be a very heavy object due to maintaining a scrollback buffer of arbitrary length. Not used directly in the desktop process's address space. Terminal Console
`terminal` | A derivative of `Teletype Console` with additional UI controls. DirectVT Gateway
`dtvt` | A lightweight truecolor text canvas depicting content received from an external dtvt-aware process. -Teletype Console dtvt‑bridge
`vtty` | A `DirectVT Gateway` hosting an external standalone `Teletype Console` applet. It is designed to run a heavy `Teletype Console` object in the external process's address space to optimize desktop resource consumption. -Terminal Console dtvt‑bridge
`term` | A `DirectVT Gateway` hosting an external standalone `Terminal Console` applet. It is designed to run a heavy `Terminal Console` object in the external process's address space to optimize desktop resource consumption. +Teletype Console dtvt‑bridge
`vtty` | A `DirectVT Gateway` hosting an external standalone `Teletype Console` applet. It is designed to run heavy `Teletype Console` objects as external processes to optimize desktop resource consumption. +Terminal Console dtvt‑bridge
`term` | A `DirectVT Gateway` hosting an external standalone `Terminal Console` applet. It is designed to run heavy `Terminal Console` objects as external processes to optimize desktop resource consumption. DirectVT Gateway with TTY
`dtty` | A derivative of `DirectVT Gateway` stacked with additional limited `Teletype Console` as a controlling terminal. It is used for CUI applications that redirect DirectVT stream to standard output and require user input via platform's TTY. Depending on activity the corresponding console became active for the user. Tiling Window Manager
`tile` | A window container with an organization of the hosting window area into mutually non-overlapping panes for nested windows. Desktop Region Marker
`site` | A transparent resizable frame for marking the specific desktop region for quick navigation across the borderless workspace. @@ -418,12 +417,10 @@ The following examples assume that vtm is installed on both the local and remote ## Standard I/O stream monitoring -vtm allows developers to visualize standard input/output streams of the running CUI applications. Launched in the `Desktop Monitor` mode, vtm will log the event stream of each terminal window with the `Logs` switch enabled. +Vtm allows developers to visualize standard input/output streams of the running CUI applications. Launched in the `Desktop Monitor` mode, vtm will log the event stream of each terminal window with the `Logs` switch enabled. Important: Avoid enabling the `Logs` switch in the terminal window hosting the `Desktop Monitor` process running, this may lead to recursive event logging of event logging with unpredictable results. -Important: Be careful with enabling the `Logs` switch when working with sensitive information, since all IO events, including keypresses, are logged in this mode. - ## Desktop taskbar customization The taskbar menu can be configured using a settings file `~/.config/vtm/settings.xml` (`%USERPROFILE%\.config\vtm\settings.xml` on Windows): @@ -457,7 +454,7 @@ The taskbar menu can be configured using a settings file `~/.config/vtm/settings ``` -The taskbar menu of the running desktop can be configured using shell piped redirection by sending script commands to the running vtm desktop: +Additionally, the taskbar menu of the running desktop can be configured using shell piped redirection by sending script commands to the running vtm desktop: ``` # Delete existing menu items echo "vtm.del()" | vtm From 0063f7e8e2ddc9531e1408c0c4ce3ec55271cc9e Mon Sep 17 00:00:00 2001 From: Dmitry Sapozhnikov <11535558+o-sdn-o@users.noreply.github.com> Date: Fri, 8 Nov 2024 19:41:35 +0500 Subject: [PATCH 3/3] Update docs --- doc/apps.md | 45 +++++++++++++++++---------------------------- doc/architecture.md | 8 ++++++++ 2 files changed, 25 insertions(+), 28 deletions(-) diff --git a/doc/apps.md b/doc/apps.md index 1b147795dc..bd7d6f69bd 100644 --- a/doc/apps.md +++ b/doc/apps.md @@ -17,41 +17,30 @@ ### Features -- UTF-8 Everywhere -- TrueColor aware -- Horizontal scrolling -- Infinite* scrollback (40k lines by default, * `< max_int32`) -- Scrollback buffer searching and matching -- Line-based/rect-block text selection: - - Ctrl: Extend selection. - - Alt/Option: Change selection mode (line/block). - - Double left click: Select a word. - - Triple left click: Select paragraph. - - Quadruple left click: Select the entire scrollback buffer or semantic block (when using OSC 133). - - Quintuple left click: Select the entire scrollback buffer. -- Widely used clipboard formats support: +- Horizontal scrolling. +- Configurable scrollback buffer size (40k lines by default, limited by `max_int32` and system RAM). +- Scrollback buffer lookup. +- Linear/box text selection: + - Extending selection with `Ctrl` key pressed. + - Changing selection mode (linear/box) with `Alt` key pressed. + - Selecting a word/paragraph/entire scrollback buffer or a semantic block (when using OSC 133) by Double/Triple/Quadruple/Quintuple left clicking. +- Multiple clipboard formats support: - Plain text - RTF - HTML - ANSI/VT - Protected (Windows only: `ExcludeClipboardContentFromMonitorProcessing`, `CanIncludeInClipboardHistory`, `CanUploadToCloudClipboard`) -- [VT-100 terminal emulation](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html) compatible (pass vttest 1 and 2 sections) - Built-in Windows Console API server: - - Legacy Win32 Console API support - - No Windows Console Host (conhost.exe) dependency - - Fullduplex pass-through VT input/output - - OEM/National, UTF-8 and UTF-16 encoding, even in cmd.exe - - Enforced ENABLE_WINDOW_INPUT mode + - Legacy Win32 Console API support. + - No Windows Console Host (conhost.exe) dependency. + - Fullduplex pass-through VT input/output. + - OEM/National, UTF-8 and UTF-16 encoding support. + - Enforced ENABLE_WINDOW_INPUT mode. Note: In fact it is a viewport resize event reporting. Viewport dimensions is always equal to the win32 console buffer dimensions. - - Enforced ENABLE_PROCESSED_OUTPUT and ENABLE_VIRTUAL_TERMINAL_PROCESSING modes - - Disabled ENABLE_QUICK_EDIT_MODE mode - - Per process instance (not per process name) cmd.exe input history, aka "line input"/"cooked read" - - Disabled DOSKEY functionality (cmd.exe's F7 input history popups too) - Note: Sharing the input history as well as a bunch of command aliases among processes (which could have different elevation levels) is a huge security threat. So DOSKEY functionality is absolutely incompatible with any sort of sudo-like commands/applications. -- Outside terminal viewport mouse tracking (See #62 for details) -- Stdin/stdout parser log on demand -- Configurable at startup via `settings.xml` -- Configurable in runtime using VT-sequences + - Enforced ENABLE_PROCESSED_OUTPUT and ENABLE_VIRTUAL_TERMINAL_PROCESSING modes. + - Disabled ENABLE_QUICK_EDIT_MODE mode. + - Per process (not per process name) Windows Command Prompt (cmd.exe) input history, aka "line input"/"cooked read". +- Stdin/stdout logging. ### Custom SGR attributes diff --git a/doc/architecture.md b/doc/architecture.md index 5bd1ae22ed..588a81da6b 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -475,3 +475,11 @@ echo "vtm.selected(Term)" | vtm # Run window with terminals echo "vtm.run(id=Tile)" | vtm ``` + +# Desktop Live Panel + +- [Desktop Live Panel](panel.md) + +# Desktop objects and built-in applications + +- [Desktop objects and built-in applications](apps.md) \ No newline at end of file