console-window 1.0.0__tar.gz

console_window-1.0.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

console_window-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joe D
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

console_window-1.0.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: console-window
+Version: 1.0.0
+Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
+Author-email: Joe Defen <joedef@duck.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Terminals
+Classifier: Topic :: Software Development :: User Interfaces
+License-File: LICENSE
+
+
+# console-window 
+
+**A robust and feature-rich wrapper for the standard Python `curses` library, simplifying the creation of complex, full-screen Text User Interface (TUI) applications.**
+
+This package abstracts away the complexities of managing curses pads, dynamic screen resizing, custom scroll/pick synchronization, and keyboard handling, allowing developers to focus purely on content.
+
+## Installation
+
+Install the package via `pip`:
+
+```bash
+pip install console-window
+```
+
+## Core Features (The "Secret Sauce")
+
+The wrapper handles several advanced terminal interaction patterns automatically:
+
+  * **Padded Content Management:** Uses separate `head` and `body` pads, allowing for a static header area while the main content area can be scrolled independently.
+  * **Seamless Resizing:** Automatically detects terminal size changes (`KEY_RESIZE`) and recalculates layout dimensions, with robust error handling to prevent common `curses.error` crashes during resizing.
+  * **Scroll & Pick Synchronization:** The `Window` class manages **scroll position** and a separate **pick position** (highlighted row) simultaneously. When using pick mode, scrolling automatically tracks the highlighted element to keep it visible.
+  * **Intuitive Navigation:** Provides built-in handling for common navigation keys (`j`/`k`, `UP`/`DOWN`, Page Up/Down, `H`/`M`/`L` for home/middle/last viewable line, etc.).
+  * **Dynamic Options Management (`OptionSpinner`):** The companion class simplifies creation of application settings, allowing users to **toggle options** or input strings using single keypresses (e.g., `p` to toggle pick mode).
+  * **Blocking Popups:** Includes fully implemented, blocking pop-up methods for user input (`.answer()`) and alerts (`.alert()`), handling the necessary temporary screen takeover and cursor management.
+
+## Minimal Working Example
+
+This example demonstrates setting up the window, using the `OptionSpinner` for control, and running the main render/prompt loop.
+
+```python
+import curses
+from ConsoleWindow import Window, OptionSpinner, SimpleNamespace
+
+def main_app_loop(stdscr):
+    # 1. Setup Options Manager
+    spin = OptionSpinner()
+    opts = spin.default_obj # Access options via this namespace
+
+    # Add features controlled by keypresses
+    spin.add_key('help_mode', '? - toggle help screen', vals=[False, True])
+    spin.add_key('pick_mode', 'p - toggle pick mode', vals=[False, True])
+    spin.add_key('pick_size', 's - #rows in pick', vals=[1, 2, 3])
+    spin.add_key('name', 'n - select name', prompt='Provide Your Name:')
+
+    # 2. Initialize Window
+    win = Window(head_line=True, keys=spin.keys)
+    opts.name = "[hit 'n' to enter name]"
+    loop_count = 0
+
+    while True:
+        loop_count += 1
+        
+        # 3. Add Content
+        if opts.help_mode:
+            win.set_pick_mode(False)
+            spin.show_help_nav_keys(win)
+            spin.show_help_body(win)
+        else:
+            win.set_pick_mode(opts.pick_mode, opts.pick_size)
+            win.add_header(f'TUI App Header | Loop: {loop_count} | Name: "{opts.name}"')
+            
+            # Add body content (scrollable)
+            for idx in range(100):
+                win.add_body(f'Main Item {idx+1}')
+
+        # 4. Render and Prompt for Input
+        win.render()
+        key = win.prompt(seconds=0.5) # Wait for half a second or a keypress
+
+        # 5. Handle Keys (App-specific logic)
+        if key is not None:
+            # Check if OptionSpinner can handle the key (p, s, n, ?)
+            spin.do_key(key, win) 
+            
+            if key in (ord('q'), ord('Q')):
+                break # Exit the loop
+        
+        win.clear()
+
+if __name__ == '__main__':
+    try:
+        # Note: Window.__init__ starts curses and registers atexit cleanup
+        curses.wrapper(main_app_loop)
+    except KeyboardInterrupt:
+        pass
+```
+
+## License
+MIT
+
+

console_window-1.0.0/README.md

@@ -0,0 +1,91 @@
+
+# console-window 
+
+**A robust and feature-rich wrapper for the standard Python `curses` library, simplifying the creation of complex, full-screen Text User Interface (TUI) applications.**
+
+This package abstracts away the complexities of managing curses pads, dynamic screen resizing, custom scroll/pick synchronization, and keyboard handling, allowing developers to focus purely on content.
+
+## Installation
+
+Install the package via `pip`:
+
+```bash
+pip install console-window
+```
+
+## Core Features (The "Secret Sauce")
+
+The wrapper handles several advanced terminal interaction patterns automatically:
+
+  * **Padded Content Management:** Uses separate `head` and `body` pads, allowing for a static header area while the main content area can be scrolled independently.
+  * **Seamless Resizing:** Automatically detects terminal size changes (`KEY_RESIZE`) and recalculates layout dimensions, with robust error handling to prevent common `curses.error` crashes during resizing.
+  * **Scroll & Pick Synchronization:** The `Window` class manages **scroll position** and a separate **pick position** (highlighted row) simultaneously. When using pick mode, scrolling automatically tracks the highlighted element to keep it visible.
+  * **Intuitive Navigation:** Provides built-in handling for common navigation keys (`j`/`k`, `UP`/`DOWN`, Page Up/Down, `H`/`M`/`L` for home/middle/last viewable line, etc.).
+  * **Dynamic Options Management (`OptionSpinner`):** The companion class simplifies creation of application settings, allowing users to **toggle options** or input strings using single keypresses (e.g., `p` to toggle pick mode).
+  * **Blocking Popups:** Includes fully implemented, blocking pop-up methods for user input (`.answer()`) and alerts (`.alert()`), handling the necessary temporary screen takeover and cursor management.
+
+## Minimal Working Example
+
+This example demonstrates setting up the window, using the `OptionSpinner` for control, and running the main render/prompt loop.
+
+```python
+import curses
+from ConsoleWindow import Window, OptionSpinner, SimpleNamespace
+
+def main_app_loop(stdscr):
+    # 1. Setup Options Manager
+    spin = OptionSpinner()
+    opts = spin.default_obj # Access options via this namespace
+
+    # Add features controlled by keypresses
+    spin.add_key('help_mode', '? - toggle help screen', vals=[False, True])
+    spin.add_key('pick_mode', 'p - toggle pick mode', vals=[False, True])
+    spin.add_key('pick_size', 's - #rows in pick', vals=[1, 2, 3])
+    spin.add_key('name', 'n - select name', prompt='Provide Your Name:')
+
+    # 2. Initialize Window
+    win = Window(head_line=True, keys=spin.keys)
+    opts.name = "[hit 'n' to enter name]"
+    loop_count = 0
+
+    while True:
+        loop_count += 1
+        
+        # 3. Add Content
+        if opts.help_mode:
+            win.set_pick_mode(False)
+            spin.show_help_nav_keys(win)
+            spin.show_help_body(win)
+        else:
+            win.set_pick_mode(opts.pick_mode, opts.pick_size)
+            win.add_header(f'TUI App Header | Loop: {loop_count} | Name: "{opts.name}"')
+            
+            # Add body content (scrollable)
+            for idx in range(100):
+                win.add_body(f'Main Item {idx+1}')
+
+        # 4. Render and Prompt for Input
+        win.render()
+        key = win.prompt(seconds=0.5) # Wait for half a second or a keypress
+
+        # 5. Handle Keys (App-specific logic)
+        if key is not None:
+            # Check if OptionSpinner can handle the key (p, s, n, ?)
+            spin.do_key(key, win) 
+            
+            if key in (ord('q'), ord('Q')):
+                break # Exit the loop
+        
+        win.clear()
+
+if __name__ == '__main__':
+    try:
+        # Note: Window.__init__ starts curses and registers atexit cleanup
+        curses.wrapper(main_app_loop)
+    except KeyboardInterrupt:
+        pass
+```
+
+## License
+MIT
+

console_window-1.0.0/console_window/ConsoleWindow.py

@@ -0,0 +1,778 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Custom Wrapper for python curses.
+"""
+# pylint: disable=too-many-instance-attributes,too-many-arguments
+# pylint: disable=invalid-name,broad-except,too-many-branches,global-statement
+
+import traceback
+import atexit
+import signal
+import time
+import curses
+import textwrap
+from types import SimpleNamespace
+from curses.textpad import rectangle, Textbox
+dump_str = None
+
+def ignore_ctrl_c():
+    """" Ignore SIGINT """
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+
+def restore_ctrl_c():
+    """" Handle SIGINT """
+    signal.signal(signal.SIGINT, signal.default_int_handler)
+
+class OptionSpinner:
+    """Manage a bunch of options where the value is rotate thru
+    a fixed set of values pressing a key."""
+    def __init__(self):
+        """Give the object with the attribute to change its
+        value (e.g., options from argparse or "self" from
+        the object managing the window).
+
+        And array of specs like:
+            ['a - allow auto suggestions', 'allow_auto', True, False],
+            ['/ - filter pattern', 'filter_str', self.filter_str],
+        A spec can have a trailing None + more comments shown after
+        the value.
+        """
+        self.options, self.keys = [], []
+        self.margin = 4 # + actual width (1st column right pos)
+        self.align = self.margin # + actual width (1st column right pos)
+        self.default_obj = SimpleNamespace() # if not given one
+        self.attr_to_option = {} # given an attribute, find its option ns
+        self.key_to_option = {} # given key, options namespace
+        self.keys = set()
+
+    @staticmethod
+    def _make_option_ns():
+        return SimpleNamespace(
+            keys=[],
+            descr='',
+            obj=None,
+            attr='',
+            vals=None,
+            prompt=None,
+            comments=[],
+        )
+
+    def get_value(self, attr, coerce=False):
+        """Get the value of the given attribute."""
+        ns = self.attr_to_option.get(attr, None)
+        obj = ns.obj if ns else None
+        value = getattr(obj, attr, None) if obj else None
+        if value is None and obj and coerce:
+            if ns.vals:
+                if value not in ns.vals:
+                    value = ns.vals[0]
+                    setattr(obj, attr, value)
+            else:
+                if value is None:
+                    value = ''
+                    setattr(ns.obj, ns.attr, '')
+        return value
+
+    def _register(self, ns):
+        """ Create the mappings needed"""
+        assert ns.attr not in self.attr_to_option
+        self.attr_to_option[ns.attr] = ns
+        for key in ns.keys:
+            assert key not in self.key_to_option, f'key ({chr(key)}, {key}) already used'
+            self.key_to_option[key] = ns
+            self.keys.add(key)
+        self.options.append(ns)
+        self.align = max(self.align, self.margin+len(ns.descr))
+        self.get_value(ns.attr, coerce=True)
+
+    def add(self, obj, specs):
+        """ Compatibility Method."""
+        for spec in specs:
+            ns = self._make_option_ns()
+            ns.descr = spec[0]
+            ns.obj = obj
+            ns.attr = spec[1]
+            ns.vals=spec[2:]
+            if None in ns.vals:
+                idx = ns.vals.index(None)
+                ns.vals = ns.vals[:idx]
+                ns.comments = ns.vals[idx+1:]
+            ns.keys = [ord(ns.descr[0])]
+            self._register(ns)
+
+    def add_key(self, attr, descr, obj=None, vals=None, prompt=None, keys=None, comments=None):
+        """ Standard method"""
+        ns = self._make_option_ns()
+        if keys:
+            ns.keys = list(keys) if isinstance(keys, (list, tuple, set)) else [keys]
+        else:
+            ns.keys = [ord(descr[0])]
+        if comments is None:
+            ns.comments = []
+        else:
+            ns.comments = list(comments) if isinstance(keys, (list, tuple)) else [comments]
+        ns.descr = descr
+        ns.attr = attr
+        ns.obj = obj if obj else self.default_obj
+        ns.vals, ns.prompt = vals, prompt
+        assert bool(ns.vals) ^ bool(ns.prompt)
+        self._register(ns)
+
+    @staticmethod
+    def show_help_nav_keys(win):
+        """For help screens, show the navigation keys. """
+        for line in ConsoleWindow.get_nav_keys_blurb().splitlines():
+            if line:
+                win.add_header(line)
+
+    def show_help_body(self, win):
+        """ Write the help page section."""
+        win.add_body('Type keys to alter choice:', curses.A_UNDERLINE)
+
+        for ns in self.options:
+            # get / coerce the current value
+            value = self.get_value(ns.attr)
+            assert value is not None, f'cannot get value of {repr(ns.attr)}'
+            choices = ns.vals if ns.vals else [value]
+
+            win.add_body(f'{ns.descr:>{self.align}}: ')
+
+            for choice in choices:
+                shown = f'{choice}'
+                if isinstance(choice, bool):
+                    shown = "ON" if choice else "off"
+                win.add_body(' ', resume=True)
+                win.add_body(shown, resume=True,
+                    attr=curses.A_REVERSE if choice == value else None)
+
+            for comment in ns.comments:
+                win.add_body(f'{"":>{self.align}}:  {comment}')
+
+    def do_key(self, key, win):
+        """Do the automated processing of a key."""
+        ns = self.key_to_option.get(key, None)
+        if ns is None:
+            return None
+        value = self.get_value(ns.attr)
+        if ns.vals:
+            idx = ns.vals.index(value) if value in ns.vals else -1
+            value = ns.vals[(idx+1) % len(ns.vals)] # choose next
+        else:
+            value = win.answer(prompt=ns.prompt, seed=str(value))
+        setattr(ns.obj, ns.attr, value)
+        return value
+
+class ConsoleWindow:
+    """ Layer above curses to encapsulate what we need """
+    timeout_ms = 200
+    static_scr = None
+    nav_keys = """
+        Navigation:    H/M/L:   top/middle/end-of-page
+            k, UP:  up one row               0, HOME:  first row
+          j, DOWN:  down one row              $, END:  last row
+           Ctrl-u:  half-page up       Ctrl-b, PPAGE:  page up
+           Ctrl-d:  half-page down     Ctrl-f, NPAGE:  page down
+    """
+    def __init__(self, head_line=True, head_rows=50, body_rows=200,
+                 body_cols=200, keys=None, pick_mode=False, pick_size=1,
+                 mod_pick=None, ctrl_c_terminates=True):
+        if ctrl_c_terminates:
+            # then never want to ignore_ctrl_c (so defeat the ignorer/restorer)
+            global ignore_ctrl_c, restore_ctrl_c
+            def noop():
+                return
+            ignore_ctrl_c = restore_ctrl_c = noop
+
+        self.scr = self._start_curses()
+
+        self.head = SimpleNamespace(
+            pad=curses.newpad(head_rows, body_cols),
+            rows=head_rows,
+            cols=body_cols,
+            row_cnt=0,  # no. head rows added
+            texts = [],
+            view_cnt=0,  # no. head rows viewable (NOT in body)
+        )
+        self.body = SimpleNamespace(
+            pad = curses.newpad(body_rows, body_cols),
+            rows= body_rows,
+            cols=body_cols,
+            row_cnt = 0,
+            texts = []
+        )
+        self.mod_pick = mod_pick # call back to modify highlighted row
+        self.hor_line_cnt = 1 if head_line else 0 # no. h-lines in header
+        self.scroll_pos = 0  # how far down into body are we?
+        self.max_scroll_pos = 0
+        self.pick_pos = 0 # in highlight mode, where are we?
+        self.last_pick_pos = -1 # last highlighted position
+        self.pick_mode = pick_mode # whether in highlight mode
+        self.pick_size = pick_size # whether in highlight mode
+        self.rows, self.cols = 0, 0
+        self.body_cols, self.body_rows = body_cols, body_rows
+        self.scroll_view_size = 0  # no. viewable lines of the body
+        self.handled_keys = set(keys) if isinstance(keys, (set, list)) else []
+        self._set_screen_dims()
+        self.calc()
+
+    def get_pad_width(self):
+        """ how much space to actually draw chars? """
+        return min(self.cols-1, self.body_cols)
+
+    @staticmethod
+    def get_nav_keys_blurb():
+        """For a help screen, describe the nav keys"""
+        return textwrap.dedent(ConsoleWindow.nav_keys)
+
+    def _set_screen_dims(self):
+        """Recalculate dimensions ... return True if geometry changed."""
+        rows, cols = self.scr.getmaxyx()
+        same = bool(rows == self.rows and cols == self.cols)
+        self.rows, self.cols = rows, cols
+        return same
+
+    @staticmethod
+    def _start_curses():
+        """ Curses initial setup.  Note: not using curses.wrapper because we
+        don't wish to change the colors. """
+        atexit.register(ConsoleWindow.stop_curses)
+        ignore_ctrl_c()
+        ConsoleWindow.static_scr = scr = curses.initscr()
+        curses.noecho()
+        curses.cbreak()
+        curses.curs_set(0)
+        scr.keypad(1)
+        scr.timeout(ConsoleWindow.timeout_ms)
+        scr.clear()
+        return scr
+
+    def set_pick_mode(self, on=True, pick_size=1):
+        """Set whether in highlight mode."""
+        was_on, was_size = self.pick_mode, self.pick_size
+        self.pick_mode = bool(on)
+        self.pick_size = max(pick_size, 1)
+        if self.pick_mode and (not was_on or was_size != self.pick_size):
+            self.last_pick_pos = -2 # indicates need to clear them all
+
+    @staticmethod
+    def stop_curses():
+        """ Curses shutdown (registered to be called on exit). """
+        if ConsoleWindow.static_scr:
+            curses.nocbreak()
+            curses.echo()
+            ConsoleWindow.static_scr.keypad(0)
+            curses.endwin()
+            ConsoleWindow.static_scr = None
+            restore_ctrl_c()
+
+    def calc(self):
+        """Recalculate dimensions ... return True if geometry changed."""
+        same = self._set_screen_dims()
+        self.head.view_cnt = min(self.rows - self.hor_line_cnt, self.head.row_cnt)
+        self.scroll_view_size = self.rows - self.head.view_cnt - self.hor_line_cnt
+        self.max_scroll_pos = max(self.body.row_cnt - self.scroll_view_size, 0)
+        self.body_base = self.head.view_cnt + self.hor_line_cnt
+        return not same
+
+    def _put(self, ns, *args):
+        """ Add text to head/body pad using its namespace. args:
+            - bytes (converted to str/unicode)
+            - str (unicode)
+            - None (same as curses.A_NORMAL)
+            - int (curses attribute)
+        """
+        def flush(attr=None):
+            nonlocal self, is_body, row, text, seg, first
+            if (is_body and self.pick_mode) or attr is None:
+                attr = curses.A_NORMAL
+            if seg and first:
+                ns.pad.addstr(row, 0, seg[0:self.get_pad_width()], attr)
+            elif seg:
+                _, x = ns.pad.getyx()
+                cols = self.get_pad_width() - x
+                if cols > 0:
+                    ns.pad.addstr(seg[0:cols], attr)
+            text += seg
+            seg, first, attr = '', False, None
+
+        is_body = bool(id(ns) == id(self.body))
+        if ns.row_cnt < ns.rows:
+            row = max(ns.row_cnt, 0)
+            text, seg, first = '', '', True
+            for arg in args:
+                if isinstance(arg, bytes):
+                    arg = arg.decode('utf-8')
+                if isinstance(arg, str):
+                    seg += arg  # note: add w/o spacing
+                elif arg is None or isinstance(arg, (int)):
+                    # assume arg is attribute ... flushes text
+                    flush(attr=arg)
+            flush()
+            ns.texts.append(text)  # text only history
+            ns.row_cnt += 1
+
+    def put_head(self, *args):
+        """ Put a line above the line."""
+        self._put(self.head, *args)
+
+    def put_body(self, *args):
+        """ Put a line below the line."""
+        self._put(self.body, *args)
+
+    def _add(self, ns, text, attr=None, resume=False):
+        """ Add text to head/body pad using its namespace"""
+        is_body = bool(id(ns) == id(self.body))
+        if ns.row_cnt < ns.rows:
+            row = max(ns.row_cnt - (1 if resume else 0), 0)
+            if (is_body and self.pick_mode) or attr is None:
+                attr = curses.A_NORMAL
+            if resume:
+                _, x = ns.pad.getyx()
+                cols = self.get_pad_width() - x
+                if cols > 0:
+                    ns.pad.addstr(text[0:cols], attr)
+                    ns.texts[row] += text
+            else:
+                ns.pad.addstr(row, 0, text[0:self.cols], attr)
+                ns.texts.append(text)  # text only history
+                ns.row_cnt += 1
+
+    def add_header(self, text, attr=None, resume=False):
+        """Add text to header"""
+        self._add(self.head, text, attr, resume)
+
+    def add_body(self, text, attr=None, resume=False):
+        """ Add text to body (below header and header line)"""
+        self._add(self.body, text, attr, resume)
+
+    def draw(self, y, x, text, text_attr=None, width=None, leftpad=False, header=False):
+        """Draws the given text (as utf-8 or unicode) at position (row=y,col=x)
+        with optional text attributes and width.
+        This is more compatible with my older, simpler Window class.
+        """
+        ns = self.head if header else self.body
+        text_attr = text_attr if text_attr else curses.A_NORMAL
+        if y < 0 or y >= ns.rows or x < 0 or x >= ns.cols:
+            return # nada if out of bounds
+        ns.row_cnt = max(ns.row_cnt, y+1)
+
+        uni = text if isinstance(text, str) else text.decode('utf-8')
+
+        if width is not None:
+            width = min(width, self.get_pad_width() - x)
+            if width <= 0:
+                return
+            padlen = width - len(uni)
+            if padlen > 0:
+                if leftpad:
+                    uni = padlen * ' ' + uni
+                else:  # rightpad
+                    uni += padlen * ' '
+            text = uni[:width].encode('utf-8')
+        else:
+            text = uni.encode('utf-8')
+
+        try:
+            while y >= len(ns.texts):
+                ns.texts.append('')
+            ns.texts[y] = ns.texts[y][:x].ljust(x) + uni + ns.texts[y][x+len(uni):]
+            ns.pad.addstr(y, x, text, text_attr)
+        except curses.error:
+            # this sucks, but curses returns an error if drawing the last character
+            # on the screen always.  this can happen if resizing screen even if
+            # special care is taken.  So, we just ignore errors.  Anyhow, you cannot
+            # get decent error handling.
+            pass
+
+
+    def highlight_picked(self):
+        """Highlight the current pick and un-highlight the previous pick."""
+        def get_text(pos):
+            nonlocal self
+            return self.body.texts[pos][0:self.cols] if pos < len(self.body.texts) else ''
+
+        if not self.pick_mode:
+            return
+        pos0, pos1 = self.last_pick_pos, self.pick_pos
+        if pos0 == -2: # special flag to clear all formatting
+            for row in range(self.body.row_cnt):
+                line = get_text(row).ljust(self.get_pad_width())
+                self.body.pad.addstr(row, 0, get_text(row), curses.A_NORMAL)
+        if pos0 != pos1:
+            if 0 <= pos0 < self.body.row_cnt:
+                for i in range(self.pick_size):
+                    line = get_text(pos0+i).ljust(self.get_pad_width())
+                    self.body.pad.addstr(pos0+i, 0, line, curses.A_NORMAL)
+            if 0 <= pos1 < self.body.row_cnt:
+                for i in range(self.pick_size):
+                    line = get_text(pos1+i)
+                    if self.mod_pick:
+                        line = self.mod_pick(line)
+                    line = line.ljust(self.get_pad_width())
+                    self.body.pad.addstr(pos1+i, 0, line, curses.A_REVERSE)
+                self.last_pick_pos = pos1
+
+    def _scroll_indicator_row(self):
+        """ Compute the absolute scroll indicator row:
+        - We want the top to be only when scroll_pos==0
+        - We want the bottom to be only when scroll_pos=max_scroll_pos-1
+        """
+        if self.max_scroll_pos <= 1:
+            return self.body_base
+        y2, y1 = self.scroll_view_size-1, 1
+        x2, x1 = self.max_scroll_pos, 1
+        x = self.scroll_pos
+        pos = y1 + (y2-y1)*(x-x1)/(x2-x1)
+        return min(self.body_base + int(max(pos, 0)), self.rows-1)
+
+    def _scroll_indicator_col(self):
+        """ Compute the absolute scroll indicator col:
+        - We want the left to be only when scroll_pos==0
+        - We want the right to be only when scroll_pos=max_scroll_pos-1
+        """
+        if self.pick_mode:
+            return self._calc_indicator(
+                self.pick_pos, 0, self.body.row_cnt-1, 0, self.cols-1)
+        return self._calc_indicator(
+            self.scroll_pos, 0, self.max_scroll_pos, 0, self.cols-1)
+
+    def _calc_indicator(self, pos, pos0, pos9, ind0, ind9):
+        if self.max_scroll_pos <= 0:
+            return -1 # not scrollable
+        if pos9 - pos0 <= 0:
+            return -1 # not scrollable
+        if pos <= pos0:
+            return ind0
+        if pos >= pos9:
+            return ind9
+        ind = int(round(ind0 + (ind9-ind0+1)*(pos-pos0)/(pos9-pos0+1)))
+        return min(max(ind, ind0+1), ind9-1)
+
+    def render(self):
+        """Draw everything added. In a loop cuz curses is a
+        piece of shit."""
+        for _ in range(128):
+            try:
+                self.render_once()
+                return
+            except curses.error:
+                time.sleep(0.16)
+                self._set_screen_dims()
+                continue
+        try:
+            self.render_once()
+        except Exception:
+            ConsoleWindow.stop_curses()
+            print(f"""curses err:
+    head.row_cnt={self.head.row_cnt}
+    head.view_cnt={self.head.view_cnt}
+    hor_line_cnt={self.hor_line_cnt}
+    body.row_cnt={self.body.row_cnt}
+    scroll_pos={self.scroll_pos}
+    max_scroll_pos={self.max_scroll_pos}
+    pick_pos={self.pick_pos}
+    last_pick_pos={self.last_pick_pos}
+    pick_mode={self.pick_mode}
+    pick_size={self.pick_size}
+    rows={self.rows}
+    cols={self.cols}
+""")
+            raise
+
+
+    def fix_positions(self, delta=0):
+        """ Ensure the vertical positions are on the playing field """
+        self.calc()
+        # if self.scroll_view_size <= 0:
+            # self.scr.refresh()
+        if self.pick_mode:
+            self.pick_pos += delta
+        else:
+            self.scroll_pos += delta
+            self.pick_pos += delta
+
+        indent = 0
+        if self.body_base < self.rows:
+            ind_pos = 0 if self.pick_mode else self._scroll_indicator_row()
+            if self.pick_mode:
+                self.pick_pos = max(self.pick_pos, 0)
+                self.pick_pos = min(self.pick_pos, self.body.row_cnt-1)
+                if self.pick_pos >= 0:
+                    self.pick_pos -= (self.pick_pos % self.pick_size)
+                if self.pick_pos < 0:
+                    self.scroll_pos = 0
+                elif self.scroll_pos > self.pick_pos:
+                    # light position is below body bottom
+                    self.scroll_pos = self.pick_pos
+                elif self.scroll_pos < self.pick_pos - (self.scroll_view_size - self.pick_size):
+                    # light position is above body top
+                    self.scroll_pos = self.pick_pos - (self.scroll_view_size - self.pick_size)
+                self.scroll_pos = max(self.scroll_pos, 0)
+                self.scroll_pos = min(self.scroll_pos, self.max_scroll_pos)
+                indent = 1
+            else:
+                self.scroll_pos = max(self.scroll_pos, 0)
+                self.scroll_pos = min(self.scroll_pos, self.max_scroll_pos)
+                self.pick_pos = self.scroll_pos + ind_pos - self.body_base
+                # indent = 1 if self.body.row_cnt > self.scroll_view_size else 0
+        return indent
+
+    def render_once(self):
+        """Draw everything added."""
+
+        indent = self.fix_positions()
+
+        if indent > 0 and self.pick_mode:
+            self.scr.vline(self.body_base, 0, ' ', self.scroll_view_size)
+            if self.pick_pos >= 0:
+                pos = self.pick_pos - self.scroll_pos + self.body_base
+                self.scr.addstr(pos, 0, '>', curses.A_REVERSE)
+
+        if self.head.view_cnt < self.rows:
+            self.scr.hline(self.head.view_cnt, 0, curses.ACS_HLINE, self.cols)
+            ind_pos = self._scroll_indicator_col()
+            if ind_pos >= 0:
+                bot, cnt = ind_pos, 1
+                if 0 < ind_pos < self.cols-1:
+                    width = self.scroll_view_size/self.body.row_cnt*self.cols
+                    bot = max(int(round(ind_pos-width/2)), 1)
+                    top = min(int(round(ind_pos+width/2)), self.cols-1)
+                    cnt = top - bot
+                # self.scr.addstr(self.head.view_cnt, bot, '-'*cnt, curses.A_REVERSE)
+                # self.scr.hline(self.head.view_cnt, bot, curses.ACS_HLINE, curses.A_REVERSE, cnt)
+                for idx in range(bot, bot+cnt):
+                    self.scr.addch(self.head.view_cnt, idx, curses.ACS_HLINE, curses.A_REVERSE)
+
+        self.scr.refresh()
+
+        if self.body_base < self.rows:
+            if self.pick_mode:
+                self.highlight_picked()
+            self.body.pad.refresh(self.scroll_pos, 0,
+                  self.body_base, indent, self.rows-1, self.cols-1)
+
+        if self.rows > 0:
+            last_row = min(self.head.view_cnt, self.rows)-1
+            if last_row >= 0:
+                self.head.pad.refresh(0, 0, 0, indent, last_row, self.cols-1)
+
+
+
+    def answer(self, prompt='Type string [then Enter]', seed='', width=80):
+        """
+        Popup with manual text input handling for unlimited length.
+        
+        This function replaces the curses.textpad.Textbox to handle arbitrarily
+        long strings by managing a separate input buffer and display window.
+        """
+        input_string = list(seed)
+        cursor_pos = len(input_string)
+        
+        if self.rows < 3 or self.cols < 30:
+            return seed
+
+        # Define the display window properties
+        max_display_width = self.cols - 6
+        text_win_width = min(width, max_display_width)
+
+        row0, row9 = self.rows // 2 - 1, self.rows // 2 + 1
+        col0 = (self.cols - (text_win_width + 2)) // 2
+
+        while True:
+            self.scr.clear()
+            rectangle(self.scr, row0, col0, row9, col0 + text_win_width + 1)
+            self.scr.addstr(row0, col0 + 1, prompt[:text_win_width])
+            
+            # Calculate the visible portion of the string
+            start_pos = max(0, cursor_pos - text_win_width + 1)
+            end_pos = start_pos + text_win_width
+            display_str = "".join(input_string[start_pos:end_pos])
+            
+            self.scr.addstr(row0 + 1, col0 + 1, display_str)
+            
+            # Position the cursor
+            display_cursor_pos = cursor_pos - start_pos
+            self.scr.move(row0 + 1, col0 + 1 + display_cursor_pos)
+            
+            ending = 'Press ENTER to submit'[:text_win_width]
+            self.scr.addstr(row9, col0 + 1 + text_win_width - len(ending), ending)
+            self.scr.refresh()
+            curses.curs_set(2)
+            
+            key = self.scr.getch()
+            
+            if key in [10, 13]:  # Enter key
+                return "".join(input_string)
+            elif key in [curses.KEY_BACKSPACE, 127, 8]:  # Backspace
+                if cursor_pos > 0:
+                    input_string.pop(cursor_pos - 1)
+                    cursor_pos -= 1
+            elif key == curses.KEY_LEFT:
+                cursor_pos = max(0, cursor_pos - 1)
+            elif key == curses.KEY_RIGHT:
+                cursor_pos = min(len(input_string), cursor_pos + 1)
+            elif key == curses.KEY_DC:  # Delete
+                if cursor_pos < len(input_string):
+                    input_string.pop(cursor_pos)
+            elif key == curses.KEY_HOME:
+                cursor_pos = 0
+            elif key == curses.KEY_END:
+                cursor_pos = len(input_string)
+            elif 32 <= key <= 126:  # Printable ASCII characters
+                input_string.insert(cursor_pos, chr(key))
+                cursor_pos += 1
+
+    def alert(self, title='ALERT', message='', height=1, width=80):
+        """Alert box"""
+        def mod_key(key):
+            return  7 if key in (10, curses.KEY_ENTER) else key
+
+        # need 3 extra cols for rectangle (so we don't draw in southeast corner)
+        # and 3 rows (top/prompt/bottom)
+        #      +Prompt---    -----------------+
+        #      | First line for message...    |
+        #      | Last line for message.       |
+        #      +-----------Press ENTER  to ack+
+        if self.rows < 2+height or self.cols < 30:
+            return
+        width = min(width, self.cols-3) # max text width
+        row0 = (self.rows+height-1)//2 - 1
+        row9 = row0 + height + 1
+        col0 = (self.cols - (width+2)) // 2
+        col9 = col0 + width + 2 - 1
+
+        self.scr.clear()
+        for row in range(self.rows):
+            self.scr.insstr(row, 0, ' '*self.cols, curses.A_REVERSE)
+        pad = curses.newpad(20, 200)
+        win = curses.newwin(1, 1, row9-1, col9-2) # input window
+        rectangle(self.scr, row0, col0, row9, col9)
+        self.scr.addstr(row0, col0+1, title[0:width], curses.A_REVERSE)
+        pad.addstr(message)
+        ending = 'Press ENTER to ack'[:width]
+        self.scr.addstr(row9, col0+1+width-len(ending), ending)
+        self.scr.refresh()
+        pad.refresh(0, 0, row0+1, col0+1, row9-1, col9-1)
+        Textbox(win).edit(mod_key).strip()
+        return
+
+    def clear(self):
+        """Clear in prep for new screen"""
+        self.scr.clear()
+        self.head.pad.clear()
+        self.body.pad.clear()
+        self.head.texts, self.body.texts, self.last_pick_pos = [], [], -1
+        self.head.row_cnt = self.body.row_cnt = 0
+
+    def prompt(self, seconds=1.0):
+        """Here is where we sleep waiting for commands or timeout"""
+        ctl_b, ctl_d, ctl_f, ctl_u = 2, 4, 6, 21
+        elapsed = 0.0
+        while elapsed < seconds:
+            key = self.scr.getch()
+            if key == curses.ERR:
+                elapsed += self.timeout_ms / 1000
+                continue
+            if key in (curses.KEY_RESIZE, ) or curses.is_term_resized(self.rows, self.cols):
+                # self.scr.erase()
+                self._set_screen_dims()
+                # self.render()
+                break
+
+            # App keys...
+            if key in self.handled_keys:
+                return key # return for handling
+
+            # Navigation Keys...
+            pos = self.pick_pos if self.pick_mode else self.scroll_pos
+            delta = self.pick_size if self.pick_mode else 1
+            was_pos = pos
+            if key in (ord('k'), curses.KEY_UP):
+                pos -= delta
+            elif key in (ord('j'), curses.KEY_DOWN):
+                pos += delta
+            elif key in (ctl_b, curses.KEY_PPAGE):
+                pos -= self.scroll_view_size
+            elif key in (ctl_u, ):
+                pos -= self.scroll_view_size//2
+            elif key in (ctl_f, curses.KEY_NPAGE):
+                pos += self.scroll_view_size
+            elif key in (ctl_d, ):
+                pos += self.scroll_view_size//2
+            elif key in (ord('0'), curses.KEY_HOME):
+                pos = 0
+            elif key in (ord('$'), curses.KEY_END):
+                pos = self.body.row_cnt - 1
+            elif key in (ord('H'), ):
+                pos = self.scroll_pos
+            elif key in (ord('M'), ):
+                pos = self.scroll_pos + self.scroll_view_size//2
+            elif key in (ord('L'), ):
+                pos = self.scroll_pos + self.scroll_view_size-1
+
+            if self.pick_mode:
+                self.pick_pos = pos
+            else:
+                self.scroll_pos = pos
+                self.pick_pos = pos
+
+            self.fix_positions()
+
+            if pos != was_pos:
+                self.render()
+            # ignore unhandled keys
+        return None
+
+def no_runner():
+    """Appease sbrun"""
+
+if __name__ == '__main__':
+    def main():
+        """Test program"""
+        def do_key(key):
+            nonlocal spin, win, opts
+            value = spin.do_key(key, win)
+            if key in (ord('p'), ord('s')):
+                win.set_pick_mode(on=opts.pick_mode, pick_size=opts.pick_size)
+            elif key == ord('n'):
+                win.alert(title='Info', message=f'got: {value}')
+            return value
+
+        spin = OptionSpinner()
+        spin.add_key('help_mode', '? - toggle help screen', vals=[False, True])
+        spin.add_key('pick_mode', 'p - toggle pick mode', vals=[False, True])
+        spin.add_key('pick_size', 's - #rows in pick', vals=[1, 2, 3])
+        spin.add_key('name', 'n - select name', prompt='Provide Your Name:')
+        spin.add_key('mult', 'm - row multiplier', vals=[0.5, 0.9, 1.0, 1.1, 2, 4, 16])
+        opts = spin.default_obj
+
+        win = ConsoleWindow(head_line=True, keys=spin.keys)
+        opts.name = "[hit 'n' to enter name]"
+        for loop in range(100000000000):
+            body_size = int(round(win.scroll_view_size*opts.mult))
+            if opts.help_mode:
+                win.set_pick_mode(False)
+                spin.show_help_nav_keys(win)
+                spin.show_help_body(win)
+            else:
+                win.set_pick_mode(opts.pick_mode, opts.pick_size)
+                win.add_header(f'Header: {loop} "{opts.name}"')
+                for idx, line in enumerate(range(body_size//opts.pick_size)):
+                    win.add_body(f'Main pick: {loop}.{line}')
+                    for num in range(1, opts.pick_size):
+                        win.draw(num+idx*opts.pick_size, 0, f'  addon: {loop}.{line}')
+            win.render()
+            _ = do_key(win.prompt(seconds=5))
+            win.clear()
+
+    try:
+        main()
+    except KeyboardInterrupt:
+        pass
+    except Exception as exce:
+        ConsoleWindow.stop_curses()
+        print("exception:", str(exce))
+        print(traceback.format_exc())
+        if dump_str:
+            print(dump_str)

console_window-1.0.0/console_window/__init__.py

@@ -0,0 +1 @@
+from .ConsoleWindow import ConsoleWindow, OptionSpinner

console_window-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+# pyproject.toml
+# TEST basic imports
+#    python -m venv test_venv
+#    source test_venv/bin/activate
+#    python3 -m venv test_venv
+#    source test_venv/bin/activate
+#    pip install dist/console_window-0.1.0-py3-none-any.whl
+#    python3 # within, from console_window import ConsoleWindow
+#    deactivate
+#    rm -rf test_venv/
+
+
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+# ----------------------------------------------------------------------
+# FLIT MODULE CONFIGURATION
+[tool.flit.module]
+name = "console_window"
+
+# ----------------------------------------------------------------------
+# UNIFIED PROJECT METADATA (Replaces [tool.flit.metadata])
+[project]
+name = "console-window" 
+version = "1.0.0"
+description = "A robust curses wrapper for creating Text User Interfaces (TUIs)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {file = "LICENSE"}
+
+dependencies = [
+    # "dependency-name >= version", 
+]
+
+authors = [
+    {name = "Joe Defen", email = "joedef@duck.com"},
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Topic :: Terminals",
+    "Topic :: Software Development :: User Interfaces",
+]