cmdgui 0.1.1__tar.gz → 0.3.0__tar.gz

cmdgui-0.3.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: cmdgui
+Version: 0.3.0
+Summary: Simple terminal GUIs: draw your layout as text, the view runs itself
+Author: olliez-mods
+License-Expression: MIT
+Project-URL: homepage, https://github.com/olliez-mods/cmdgui
+Keywords: terminal,tui,gui,cli,widgets
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cmdgui
+
+Simple terminal GUIs in Python. Draw your layout as text, fill in the widgets,
+and keep writing your program — the view runs on its own thread, so there's no
+event loop to hand control to and no draw calls to make.
+
+```
+┌─ name ───────────────────┐
+│quinn                     │[         Greet          ] ON   fast
+├─ fruit ──────────────────┼─ scores ──────────────────────────────────┐
+│ apple                    │name      score  city                      │
+│ banana                   │Ada       98     London                    │
+│ cherry                   │Linus     87     Helsinki                  │
+│                          ├─ log ─────────────────────────────────────┤
+│                          │Hello, quinn! 👋                           │
+│                          │picked cherry                              │
+└──────────────────────────┴───────────────────────────────────────────┘
+ ████████████████████████████████░░░░░░░░░░░░░░░░  67%[ ] done
+```
+
+No dependencies. macOS and Linux; Windows support is written but untested.
+
+## Install
+
+```bash
+pip install cmdgui
+```
+
+## Quick start
+
+```python
+from cmdgui import View, Button, Stdout
+import time
+
+class App(View):
+    layout = """
+        start  pause  .
+        log    -      -
+    """
+    start = Button("Start", on_click=lambda: print("started"))
+    pause = Button("Pause", on_click=lambda: print("paused"))
+    log = Stdout()
+
+view = App()
+
+for i in range(100):
+    print(f"tick {i}")   # shows up in the log box
+    time.sleep(0.5)
+```
+
+Press `q` to quit (or Ctrl+C). Because the widgets are class attributes, your
+editor knows `view.start` is a `Button` — autocomplete and type checking work.
+
+## What's in it
+
+- **Layouts drawn as text**: each word is a grid cell, `-` and `|` stretch a widget
+  across cells, and borders between neighbours join up.
+- **Widgets**: text, labels, buttons, one-line and multi-line text boxes (with password
+  mode and history), checkboxes, toggles, radio buttons, dropdowns, sliders, progress
+  bars, menus, folding trees, tables, a calendar and date picker, tabs, split panes to
+  drag, a log viewer with levels and search, a box that shows everything you print, and
+  a pixel canvas with lines, shapes and curves.
+- **Styled text**: `"[bold red]Error:[/] couldn't open [cyan]notes.txt[/]"` in labels,
+  buttons and text.
+- **Text boxes that behave**: select with the mouse or Shift, copy, cut and paste,
+  pasting in one go, and dim hints before, after and ahead of the cursor for autocomplete.
+- **Inline views**: draw in a few rows under the prompt instead of the whole screen, with
+  printed text scrolling above.
+- **Popups**: dialogs, dropdowns and command menus that float over the layout.
+- **Mouse and keyboard**: clicks, dragging, the scroll wheel, Tab between widgets, and
+  your own key bindings.
+- **Timers**: `view.every(1, tick)` and `view.after(5, fn)`, no threads needed.
+- **Themes**: restyle any part, with 73 named colors, the 256-color palette, or exact
+  hex colors.
+- **Your own widgets**: subclass `Widget`, draw into a canvas, and it works in layouts.
+
+## Documentation
+
+- [Overview](https://github.com/olliez-mods/cmdgui/blob/main/docs/index.md): ways to build a view, changing widgets, timers, running and quitting
+- [Layouts](https://github.com/olliez-mods/cmdgui/blob/main/docs/layouts.md)
+- [Widgets](https://github.com/olliez-mods/cmdgui/blob/main/docs/widgets.md)
+- [Popups](https://github.com/olliez-mods/cmdgui/blob/main/docs/popups.md)
+- [Keys and focus](https://github.com/olliez-mods/cmdgui/blob/main/docs/keys-and-focus.md)
+- [Themes and colors](https://github.com/olliez-mods/cmdgui/blob/main/docs/themes.md)
+- [Your own widgets](https://github.com/olliez-mods/cmdgui/blob/main/docs/custom-widgets.md)
+
+The [examples](https://github.com/olliez-mods/cmdgui/tree/main/examples) folder has a
+widget demo, a dashboard, popups, tabs, a console, a file browser, pixel graphics, a
+log viewer with split panes, date pickers, and an inline progress display.

cmdgui-0.3.0/README.md

@@ -0,0 +1,89 @@
+# cmdgui
+
+Simple terminal GUIs in Python. Draw your layout as text, fill in the widgets,
+and keep writing your program — the view runs on its own thread, so there's no
+event loop to hand control to and no draw calls to make.
+
+```
+┌─ name ───────────────────┐
+│quinn                     │[         Greet          ] ON   fast
+├─ fruit ──────────────────┼─ scores ──────────────────────────────────┐
+│ apple                    │name      score  city                      │
+│ banana                   │Ada       98     London                    │
+│ cherry                   │Linus     87     Helsinki                  │
+│                          ├─ log ─────────────────────────────────────┤
+│                          │Hello, quinn! 👋                           │
+│                          │picked cherry                              │
+└──────────────────────────┴───────────────────────────────────────────┘
+ ████████████████████████████████░░░░░░░░░░░░░░░░  67%[ ] done
+```
+
+No dependencies. macOS and Linux; Windows support is written but untested.
+
+## Install
+
+```bash
+pip install cmdgui
+```
+
+## Quick start
+
+```python
+from cmdgui import View, Button, Stdout
+import time
+
+class App(View):
+    layout = """
+        start  pause  .
+        log    -      -
+    """
+    start = Button("Start", on_click=lambda: print("started"))
+    pause = Button("Pause", on_click=lambda: print("paused"))
+    log = Stdout()
+
+view = App()
+
+for i in range(100):
+    print(f"tick {i}")   # shows up in the log box
+    time.sleep(0.5)
+```
+
+Press `q` to quit (or Ctrl+C). Because the widgets are class attributes, your
+editor knows `view.start` is a `Button` — autocomplete and type checking work.
+
+## What's in it
+
+- **Layouts drawn as text**: each word is a grid cell, `-` and `|` stretch a widget
+  across cells, and borders between neighbours join up.
+- **Widgets**: text, labels, buttons, one-line and multi-line text boxes (with password
+  mode and history), checkboxes, toggles, radio buttons, dropdowns, sliders, progress
+  bars, menus, folding trees, tables, a calendar and date picker, tabs, split panes to
+  drag, a log viewer with levels and search, a box that shows everything you print, and
+  a pixel canvas with lines, shapes and curves.
+- **Styled text**: `"[bold red]Error:[/] couldn't open [cyan]notes.txt[/]"` in labels,
+  buttons and text.
+- **Text boxes that behave**: select with the mouse or Shift, copy, cut and paste,
+  pasting in one go, and dim hints before, after and ahead of the cursor for autocomplete.
+- **Inline views**: draw in a few rows under the prompt instead of the whole screen, with
+  printed text scrolling above.
+- **Popups**: dialogs, dropdowns and command menus that float over the layout.
+- **Mouse and keyboard**: clicks, dragging, the scroll wheel, Tab between widgets, and
+  your own key bindings.
+- **Timers**: `view.every(1, tick)` and `view.after(5, fn)`, no threads needed.
+- **Themes**: restyle any part, with 73 named colors, the 256-color palette, or exact
+  hex colors.
+- **Your own widgets**: subclass `Widget`, draw into a canvas, and it works in layouts.
+
+## Documentation
+
+- [Overview](https://github.com/olliez-mods/cmdgui/blob/main/docs/index.md): ways to build a view, changing widgets, timers, running and quitting
+- [Layouts](https://github.com/olliez-mods/cmdgui/blob/main/docs/layouts.md)
+- [Widgets](https://github.com/olliez-mods/cmdgui/blob/main/docs/widgets.md)
+- [Popups](https://github.com/olliez-mods/cmdgui/blob/main/docs/popups.md)
+- [Keys and focus](https://github.com/olliez-mods/cmdgui/blob/main/docs/keys-and-focus.md)
+- [Themes and colors](https://github.com/olliez-mods/cmdgui/blob/main/docs/themes.md)
+- [Your own widgets](https://github.com/olliez-mods/cmdgui/blob/main/docs/custom-widgets.md)
+
+The [examples](https://github.com/olliez-mods/cmdgui/tree/main/examples) folder has a
+widget demo, a dashboard, popups, tabs, a console, a file browser, pixel graphics, a
+log viewer with split panes, date pickers, and an inline progress display.

{cmdgui-0.1.1 → cmdgui-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cmdgui"
-version = "0.1.1"
+version = "0.3.0"
 description = "Simple terminal GUIs: draw your layout as text, the view runs itself"
 readme = "README.md"
 requires-python = ">=3.9"

cmdgui-0.3.0/src/cmdgui/__init__.py

@@ -0,0 +1,14 @@
+from .view import View, Popup, Panel, Edge, Timer
+from .widgets import (
+    Widget, Text, Label, Button, TextInput, TextArea, ProgressBar, Slider, Checkbox, Toggle,
+    RadioGroup, Select, Menu, Tree, Table, Tabs, Graphics, Calendar, DatePicker, Log, Stdout, DrawMouse, DEFAULT_THEME, field,
+)
+from .inputs import Input, mouse
+from .layout import LayoutError
+from .shorts import Canvas, style, styled, Color, ColorName
+
+__all__ = [
+    "View", "Popup", "Panel", "Edge", "Timer", "Widget", "Text", "Label", "Button", "TextInput", "TextArea", "ProgressBar",
+    "Slider", "Checkbox", "Toggle", "RadioGroup", "Select", "Menu", "Tree", "Table", "Tabs", "Graphics", "Calendar", "DatePicker", "Log", "Stdout", "DrawMouse", "DEFAULT_THEME", "field",
+    "Input", "mouse", "LayoutError", "Canvas", "style", "styled", "Color", "ColorName",
+]

{cmdgui-0.1.1 → cmdgui-0.3.0}/src/cmdgui/_platform.py

@@ -22,8 +22,11 @@ if not WINDOWS:
             fd = sys.stdin.fileno()
             self._saved = termios.tcgetattr(fd)
             attrs = termios.tcgetattr(fd)
-            # No line buffering, no echo. ISIG stays on so Ctrl+C still raises KeyboardInterrupt.
-            attrs[3] &= ~(termios.ICANON | termios.ECHO)
+            # No line buffering or echo. Ctrl+C, Ctrl+V, Ctrl+S and so on come through as keys
+            # (ISIG, IEXTEN, IXON off): the view turns Ctrl+C back into KeyboardInterrupt when
+            # it isn't copying, and Ctrl+S no longer freezes the output
+            attrs[3] &= ~(termios.ICANON | termios.ECHO | termios.ISIG | termios.IEXTEN)
+            attrs[0] &= ~termios.IXON
             termios.tcsetattr(fd, termios.TCSANOW, attrs)
 
         def disable(self):

cmdgui-0.3.0/src/cmdgui/clipboard.py

@@ -0,0 +1,53 @@
+"""Copying to the system clipboard. A terminal app can't reach the clipboard
+directly, so copy() tries both ways there are:
+
+- OSC 52, an escape code asking the terminal to copy. Works over SSH. Most modern
+  terminals support it (kitty, WezTerm, Ghostty, Alacritty, Windows Terminal, foot,
+  iTerm2 once allowed in its settings); macOS's Terminal.app doesn't.
+- the system's own tool (pbcopy, wl-copy, xclip, xsel, clip), when running locally.
+
+Pasting from the system clipboard is done by the terminal (Cmd+V, or Ctrl+Shift+V),
+which sends the text to the app as a paste. paste() gives what was last copied in
+this program, for Ctrl+V."""
+from __future__ import annotations
+
+import base64
+import os
+import shutil
+import subprocess
+import sys
+from .shorts import write
+
+_last = "" # the last text copied, for paste()
+
+# Clipboard tools, most likely first: (command, needs)
+TOOLS = [
+    (["pbcopy"], "darwin"),
+    (["wl-copy"], "WAYLAND_DISPLAY"),
+    (["xclip", "-selection", "clipboard"], "DISPLAY"),
+    (["xsel", "--clipboard", "--input"], "DISPLAY"),
+    (["clip"], "win32"),
+]
+
+
+def copy(text: str) -> None:
+    """Put text on the system clipboard (as far as the terminal allows), and keep it
+    for paste()."""
+    global _last
+    _last = text
+    write("\x1b]52;c;" + base64.b64encode(text.encode("utf-8")).decode("ascii") + "\x07")
+    if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_TTY"):
+        return # the tools would copy on the remote machine, not yours
+    for command, needs in TOOLS:
+        if (needs == sys.platform or os.environ.get(needs)) and shutil.which(command[0]):
+            try:
+                subprocess.run(command, input=text.encode("utf-8"), timeout=2, check=False,
+                               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            except (OSError, subprocess.SubprocessError):
+                continue
+            return
+
+
+def paste() -> str:
+    """The text last copied with copy() in this program."""
+    return _last

{cmdgui-0.1.1 → cmdgui-0.3.0}/src/cmdgui/inputs.py

@@ -1,6 +1,7 @@
 import queue
 import re
 import sys
+import time
 
 from .shorts import ESC, write
 from ._platform import Terminal
@@ -57,6 +58,10 @@ def update_state(input):
 # 1006 = SGR encoding, which gives readable decimal coordinates with no size limit
 MOUSE_ON = ESC + "?1003h" + ESC + "?1006h"
 MOUSE_OFF = ESC + "?1003l" + ESC + "?1006l"
+# Bracketed paste: the terminal wraps pasted text in these, so it arrives as one
+# "paste" input instead of keys (a pasted newline isn't Enter)
+PASTE_ON, PASTE_OFF = ESC + "?2004h", ESC + "?2004l"
+PASTE_START, PASTE_END = "\x1b[200~", "\x1b[201~"
 
 # SGR mouse report: ESC [ < button ; x ; y  then M (press/move) or m (release)
 SGR_MOUSE = re.compile(r"\x1b\[<(\d+);(\d+);(\d+)([Mm])")
@@ -105,7 +110,7 @@ def enable():
     """Raw keyboard mode, mouse reporting, and capture print output."""
     _stderr_log.clear()
     _terminal.enable()
-    write(MOUSE_ON)
+    write(MOUSE_ON + PASTE_ON)
     sys.stdout = StreamInterceptor(sys.stdout, "stdout")
     sys.stderr = StreamInterceptor(sys.stderr, "stderr")
 
@@ -116,7 +121,7 @@ def disable():
         sys.stdout = sys.stdout.real
     if isinstance(sys.stderr, StreamInterceptor):
         sys.stderr = sys.stderr.real
-    write(MOUSE_OFF)
+    write(MOUSE_OFF + PASTE_OFF)
     _terminal.disable()
 
 
@@ -125,6 +130,23 @@ def captured_stderr():
     return "".join(_stderr_log)
 
 
+CURSOR_REPORT = re.compile(r"\x1b\[(\d+);(\d+)R")
+
+def cursor_position(timeout=0.5):
+    """Ask the terminal where the cursor is: (x, y), 0-based, or None if it doesn't say.
+    Call after enable() and before reading inputs; anything typed meanwhile is kept."""
+    global _buffer
+    write(ESC + "6n")
+    end = time.monotonic() + timeout
+    while time.monotonic() < end:
+        _buffer += _terminal.read(max(0.0, end - time.monotonic()))
+        match = CURSOR_REPORT.search(_buffer)
+        if match:
+            _buffer = _buffer[:match.start()] + _buffer[match.end():]
+            return int(match.group(2)) - 1, int(match.group(1)) - 1
+    return None
+
+
 def wake():
     """Make read_inputs() return straight away. Safe from any thread."""
     _terminal.wake()
@@ -146,7 +168,14 @@ def read_inputs(timeout=0.1):
             inputs.append(Input(kind, {"text": text}))
 
     while _buffer:
-        if _buffer.startswith("\x1b[<"):
+        if _buffer.startswith(PASTE_START):
+            end = _buffer.find(PASTE_END)
+            if end < 0:
+                break  # the rest of the paste is still coming
+            text = _buffer[len(PASTE_START):end].replace("\r\n", "\n").replace("\r", "\n")
+            inputs.append(Input("paste", {"text": text}))
+            _buffer = _buffer[end + len(PASTE_END):]
+        elif _buffer.startswith("\x1b[<"):
             match = SGR_MOUSE.match(_buffer)
             if not match:
                 break  # incomplete mouse report, wait for the rest