DOCSEARCHbyAlgolia
Submit Docs

pyTermTk Documentation

repository·main·Indexed 21 days ago

https://github.com/ceccopierangiolieugenio/pytermtk

A Python-based Text User Interface (TUI) toolkit for creating rich, widget-based terminal applications. Inspired by GUI frameworks like Qt and GTK, it features a layout engine, True Color support, and a comprehensive widget system. The ecosystem includes several applications: ttkDesigner (a WYSIWYG TUI designer), dumbPaintTool (an ASCII/ANSI/UTF-8 art editor), tlogg (a text-based log explorer), and ttkode (a text-based code editor).

Tokens
47.1K
Snippets
174
Records
217
Agent score
75%

What's inside pyTermTk

  1. Introduction to pyTermTk

    main

    pyTermTk is a Text-based user interface (TUI) library for Python. It is designed with an API inspired by a mix of Qt5, GTK, and tkinter, providing a structured way to build terminal interfaces.

    Key resources for users:

    • Features: Detailed information on library capabilities and widget sets.
    • Installation & Quickstart: Guides on how to install, use, and deliver pyTermTk applications.
    • Tutorials: Step-by-step guides ranging from 'Hello World' to complex layouts, signal/slot patterns, and logging.
    • Debugging: Documentation on how to debug and profile pyTermTk applications.

  2. What is ttkDesigner

    main

    ttkDesigner is a WYSIWYG (What-You-See-Is-What-You-Get) tool for designing and building Text-based User Interfaces (TUIs) using pyTermTk Widgets.

    Key capabilities include:

    • Visual Composition: Compose and customize windows or dialogs visually.
    • Interactive Testing: Test your UI designs interactively within the tool.
    • Code Integration: Widgets and forms created in ttkDesigner integrate with pyTermTk's signals and slots mechanism, allowing you to assign programmatic behavior to graphical elements.
    • Dynamic Properties: All properties configured in the designer can be modified dynamically via code at runtime.

  3. Overview of dumbPaintTool features

    main

    dumbPaintTool is a terminal-based art editor (often described as "Terminal ASCII Photoshop") designed for creating ASCII, ANSI, and UTF-8 art. It is built using the pyTermTk library.

    Key Capabilities:

    • Terminal Native: Runs directly in your terminal via SSH, Telnet, or Serial.
    • Glyphs & Tools: Supports a wide variety of UTF-8 glyphs and specialized drawing tools.
    • Layer System: Includes support for layers, including intelligent and "dumb" transparent layers.
    • Import/Export: Supports image/picture imports with configurable ASCII rasterizers and exports to ANSI/ASCII formats.
    • Workflow: Features unlimited Undo/Redo and copy/paste capabilities from the terminal or web app.
    • Web Version: The web version supports dragging files directly to open them.

  4. Overview of pyTermTk features

    main

    pyTermTk (Python Terminal Toolkit) is a text-based user interface (TUI) library inspired by Qt5, GTK, and tkinter.

    Key Features:

    • Self-contained: Requires no external libraries (except for optional features like Pygments or Pillow).
    • Cross-compatible: Works on Linux, macOS, MS Windows, and even HTML5 (via Pyodide/xterm.js).
    • Widget System: Includes basic widgets (Button, Label, checkbox, etc.) and specialized widgets (Windows, Frames, Tables, etc.).
    • Layout Engine: Uses a Qt-like layout system for arranging widgets.
    • Rich Rendering: Supports True Color and various Unicode character sizes (Full/Half/Zero-sized).

    Requirements:

    • Python 3.10 or higher.

  5. Core features of pyTermTk

    main

    pyTermTk is a self-contained TUI (Text-based User Interface) development library that does not require external libraries like curses. It provides a wide range of tools for building terminal applications, including:

    • Cross-platform compatibility: Works on Linux, MacOS, MS Windows, and HTML5.
    • Widget System: Includes basic widgets (Button, Label, checkbox, etc.), specialized widgets (Windows, Frames, Tables), and pickers.
    • Layout System: A QT-like layout system for arranging widgets in the terminal.
    • Advanced Rendering: Supports True Color, drawing primitives, and an image rasteriser.
    • Unicode Support: Utilizes Full, Half, and Zero-sized Unicode characters.
    • Interaction: Supports Input, Mouse, Paste events, Drag and Drop, and Clipboard support.

  6. Supported platforms for pyTermTk

    main

    pyTermTk is designed for cross-platform compatibility, allowing terminal-based applications to run across various environments including native operating systems and web browsers. Supported platforms include:

    • Linux: Supports standard pty, GPM integration, and serial consoles.
    • Windows: Native support available.
    • MacOS: Native support available.
    • HTML5: Can be run directly in a web browser via an HTML5 sandbox.

  7. Overview of pyTermTk modules

    main

    The pyTermTk API is organized into several key modules that handle different aspects of TUI development:

    • TTkCore: Contains the core classes used by all other modules.
    • TTkGui: Provides the themes collection for styling your UI.
    • TTkWidgets: Contains classes for creating classic desktop-style user interfaces.
    • TTkTestWidgets: Provides classes with basic testing widgets for development and verification.

  8. Understand the input processing architecture in pyTermTk

    main

    pyTermTk handles user input through a driver-to-input-component pipeline. Depending on the version, this architecture is either single-threaded or multi-threaded.

    Single-threaded Architecture (v0.36.0-a and earlier)

    In this mode, input reading and processing happen sequentially:

    1. TTkInputDriver.read() reads from stdin and yields an inString.
    2. TTkInput.key_process(inString) processes the string.
    3. inputEvent.emit(kevt, mevt) triggers _processInput.
    4. pasteEvent.emit(str) triggers _pasteInput.

    Multi-threaded Architecture (v0.xx.0-a and later)

    In newer versions, input reading is decoupled from the main thread using a queue to prevent blocking the UI:

    1. Thread 1 (Input Thread): TTkInputDriver.read() yields inString. key_process(inString) is called, returning a tuple of (kevt, mevt, paste). These are placed into a queue.
    2. Thread 2 (Main Thread): The main thread performs queue.get(), then emits inputEvent.emit(kevt, mevt) to trigger _processInput and pasteEvent.emit(str) to trigger _pasteInput.

  9. Use TTkTable for data display

    main

    The TTkTable widget is used for displaying structured data. It supports various advanced configurations:

    • Custom Models: Implementing custom data models for table content.
    • Theming: Customizing colors, headers, and lines.
    • Events: Handling interactions within the table.

    Examples are located in tutorial/examples/TTkTable/.

  10. Capabilities and limitations for game development in pyTermTk

    main

    When developing games with pyTermTk, you can leverage full mouse support, key presses, and a full glyph set available on standard terminals (including NerdFonts and emoji).

    Critical Limitation: Games cannot rely on keyboard 'up/down' events (detecting the release of a key). This means games that require a key release to trigger an interaction (like MarioBros) are not technically possible in a terminal environment using this library.

    Recommended Game Types:

    • Games that use discrete mouse clicks (e.g., Canabalt style).
    • Games that do not require long keypresses (e.g., Pacman, Nibbles).
    • Roguelikes and mouse-driven RPGs (e.g., Diablo style where mouse handles movement/combat and keyboard handles menus/potions).

  12. Import ttkDesigner content using TTkUiLoader

    main

    The TTkUiLoader class provides methods to integrate UI content generated by ttkDesigner into your application. It supports two primary integration patterns:

    1. Returning a new Widget: Using the loader to instantiate a standalone widget object.
    2. Extending a custom widget: Using the loader to populate an existing custom class (e.g., a subclass of TTkWindow) with the designed UI elements.

    To use the content, you typically pass a base64-deflated object (the compressed string representation of the UI) to TTkUiLoader.loadDict.