cmdgui 0.1.1__tar.gz → 0.2.0__tar.gz

cmdgui-0.2.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: cmdgui
+Version: 0.2.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, tabs, and a box that shows everything you print.
+- **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 and a file browser.

cmdgui-0.2.0/README.md

@@ -0,0 +1,80 @@
+# 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, tabs, and a box that shows everything you print.
+- **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 and a file browser.

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

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

cmdgui-0.2.0/src/cmdgui/__init__.py

@@ -0,0 +1,14 @@
+from .view import View, Popup, Panel, Timer
+from .widgets import (
+    Widget, Text, Label, Button, TextInput, TextArea, ProgressBar, Slider, Checkbox, Toggle,
+    RadioGroup, Select, Menu, Tree, Table, Tabs, 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", "Timer", "Widget", "Text", "Label", "Button", "TextInput", "TextArea", "ProgressBar",
+    "Slider", "Checkbox", "Toggle", "RadioGroup", "Select", "Menu", "Tree", "Table", "Tabs", "Stdout", "DrawMouse", "DEFAULT_THEME", "field",
+    "Input", "mouse", "LayoutError", "Canvas", "style", "styled", "Color", "ColorName",
+]

{cmdgui-0.1.1 → cmdgui-0.2.0}/src/cmdgui/shorts.py

@@ -1,6 +1,7 @@
 import os
 import sys
 import unicodedata
+from typing import Literal, Optional, Tuple, Union, get_args
 
 ESC = "\x1b["
 RESET = ESC + "0m"
@@ -26,11 +27,58 @@ LINE_CHARS = {
     UP | DOWN | LEFT | RIGHT: "┼",
 }
 
+# The basic colors (and 'bright_' versions) use the terminal's own palette, so
+# they match the user's theme
 COLORS = {
     "black": 0, "red": 1, "green": 2, "yellow": 3,
     "blue": 4, "magenta": 5, "cyan": 6, "white": 7,
 }
 
+# More colors, as numbers in the 256-color palette (supported by nearly every terminal).
+# "grey" works wherever "gray" does.
+EXTRA_COLORS = {
+    # reds and pinks
+    "dark_red": 88, "maroon": 52, "crimson": 161, "scarlet": 196, "coral": 203,
+    "salmon": 209, "rose": 211, "pink": 218, "hot_pink": 205, "deep_pink": 198,
+    # oranges, yellows and browns
+    "orange": 208, "dark_orange": 166, "amber": 214, "gold": 220, "lemon": 227,
+    "cream": 229, "peach": 216, "tan": 180, "khaki": 186, "brown": 94,
+    "rust": 130, "copper": 173,
+    # greens
+    "lime": 118, "chartreuse": 112, "olive": 100, "dark_green": 28, "forest": 22,
+    "emerald": 35, "sea_green": 72, "mint": 121, "pale_green": 157,
+    # blues and cyans
+    "teal": 30, "turquoise": 44, "aqua": 51, "sky": 117, "light_blue": 153,
+    "steel_blue": 67, "cornflower": 69, "royal_blue": 63, "dodger_blue": 33,
+    "dark_blue": 19, "navy": 17, "slate": 60,
+    # purples
+    "indigo": 54, "purple": 93, "dark_purple": 53, "violet": 177, "lavender": 183,
+    "plum": 176, "orchid": 170, "fuchsia": 201,
+    # grays
+    "charcoal": 236, "dark_gray": 238, "gray": 244, "silver": 249,
+    "light_gray": 252, "snow": 255,
+}
+
+# Every color name, so editors can autocomplete style(fg="...") and catch typos.
+# Keep in step with COLORS and EXTRA_COLORS (checked below).
+ColorName = Literal[
+    "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "bright_black",
+    "bright_red", "bright_green", "bright_yellow", "bright_blue", "bright_magenta",
+    "bright_cyan", "bright_white",
+    "dark_red", "maroon", "crimson", "scarlet", "coral", "salmon", "rose", "pink",
+    "hot_pink", "deep_pink", "orange", "dark_orange", "amber", "gold", "lemon", "cream",
+    "peach", "tan", "khaki", "brown", "rust", "copper", "lime", "chartreuse", "olive",
+    "dark_green", "forest", "emerald", "sea_green", "mint", "pale_green", "teal",
+    "turquoise", "aqua", "sky", "light_blue", "steel_blue", "cornflower", "royal_blue",
+    "dodger_blue", "dark_blue", "navy", "slate", "indigo", "purple", "dark_purple",
+    "violet", "lavender", "plum", "orchid", "fuchsia", "charcoal", "dark_gray", "gray",
+    "silver", "light_gray", "snow",
+]
+# A color: a name, a 256-color palette number, "#rrggbb", or (r, g, b)
+Color = Union[ColorName, str, int, Tuple[int, int, int]]
+assert set(get_args(ColorName)) == set(COLORS) | {"bright_" + c for c in COLORS} | set(EXTRA_COLORS), \
+    "ColorName is out of date with COLORS / EXTRA_COLORS"
+
 # --- Screen / cursor ------------------------------------------------------
 
 def screen_size():
@@ -53,16 +101,21 @@ def write(s):
 
 # --- Styling ----------------------------------------------------------------
 
-def style(fg=None, bg=None, bold=False, dim=False, italic=False, underline=False, reverse=False):
-    """Escape code for a style. Colors are names from COLORS, prefixed 'bright_' for bright."""
+def style(fg: Optional[Color] = None, bg: Optional[Color] = None, bold: bool = False, dim: bool = False,
+          italic: bool = False, underline: bool = False, reverse: bool = False) -> str:
+    """Escape code for a style. A color can be:
+        a name from COLORS, or 'bright_' + one of those: "red", "bright_red"
+        a name from EXTRA_COLORS: "orange", "teal", "lavender"
+        a number in the 256-color palette: 208
+        a hex string or (r, g, b) for exact colors, if the terminal has true color: "#ff8800" """
     codes = []
     if bold: codes.append("1")
     if dim: codes.append("2")
     if italic: codes.append("3")
     if underline: codes.append("4")
     if reverse: codes.append("7")
-    if fg: codes.append(str(_color_code(fg, 30)))
-    if bg: codes.append(str(_color_code(bg, 40)))
+    if fg is not None: codes.append(_color_code(fg, 30))
+    if bg is not None: codes.append(_color_code(bg, 40))
     return f"{ESC}{';'.join(codes)}m" if codes else ""
 
 def styled(text, **kwargs):
@@ -70,9 +123,28 @@ def styled(text, **kwargs):
     s = style(**kwargs)
     return f"{s}{text}{RESET}" if s else text
 
-def _color_code(name, base):
-    if name.startswith("bright_"): return COLORS[name[7:]] + base + 60
-    return COLORS[name] + base
+def _color_code(color, base):
+    """The SGR code for a color, base is 30 for the foreground or 40 for the background."""
+    extended = base + 8 # 38 / 48 start a 256-color or true color code
+    if isinstance(color, int) and not isinstance(color, bool) and 0 <= color <= 255:
+        return f"{extended};5;{color}"
+    if isinstance(color, (tuple, list)) and len(color) == 3:
+        return f"{extended};2;" + ";".join(str(max(0, min(255, int(v)))) for v in color)
+    if isinstance(color, str):
+        name = color.lower().replace("grey", "gray").replace(" ", "_")
+        if name.startswith("#") and len(name) == 7:
+            try:
+                return f"{extended};2;{int(name[1:3], 16)};{int(name[3:5], 16)};{int(name[5:7], 16)}"
+            except ValueError:
+                pass
+        elif name in COLORS:
+            return str(COLORS[name] + base)
+        elif name.startswith("bright_") and name[7:] in COLORS:
+            return str(COLORS[name[7:]] + base + 60)
+        elif name in EXTRA_COLORS:
+            return f"{extended};5;{EXTRA_COLORS[name]}"
+    raise ValueError(f"unknown color {color!r}: use a name from COLORS or EXTRA_COLORS "
+                     f"(with 'bright_' for the basic ones), 0-255, '#rrggbb' or (r, g, b)")
 
 # --- Text width -------------------------------------------------------------
 # Emoji and CJK characters take two columns, combining accents take none.
@@ -190,6 +262,10 @@ class Canvas:
             x += self.put(x, y, char, style)
         return x
 
+    def restyle(self, style=""):
+        """Give every cell the same style, keeping the characters."""
+        self.styles = [[style] * self.width for _ in range(self.height)]
+
     def fill(self, x=0, y=0, w=None, h=None, char=" ", style=""):
         """Fill a rectangle (the whole canvas by default)."""
         w = self.width if w is None else w