TVDesk - Terminal Desktop Environment

A terminal-based desktop environment built with Turbo Vision, providing a classic text-mode interface with modern features.

Features

• Application Launcher: Configurable menu to launch your favorite terminal applications
• Terminal Emulator: Full-featured terminal with libvterm (ANSI colors, cursor, etc.)
• Configuration Editor: GUI tool to manage applications and settings
• Theme Support: Customizable YAML-based themes with built-in dark mode
• Theme Picker: Interactive dialog to select and apply themes
• Classic UI: Retro Turbo Vision aesthetic with windows, menus, and dialogs

Screenshots

Terminal windows running man man and Midnight Commander side by side:

Application launcher / configuration editor:

Building

Requirements

• C++14 compatible compiler (GCC/Clang)
• CMake 3.13 or later
• ncursesw library
• libgpm (optional, for mouse support)
• Perl (for building libvterm)

Build Instructions

cmake . -B ./build -DCMAKE_BUILD_TYPE=Release
cmake --build ./build

The executable will be created at ./build/tvdesk.

Note: The build process includes libvterm and tvterm-core for proper terminal emulation.

Running

./build/tvdesk

Usage

Keyboard Shortcuts

• Alt+A: Open application launcher
• Alt+N: Open new terminal window
• Alt+C: Open configuration editor
• F9: Theme selector
• Alt+X: Exit application

Application Launcher

Press Alt+A or select "Desktop → Applications" from the menu to open the application launcher. Select an application and press Enter to launch it.

Configuration Editor

Press Alt+C or select "Tools → Configuration" to:

• Add new applications
• Edit existing applications
• Remove applications
• Configure application properties (name, command, category, description)

Terminal

Press Alt+N or select "Desktop → New Terminal" to open a terminal window. The terminal provides full shell access with proper ANSI terminal emulation powered by libvterm:

• Full ANSI color support
• Proper cursor handling
• Scrollback buffer
• Mouse support (if available)
• UTF-8 support

The terminal implementation is based on tvterm, ensuring compatibility with most terminal applications.

Configuration

Applications are stored in config/apps.json. You can edit this file manually or use the built-in configuration editor.

Example application entry:

{
  "name": "Text Editor",
  "command": "nano",
  "category": "Editors",
  "shortcut": "",
  "description": "Simple text editor"
}

Themes

TVDesk features a flexible YAML-based theme system that allows you to customize the entire color scheme. Themes are stored in config/themes/ as YAML files.

Built-in Themes

• Classic: Traditional Turbo Vision colors (blue/gray DOS aesthetic)
• Dark: Modern dark theme with high contrast (white on black)
• Blue: Blue color scheme

Using the Theme Picker

1. Press F9 or select "Tools → Theme Selector" from the menu
2. Choose a theme from the list
3. Click OK to save your selection
4. Restart TVDesk to see the new theme applied

Creating Custom Themes

You can create your own themes by adding YAML files to the config/themes/ directory. See config/themes/README.md for detailed documentation on the theme file format.

Example theme file:

name: "My Theme"
description: "Custom color scheme"

palette:
  - 0x71  # Entry 0: Desktop background (white on blue)
  - 0x70  # Entry 1: Desktop text (white on dark gray)
  # ... 62 more entries (64 total required)

Each palette entry is a hex byte where:

• High nibble (first digit) = foreground color
• Low nibble (second digit) = background color
• Colors: 0=Black, 1=Blue, 2=Green, 3=Cyan, 4=Red, 5=Magenta, 6=Brown, 7=LightGray, 8=DarkGray, 9=LightBlue, A=LightGreen, B=LightCyan, C=LightRed, D=LightMagenta, E=Yellow, F=White

License

This project uses the Turbo Vision library by magiblot (https://github.com/magiblot/tvision).

Development

Project Structure

tvdesk/
├── src/           - Source files
├── include/       - Header files
├── config/        - Configuration files
├── tvision/       - Turbo Vision library
└── build/         - Build output

Adding Applications

Applications can be added through the Configuration Editor or by editing config/apps.json directly.

Troubleshooting

If you encounter issues:

1. Ensure ncursesw is installed: sudo apt-get install libncursesw5-dev
2. For mouse support, install gpm: sudo apt-get install libgpm-dev
3. Make sure your terminal supports UTF-8

Enjoy your classic terminal desktop experience!

Technical Architecture

Terminal Emulation

TVDesk uses a professional-grade terminal emulation stack:

• libvterm: Industry-standard terminal emulator library (used by Neovim, Emacs)
• tvterm-core: Turbo Vision integration layer
• Full VT100/xterm compatibility: All escape sequences supported
• Efficient rendering: Damage-based updates, minimal redrawing

This provides the same terminal quality you'd expect from modern terminal emulators like xterm or gnome-terminal.

Components

TVDesk Application
    ├── Desktop Framework (TApplication, TMenuBar, TStatusLine)
    ├── Application Launcher (TDialog, TListBox)
    ├── Configuration Editor (TDialog, TInputLine)
    ├── Theme Manager (TPalette system)
    └── Terminal Windows (tvterm::BasicTerminalWindow)
            ├── Terminal View (rendering)
            ├── Terminal Controller (I/O handling)
            └── VTerm Emulator (escape sequence parsing)

Dependencies

Build-time

• CMake 3.13+
• C++14 compiler
• Perl (for libvterm code generation)

Runtime

• ncursesw
• libgpm (optional, for mouse)
• System shell (bash, zsh, etc.)

Libraries (bundled)

• Turbo Vision (submodule/clone)
• libvterm (cloned)
• tvterm-core (copied sources)

Application Configuration

TVDesk stores its application configuration in a human-readable JSON file at:

~/.tvdesk/apps.json

Format

The configuration file contains:

• applications: Array of application entries
• settings: Global settings

Application Entry Fields

Each application has the following fields:

• name: Display name shown in the application launcher
• command: Command to execute (can include arguments)
• category: Category for organization (e.g., "Editors", "System", "Utilities")
• shortcut: Keyboard shortcut (currently unused)
• description: Brief description of the application
• icon: Unicode emoji icon (optional)

Example Configuration

{
  "applications": [
    {
      "name": "Text Editor (nano)",
      "command": "nano",
      "category": "Editors",
      "shortcut": "",
      "description": "Simple text editor",
      "icon": "📝"
    },
    {
      "name": "System Monitor",
      "command": "htop",
      "category": "System",
      "shortcut": "",
      "description": "Interactive process viewer",
      "icon": "📊"
    }
  ],
  "settings": {
    "theme": "Classic",
    "showClock": true,
    "show24Hour": true,
    "shell": "/bin/bash"
  }
}

Editing Applications

You can edit applications in two ways:

1. Through the UI: Press Alt+C to open the Configuration Editor
2. Manual editing: Edit ~/.tvdesk/apps.json with any text editor

Changes are automatically saved when using the Configuration Editor. If manually editing the file, restart TVDesk to load the changes.

Default Applications

On first run, TVDesk creates default applications. These are stored in ~/.tvdesk/apps.json after the first modification through the UI.