console-window 1.3.2__tar.gz → 1.3.3__tar.gz

console_window-1.3.3/ConsoleWindowDemo.py

@@ -0,0 +1,559 @@
+#!/usr/bin/env python3
+"""
+ConsoleWindow Comprehensive Demo
+
+This demo showcases the main features of ConsoleWindow:
+- OptionSpinner for cycling through choices and triggering actions
+- Screen classes (Main, Help, History, Theme)
+- IncrementalSearchBar for inline filtering in header
+- InlineConfirmation for inline prompts
+- Theme/color support
+- Flash and answer methods for user feedback
+
+Usage:
+    .venv/bin/python3 demo.py
+
+    Or activate the venv first:
+    source .venv/bin/activate
+    python3 demo.py
+
+Features demonstrated:
+    - Press q to quit
+    - Navigate with arrow keys or j/k
+    - Press v to cycle view modes (compact/detailed/full)
+    - Press s to cycle sort options (name/uid/home)
+    - Press / to filter items (inline search bar)
+    - Press SPACE to select an item (inline confirmation)
+    - Press a to demo the answer() prompt
+    - Press l to demo the alert() popup
+    - Press ? for help screen
+    - Press h for history screen
+    - Press t for themes (and cycle themes with t on theme screen)
+"""
+# python: disable=invalid-name
+
+import sys
+import time
+import traceback
+import curses as cs
+from types import SimpleNamespace
+from console_window import (
+    ConsoleWindow, ConsoleWindowOpts, OptionSpinner,
+    IncrementalSearchBar, InlineConfirmation, Theme,
+    Screen, ScreenStack, Context
+)
+
+# Screen IDs
+MAIN_ST = 0
+HELP_ST = 1
+HISTORY_ST = 2
+THEME_ST = 3
+SCREEN_NAMES = ('MAIN', 'HELP', 'HISTORY', 'THEMES')
+
+
+class DemoApp:
+    """Main demo application"""
+    singleton = None
+
+    def __init__(self):
+        DemoApp.singleton = self
+        self.win = None
+        self.spin = None
+        self.stack = None
+        self.items = []  # Items to display in main screen
+        self.filter_text = ''
+        self.selected_items = set()  # Track "selected" items for demo
+        self.operation_count = 0
+
+        # Inline confirmation handler
+        self.confirmation = InlineConfirmation()
+
+        # Incremental search bar
+        self.filter_bar = IncrementalSearchBar(
+            on_change=self._on_filter_change,
+            on_accept=self._on_filter_accept,
+            on_cancel=self._on_filter_cancel
+        )
+
+        # IMPORTANT: Create opts BEFORE ScreenStack to ensure proper object linking
+        # The OptionSpinner will use stack.obj, so it must be set correctly from the start
+        self.opts = SimpleNamespace()
+
+        # Create screen instances
+        screens = self.screens = {
+            MAIN_ST: MainScreen(self),
+            HELP_ST: HelpScreen(self),
+            HISTORY_ST: HistoryScreen(self),
+            THEME_ST: ThemeScreen(self),
+        }
+
+        # Configure console window
+        win_opts = ConsoleWindowOpts(
+            head_line=True,
+            body_rows=200,
+            head_rows=4,
+            min_cols_rows=(60,10),
+            pick_attr=cs.A_REVERSE,
+            ctrl_c_terminates=True,
+        )
+
+        self.win = ConsoleWindow(opts=win_opts,)
+        # Pass self.opts as spins_obj so stack.obj points to the right object
+        self.stack = ScreenStack(self.win, self.opts, SCREEN_NAMES, screens)
+
+        # Setup option spinner - it will inherit stack.obj (self.opts)
+        spin = self.spin = OptionSpinner(stack=self.stack)
+        themes = Theme.list_all()
+
+        # Add view mode and sort options
+        spin.add_key('quit', 'q - quit', genre='action')
+        spin.add_key('escape', 'ESC,ENTER - back',
+                     keys=[27,10,cs.KEY_ENTER], genre='action')
+        spin.add_key('view_mode', 'v - view mode',
+                     vals=['compact', 'detailed', 'full'], scope={MAIN_ST})
+        spin.add_key('sort_by', 's - sort by',
+                     vals=['name', 'uid', 'home'], scope={MAIN_ST})
+        spin.add_key('theme', 't - theme', vals=themes, scope={THEME_ST})
+
+        # Add navigation keys (global)
+        spin.add_key('help_screen', '? - help', genre='action', scope={MAIN_ST})
+        spin.add_key('history_screen', 'h - history', genre='action', scope={MAIN_ST})
+        spin.add_key('theme_screen', 't - Theme Screen', genre='action', scope={MAIN_ST})
+
+        # Add main screen actions
+        spin.add_key('filter', '/ - filter', genre='action', scope={MAIN_ST})
+        spin.add_key('clear_filter', 'ESC - clear filter',
+                     keys=[27], genre='action', scope=MAIN_ST)
+        spin.add_key('select', 'SPACE - select', keys=[ord(' ')],
+                     genre='action', scope={MAIN_ST})
+        spin.add_key('answer_demo', 'a - answer demo',
+                     genre='action', scope={MAIN_ST})
+        spin.add_key('alert_demo', 'l - alert demo',
+                     genre='action', scope={MAIN_ST})
+        self.win.set_handled_keys(spin.keys)
+
+
+
+        # Load sample data from /etc/passwd
+        self._load_sample_data()
+
+    def _load_sample_data(self):
+        """Load sample items from /etc/passwd"""
+        try:
+            with open('/etc/passwd', 'r', encoding='utf-8') as f:
+                for line in f:
+                    if line.strip() and not line.startswith('#'):
+                        parts = line.split(':')
+                        if len(parts) >= 3:
+                            username = parts[0]
+                            uid = parts[2]
+                            home = parts[5] if len(parts) > 5 else ''
+                            self.items.append({
+                                'username': username,
+                                'uid': uid,
+                                'home': home,
+                                'line': line.strip()
+                            })
+        except Exception:
+            # Fallback sample data
+            self.items = [
+                {'username': 'demo1', 'uid': '1001', 'home': '/home/demo1',
+                 'line': 'demo1:x:1001:1001::/home/demo1:/bin/bash'},
+                {'username': 'demo2', 'uid': '1002', 'home': '/home/demo2',
+                 'line': 'demo2:x:1002:1002::/home/demo2:/bin/bash'},
+                {'username': 'test', 'uid': '1003', 'home': '/home/test',
+                 'line': 'test:x:1003:1003::/home/test:/bin/bash'},
+            ]
+
+    def _on_filter_change(self, text):
+        """Update filter as user types"""
+        self.filter_text = text.lower()
+
+    def _on_filter_accept(self, text):
+        """Filter accepted (ENTER pressed)"""
+        self.filter_text = text.lower()
+        self.win.passthrough_mode = False
+        self.win.pick_pos = 0  # Move to top
+
+    def _on_filter_cancel(self, original_text):
+        """Filter cancelled (ESC pressed)"""
+        self.filter_text = original_text.lower() if original_text else ''
+        self.win.passthrough_mode = False
+
+    def _start_operation(self):
+        """Start operation after confirmation"""
+        if self.confirmation.partition_name:
+            item_name = self.confirmation.partition_name
+            # Mark item as "processed"
+            self.selected_items.add(item_name)
+            self.operation_count += 1
+            # Flash success message
+            self.win.flash(f'✓ Processed {item_name}', duration=1.5)
+        self.confirmation.cancel()
+        self.win.passthrough_mode = False
+
+    def handle_key(self, key):
+        """Handle global key presses - ORDER MATTERS!"""
+        # Handle filter bar FIRST (highest priority when active)
+        if self.filter_bar.is_active:
+            if self.filter_bar.handle_key(key):
+                return None  # Key was consumed
+
+        # Handle confirmation mode SECOND (high priority when active)
+        if self.confirmation.active:
+            result = self.confirmation.handle_key(key)
+            if result == 'confirmed':
+                self._start_operation()
+            elif result == 'cancelled':
+                self.confirmation.cancel()
+                self.win.passthrough_mode = False
+            return None  # Key was consumed by confirmation
+
+        # Handle ENTER for screen navigation
+        if key in (cs.KEY_ENTER, 10):
+            if self.stack.curr.num != MAIN_ST:
+                self.stack.pop()
+                return None
+
+        # Handle spinner keys LAST (normal priority)
+        if key in self.spin.keys:
+            self.spin.do_key(key, self.win)
+
+        return None
+
+    def get_filtered_items(self):
+        """Get items matching current filter"""
+        if not self.filter_text:
+            return self.items
+        return [item for item in self.items
+                if self.filter_text in item['username'].lower() or
+                   self.filter_text in item['home'].lower()]
+
+    def do_key(self, key):
+        """ TBD """
+        if not key:
+            return
+        # handle Inline confirmation / filter
+        if key in self.spin.keys:
+            self.spin.do_key(key, self.win)
+
+    def main_loop(self):
+        """Main application loop"""
+
+        while True:
+            current_screen = self.screens[self.stack.curr.num]
+            current_screen.draw_screen()
+            self.win.render()
+
+            key = self.win.prompt(seconds=3.0)
+            if key:
+                self.handle_key(key)
+            self.stack.perform_actions(self.spin)
+            self.win.clear()
+
+
+class DemoScreen(Screen):
+    """Base screen class for demo screens"""
+    app: DemoApp
+
+    def __init__(self, name, app):
+        super().__init__(app)
+        self.app = app
+
+    def get_spinner(self):
+        """Get the option spinner"""
+        return self.app.spin if hasattr(self.app, 'spin') else None
+
+    def escape_ACTION(self):
+        """ go back """
+        app = self.app
+        app.stack.pop()
+
+    def quit_ACTION(self):
+        """Quit the application"""
+        app = self.app
+        win = app.win
+
+        if app.operation_count > 0:
+            win.flash(
+                f'Processed {app.operation_count} items. Goodbye!',
+                duration=1.5
+            )
+            time.sleep(1.5)
+        win.stop_curses()
+        sys.exit(0)
+
+class MainScreen(DemoScreen):
+    """Main screen showing user list"""
+
+    def __init__(self, app):
+        super().__init__('MAIN', app)
+
+    def draw_screen(self):
+        """Draw main screen with item list"""
+        self.app.win.set_pick_mode(True)
+
+        self._draw_body()
+        self._draw_header()
+
+    def _draw_body(self):
+        """  Display items """
+        app = self.app
+        items = app.get_filtered_items()
+        by = app.opts.sort_by
+        by = 'username' if by == 'name' else by
+        items = sorted(items, key=lambda it: it[by])
+        view_mode = app.opts.view_mode
+        for item in items:
+            username = item['username']
+            uid = item['uid']
+            home = item['home']
+
+            # Determine status and color
+            if username in app.selected_items:
+                status = '✓ Processed'
+                attr = cs.color_pair(Theme.SUCCESS)
+            else:
+                status = '  Ready'
+                attr = cs.color_pair(0)
+
+            # Format line based on view mode
+            if view_mode == 'full':
+                line = f'{username:<16} {uid:<8} {home:<30} {status}'
+            elif view_mode == 'detailed':
+                line = f'{username:<16} {uid:<8} {status}'
+            else:  # compact
+                line = f'{username:<20} {status}'
+
+            # Create context for picking
+            ctx = Context(genre='item', item=item)
+            app.win.add_body(line, attr=attr, context=ctx)
+
+            # Show inline confirmation if active for this item
+            if app.confirmation.active and \
+               app.confirmation.partition_name == username:
+                msg = f'    ⚠️  Process {username}?'
+                if app.confirmation.mode == 'y':
+                    msg += " - Press 'y' or ESC"
+                elif app.confirmation.mode == 'Y':
+                    msg += " - Press 'Y' or ESC"
+
+                app.win.add_body(
+                    msg,
+                    attr=cs.color_pair(Theme.WARNING) | cs.A_BOLD,
+                    context=Context(genre='DECOR')
+                )
+
+    def _draw_header(self):
+        app = self.app
+        # Build header with filter display using fancy_header for compact formatting
+        line = app.filter_bar.get_display_string(prefix='/')
+        if not line:
+            line = '/'
+        # Use fancy_header to show filter with bold/underline formatting
+
+        # Show spinner keys
+        line += f' [v]iew={app.opts.view_mode}'
+        line += f' [s]ort={app.opts.sort_by}'
+        line += ' [a]nsDemo'
+        line += ' l:alrtDemo'
+        line += ' SPC:process'
+        line += ' [t]hemes'
+        line += ' [h]ist'
+        line += ' ?:help'
+        app.win.add_fancy_header(f'  {line}', mode="Underline")
+
+        # Column headers
+        view_mode = app.opts.view_mode
+        if view_mode == 'full':
+            header = f'{"User":<16} {"UID":<8} {"Home":<30} Status'
+        elif view_mode == 'detailed':
+            header = f'{"User":<16} {"UID":<8} Status'
+        else:  # compact
+            header = f'{"User":<20} Status'
+
+        app.win.add_header(header, attr=cs.A_DIM | cs.A_UNDERLINE)
+
+    def filter_ACTION(self):
+        """Activate filter search bar"""
+        app = self.app
+        app.filter_bar.start(app.filter_text)
+        app.win.passthrough_mode = True
+
+    def clear_filter_ACTION(self):
+        """Clear filter search bar"""
+        app = self.app
+        app.filter_bar._text = ''
+        app.filter_text = ''
+        app.win.pick_pos = 0
+
+    def select_ACTION(self):
+        """Select/process the current item with confirmation"""
+        app = self.app
+        ctx = app.win.get_picked_context()
+        if ctx and hasattr(ctx, 'item'):
+            item = ctx.item
+            username = item['username']
+            # Start inline confirmation (mode 'y' = press 'y' to confirm)
+            app.confirmation.start('process', username, mode='y')
+            app.win.passthrough_mode = True
+
+    def answer_demo_ACTION(self):
+        """Demo the answer() method"""
+        app = self.app
+        win = app.win
+        response = win.answer('Enter your name (or ESC to cancel): ',
+                              height=1)
+        if response:
+            win.flash(f'Hello, {response}!', duration=2.0)
+        else:
+            win.flash('Cancelled', duration=1.0)
+
+    def alert_demo_ACTION(self):
+        """Demo the alert() method - shows a simple modal message box"""
+        ctx = self.app.win.get_picked_context()
+        if ctx and hasattr(ctx, 'item'):
+            item = ctx.item
+            # alert() displays a single-paragraph message (newlines are ignored)
+            # Keep it simple and short
+            message = (
+                f"Selected user: {item['username']} "
+                f"(UID: {item['uid']}) "
+                f"Home: {item['home']}"
+            )
+            self.app.win.alert(message, title='User Info')
+        else:
+            self.app.win.alert(
+                'No item selected! Please select an item from the list first.',
+                title='Selection Required'
+            )
+
+    def help_screen_ACTION(self):
+        """Navigate to help screen"""
+        self.app.stack.push(HELP_ST, self.app.win.pick_pos)
+
+    def history_screen_ACTION(self):
+        """Navigate to history screen"""
+        app = self.app
+        win = app.win
+        app.stack.push(HISTORY_ST, win.pick_pos)
+
+    def theme_screen_ACTION(self):
+        """Navigate to theme screen"""
+        app = self.app
+        win = app.win
+        app.stack.push(THEME_ST, win.pick_pos)
+
+
+class HelpScreen(DemoScreen):
+    """Help screen"""
+
+    def __init__(self, app):
+        super().__init__('HELP', app)
+
+    def draw_screen(self):
+        """Draw help screen"""
+        app = self.app
+        app.win.set_pick_mode(False)
+
+        spinner = self.get_spinner()
+        if spinner:
+            # Use built-in help display
+            spinner.show_help_nav_keys(app.win)
+            spinner.show_help_body(app.win)
+
+
+class HistoryScreen(DemoScreen):
+    """History screen showing operation log"""
+
+    def __init__(self, app):
+        super().__init__('HISTORY', app)
+
+    def draw_screen(self):
+        """Draw history screen"""
+        app = self.app
+        app.win.set_pick_mode(False)
+
+        app.win.add_header('OPERATION HISTORY', attr=cs.A_BOLD)
+        app.win.add_header('  Press ESC or ENTER to return',
+                          attr=cs.A_DIM, resume=True)
+
+        if app.selected_items:
+            app.win.add_body('')
+            app.win.add_body(f'Total processed items: {len(app.selected_items)}')
+            app.win.add_body('')
+            for username in sorted(app.selected_items):
+                # Find the item details
+                item = next((i for i in app.items
+                           if i['username'] == username), None)
+                if item:
+                    line = f'  ✓ {username:<16} uid={item["uid"]:<8} {item["home"]}'
+                    app.win.add_body(line, attr=cs.color_pair(Theme.SUCCESS))
+        else:
+            app.win.add_body('')
+            app.win.add_body('No items have been processed yet.')
+            app.win.add_body('')
+            app.win.add_body('Go back to the main screen and press '
+                           'SPACE on an item to process it.')
+
+
+class ThemeScreen(DemoScreen):
+    """Theme selection screen"""
+
+    def __init__(self, app):
+        super().__init__('THEMES', app)
+
+    def draw_screen(self):
+        """Draw theme screen with color samples"""
+        app = self.app
+        win = app.win
+        win.set_pick_mode(False)
+        if app.opts.theme != Theme.get_current():
+            Theme.set(app.opts.theme)
+
+        theme = app.opts.theme
+        win.add_header(f'COLOR THEMES: [t]heme={theme}',
+                          attr=cs.A_BOLD)
+        win.add_header('  ESC:return', attr=cs.A_DIM, resume=True)
+
+        win.add_body('Color samples:')
+        win.add_body('')
+
+        # Color samples
+        color_samples = [
+            (Theme.DANGER, 'DANGER', 'Destructive operations'),
+            (Theme.SUCCESS, 'SUCCESS', 'Completed operations'),
+            (Theme.WARNING, 'WARNING', 'Warnings and cautions'),
+            (Theme.INFO, 'INFO', 'Informational messages'),
+            (Theme.EMPHASIS, 'EMPHASIS', 'Emphasized text'),
+            (Theme.ERROR, 'ERROR', 'Error messages'),
+            (Theme.PROGRESS, 'PROGRESS', 'Progress indicators'),
+        ]
+
+        for color_id, label, description in color_samples:
+            line = f'  {label:<12} ████████  {description}'
+            win.add_body(line, attr=cs.color_pair(color_id))
+
+    def theme_screen(self):
+        """Cycle to next theme"""
+        themes = Theme.list_all()
+        current = Theme.get_current()
+        idx = themes.index(current) if current in themes else -1
+        next_theme = themes[(idx + 1) % len(themes)]
+        Theme.set(next_theme)
+
+def main():
+    """Main entry point"""
+    try:
+        app = DemoApp()
+        app.main_loop()
+    except Exception as bummer:
+        app = DemoApp.singleton
+        if app and app.win:
+            app.win.stop_curses()
+        print('exception: ', str(bummer))
+        print(traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

{console_window-1.3.2 → console_window-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 1.3.2
+Version: 1.3.3
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.8
@@ -130,6 +130,4 @@ For more extensive examples, you can look at some projects using `console-window
   * viewer of /proc/meminfo that shows historical values
 * [vappman](https://github.com/joedefen/vappman)
   * convenince wrapper to mostly hide CLI of [AppMan](https://github.com/ivan-hc/AppMan), a life-cycle manager for 2000+ AppImages
-* [my-snaps](https://github.com/joedefen/my-snaps)
-  * special purpose BTRFS snap manager
 

{console_window-1.3.2 → console_window-1.3.3}/README.md

@@ -115,5 +115,3 @@ For more extensive examples, you can look at some projects using `console-window
   * viewer of /proc/meminfo that shows historical values
 * [vappman](https://github.com/joedefen/vappman)
   * convenince wrapper to mostly hide CLI of [AppMan](https://github.com/ivan-hc/AppMan), a life-cycle manager for 2000+ AppImages
-* [my-snaps](https://github.com/joedefen/my-snaps)
-  * special purpose BTRFS snap manager

{console_window-1.3.2 → console_window-1.3.3}/console_window/ConsoleWindow.py

@@ -265,6 +265,70 @@ class Theme:
 
         return True
 
+    @classmethod
+    def create_picker_screen(cls, base_class):
+        """
+        Create a theme picker screen class dynamically.
+
+        Args:
+            base_class: The Screen base class to inherit from
+
+        Returns:
+            A new class that displays all themes and allows cycling through them
+
+        Usage:
+            ThemeScreen = Theme.create_picker_screen(Screen)
+            screens[THEME_ST] = ThemeScreen(app)
+        """
+        class ThemePickerScreen(base_class):
+            """Theme preview screen showing all available themes with color examples"""
+
+            def draw_screen(self):
+                """Draw the theme screen with color examples for all themes"""
+                app = self.app
+                win = app.win
+
+                win.set_pick_mode(False)
+
+                # Get current theme name (may be empty string for default)
+                current_theme = cls.get_current()
+                display_theme = current_theme if current_theme else '(default)'
+
+                # Add header showing current theme
+                win.add_header(f'COLOR THEME:  {display_theme:^18}', attr=curses.A_BOLD)
+                win.add_header('   Press [t] to cycle themes, ESC to return', resume=True)
+
+                # Color purpose labels
+                color_labels = [
+                    (cls.DANGER, 'DANGER', 'Destructive operations'),
+                    (cls.SUCCESS, 'SUCCESS', 'Completed operations'),
+                    (cls.OLD_SUCCESS, 'OLD_SUCCESS', 'Older completed operations'),
+                    (cls.WARNING, 'WARNING', 'Caution/stopped states'),
+                    (cls.INFO, 'INFO', 'Informational states'),
+                    (cls.EMPHASIS, 'EMPHASIS', 'Emphasized text'),
+                    (cls.ERROR, 'ERROR', 'Errors'),
+                    (cls.PROGRESS, 'PROGRESS', 'Progress indicators'),
+                    (cls.HOTSWAP, 'HOTSWAP', 'Recently added items'),
+                ]
+
+                # Show color examples for this theme
+                for color_id, label, description in color_labels:
+                    # Create line with colored block and description
+                    line = f'{label:12} ████████  {description}'
+                    attr = curses.color_pair(color_id)
+                    win.add_body(line, attr=attr)
+
+            def spin_theme_ACTION(self):
+                """Handle 't' key - cycle through themes"""
+                vals = cls.list_all()
+                value = cls.get_current()
+                idx = vals.index(value) if value in vals else -1
+                value = vals[(idx+1) % len(vals)]  # choose next
+                cls.set(value)
+                self.app.opts.theme = value
+
+        return ThemePickerScreen
+
 
 class Context:
     """
@@ -337,7 +401,7 @@ class ConsoleWindowOpts:
                  'pick_mode', 'pick_size', 'mod_pick', 'pick_attr', 'pick_range', 'ctrl_c_terminates',
                  'return_if_pos_change', 'min_cols_rows', 'dialog_abort', 'dialog_return',
                  'single_cell_scroll_indicator', 'answer_show_redraws', 'strip_attrs_in_pick_mode',
-                 'demo_mode']
+                 'demo_mode', 'relax_handled_keys']
 
     def __init__(self, **kwargs):
         """
@@ -360,6 +424,7 @@ class ConsoleWindowOpts:
         :param dialog_return: Which key submits dialogs: "ENTER", "TAB" (default: "ENTER")
         :param single_cell_scroll_indicator: If True, shows single-cell position dot; if False, shows proportional range (default: False)
         :param strip_attrs_in_pick_mode: If True, strips attributes in pick mode (old behavior); if False, preserves them (default: False)
+        :param relax_handled_keys: If True, passes all non-navigation keys to app without checking handled_keys list (default: True)
         """
         self.head_line = kwargs.get('head_line', True)
         self.head_rows = kwargs.get('head_rows', 50)
@@ -380,6 +445,7 @@ class ConsoleWindowOpts:
         self.answer_show_redraws = kwargs.get('answer_show_redraws', False)
         self.strip_attrs_in_pick_mode = kwargs.get('strip_attrs_in_pick_mode', False)
         self.demo_mode = kwargs.get('demo_mode', False)
+        self.relax_handled_keys = kwargs.get('relax_handled_keys', True)
 
         # Validate dialog_abort
         if self.dialog_abort not in [None, 'ESC', 'ESC-ESC']:
@@ -647,29 +713,30 @@ class IncrementalSearchBar:
 
         return False
 
-    def get_display_string(self, prefix='/', suffix=''):
+    def get_display_string(self, prefix='/', suffix='', cursor_char='█'):
         """
         Get formatted display string with cursor indicator.
 
-        When active (in search mode), shows cursor position with '|'.
+        When active (in search mode), shows cursor position with cursor_char (default: block).
         When inactive, just shows the text with prefix/suffix if text is non-empty.
 
         :param prefix: String to show before the search text (default: '/')
         :param suffix: String to show after the search text (default: '')
+        :param cursor_char: Character to use for cursor (default: '█' block)
         :returns: Formatted string for display
 
         Example:
-            Active with cursor: ' /hello| world'
-            Active at end: ' /hello world|'
+            Active with cursor: ' /hello█ world'
+            Active at end: ' /hello world█'
             Inactive with text: ' /hello world'
             Inactive without text: ''
         """
         if self._active:
-            # Show cursor position with |
+            # Show cursor position with cursor_char (block by default for visibility)
             before = self._text[:self._cursor_pos]
             after = self._text[self._cursor_pos:]
             # Add space after prefix to prevent pattern matching in fancy_header
-            return f'{prefix} {before}|{after}{suffix}'
+            return f'{prefix} {before}{cursor_char}{after}{suffix}'
         elif self._text:
             return f'{prefix}{self._text}{suffix}'
         else:
@@ -707,20 +774,52 @@ class OptionSpinner:
         :param stack: Optional ScreenStack reference for scope-aware key bindings.
                       If stack.obj is None, it will be set to this spinner's default_obj.
         :type stack: ScreenStack or None
+
+        .. warning::
+            If you plan to set a custom default_obj, either:
+
+            1. Pass it via ScreenStack: ``ScreenStack(win, my_opts, ...)`` then
+               ``OptionSpinner(stack=stack)`` (recommended)
+            2. Set it immediately after creation before calling add_key():
+               ``spin = OptionSpinner(stack=stack); spin.default_obj = my_opts``
+
+            The default_obj property automatically syncs with stack.obj when set.
         """
         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._default_obj = SimpleNamespace() # if not given one (private)
         self.attr_to_option = {} # given an attribute, find its option ns
         self.key_to_option = {} # given key, options namespace
         self.keys = set()
         self.stack = stack  # Optional ScreenStack for scope-aware bindings
         self.key_scopes = {}  # Maps (key, screen) -> option_ns for scope tracking
 
-        # If stack has None obj, give it our default_obj
-        if self.stack and self.stack.obj is None:
-            self.stack.obj = self.default_obj
+        # Sync with stack.obj: use stack's obj if available, otherwise provide ours
+        if self.stack:
+            if self.stack.obj is not None:
+                # Stack already has an obj - use it as our default_obj
+                self._default_obj = self.stack.obj
+            else:
+                # Stack has no obj - give it ours
+                self.stack.obj = self._default_obj
+
+    @property
+    def default_obj(self):
+        """
+        The default object for storing option values.
+
+        When set, automatically synchronizes with stack.obj to prevent
+        object reference fragmentation.
+        """
+        return self._default_obj
+
+    @default_obj.setter
+    def default_obj(self, value):
+        """Set default_obj and keep stack.obj synchronized."""
+        self._default_obj = value
+        if self.stack:
+            self.stack.obj = value  # Keep in sync!
 
     @staticmethod
     def _make_option_ns():
@@ -787,7 +886,7 @@ class OptionSpinner:
                 # Find all screens that implement this action (have method with name = attr)
                 effective_scope = set()
                 for screen_num, screen_obj in self.stack.screen_objects.items():
-                    if hasattr(screen_obj, ns.attr):
+                    if hasattr(screen_obj, f'{ns.attr}_ACTION'):
                         effective_scope.add(screen_num)
                 # If no screens found, default to all screens
                 if not effective_scope:
@@ -1186,6 +1285,7 @@ class ConsoleWindow:
         self.last_demo_key = ''  # Last key pressed in demo mode
         self.max_header_len = 0  # Max visible header length from previous render
         self.passthrough_mode = False  # When True, all printable keys pass through
+        self.relax_handled_keys = self.opts.relax_handled_keys  # When True, pass non-nav keys without checking handled_keys
         self._set_screen_dims()
         self.calc()
 
@@ -1551,78 +1651,6 @@ class ConsoleWindow:
         self.body_base = self.head.view_cnt + self.hor_line_cnt
         return not same
 
-    def _put(self, ns, *args, context=None):
-        """
-        Adds text to the head/body pad using a mixed argument list.
-
-        Allows interleaving of text (str/bytes) and curses attributes (int).
-        Text segments before an attribute are flushed with that attribute.
-
-        :param context: Optional Context object with metadata for this line.
-        :type context: Context or None
-        """
-        def flush(attr=None):
-            nonlocal self, is_body, row, text, seg, first, attrs_list
-            if attr is None:
-                attr = curses.A_NORMAL
-            # Apply stripping logic if needed
-            if is_body and self.pick_mode and self.opts.strip_attrs_in_pick_mode:
-                attr = curses.A_NORMAL
-
-            if seg and first:
-                ns.pad.addstr(row, 0, seg[0:self.get_pad_width()], attr)
-                attrs_list.append((attr, len(seg)))
-            elif seg:
-                _, x = ns.pad.getyx()
-                cols = self.get_pad_width() - x
-                if cols > 0:
-                    actual_seg = seg[0:cols]
-                    ns.pad.addstr(actual_seg, attr)
-                    attrs_list.append((attr, len(actual_seg)))
-            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
-            attrs_list = []  # run-length encoded attributes
-            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.text_attrs.append(attrs_list)  # run-length encoded attributes
-            ns.contexts.append(context)  # Context metadata (or None)
-            ns.row_cnt += 1
-
-    def put_head(self, *args, context=None):
-        """
-        Adds a line of text to the header pad, supporting mixed text and attributes.
-
-        :param args: Mixed arguments of str/bytes (text) and int (curses attributes).
-        :param context: Optional Context object with metadata for this line.
-        :type args: Any
-        :type context: Context or None
-        """
-        self._put(self.head, *args, context=context)
-
-    def put_body(self, *args, context=None):
-        """
-        Adds a line of text to the body pad, supporting mixed text and attributes.
-
-        :param args: Mixed arguments of str/bytes (text) and int (curses attributes).
-        :param context: Optional Context object with metadata for this line.
-        :type args: Any
-        :type context: Context or None
-        """
-        self._put(self.body, *args, context=context)
-
     def _add(self, ns, text, attr=None, resume=False, context=None):
         """Internal method to add text to pad using its namespace (simpler version of _put)."""
         is_body = bool(id(ns) == id(self.body))
@@ -1683,7 +1711,7 @@ class ConsoleWindow:
         """
         self._add(self.body, text, attr, resume, context)
 
-    def add_fancy_header(self, line, mode='Underline'):
+    def add_fancy_header(self, line, mode='Underline', search_pattern_attr=None):
         """
         Parses header line and adds it with fancy formatting.
 
@@ -1699,8 +1727,10 @@ class ConsoleWindow:
 
         :param line: The header text to add with formatting
         :param mode: Formatting mode ('Off', 'Underline', or 'Reverse')
+        :param search_pattern_attr: Optional custom attribute for /pattern highlighting
         :type line: str
         :type mode: str
+        :type search_pattern_attr: int or None
         """
         if mode == 'Off':
             # Fancy mode off, just add the line normally
@@ -1765,7 +1795,9 @@ class ConsoleWindow:
                             current_text = ""
 
                         full_pattern = match.group(0)  # includes the /
-                        result_sections.append((full_pattern, curses.A_BOLD | curses.A_REVERSE))
+                        # Use custom attr if provided, otherwise default bold+reverse
+                        pattern_attr = search_pattern_attr if search_pattern_attr is not None else (curses.A_BOLD | curses.A_REVERSE)
+                        result_sections.append((full_pattern, pattern_attr))
                         i += len(full_pattern)
                     else:
                         # Not a key pattern, just regular character
@@ -2799,7 +2831,10 @@ class ConsoleWindow:
                 if self.opts.demo_mode and key not in NAVIGATION_KEYS:
                     self.last_demo_key = self._format_key_for_demo(key)
                 return key
-            elif key in self.handled_keys:
+
+            # If relax_handled_keys is False, only pass keys explicitly in handled_keys
+            # (Navigation keys will still be handled below)
+            if not self.relax_handled_keys and key in self.handled_keys:
                 # Update demo mode tracking for non-navigation keys
                 if self.opts.demo_mode and key not in NAVIGATION_KEYS:
                     self.last_demo_key = self._format_key_for_demo(key)
@@ -2880,6 +2915,13 @@ class ConsoleWindow:
                 else:
                     # Only render here if we're not going to redraw immediately
                     self.render()
+            else:
+                # Navigation key didn't match - if relax_handled_keys is True, pass key to app
+                if self.relax_handled_keys:
+                    # Update demo mode tracking for non-navigation keys
+                    if self.opts.demo_mode and key not in NAVIGATION_KEYS:
+                        self.last_demo_key = self._format_key_for_demo(key)
+                    return key
         return None
 
 # =============================================================================
@@ -3214,8 +3256,31 @@ class ScreenStack:
         Args:
             win (ConsoleWindow): The console window instance
             spins_obj: Application object (typically holds OptionSpinner and state)
+                      IMPORTANT: If using OptionSpinner, pass your options namespace here
+                      to ensure proper object linking. See warning below.
             screens (tuple): Tuple of screen names (e.g., ['HOME', 'SETTINGS', 'HELP'])
             screen_objects (dict): Dict mapping screen numbers to Screen instances
+
+        .. warning::
+            **Initialization Order Matters!**
+
+            When using ScreenStack with OptionSpinner, follow this pattern:
+
+            .. code-block:: python
+
+                # CORRECT - Pass opts to ScreenStack
+                opts = SimpleNamespace()
+                stack = ScreenStack(win, opts, SCREENS, screen_objects)
+                spinner = OptionSpinner(stack=stack)
+                # spinner.default_obj now points to opts via stack.obj
+
+                # INCORRECT - Don't pass None then reassign
+                stack = ScreenStack(win, None, SCREENS, screen_objects)
+                spinner = OptionSpinner(stack=stack)
+                spinner.default_obj = opts  # Creates object fragmentation!
+
+            The OptionSpinner syncs with stack.obj, so they must use the same object
+            from the start to avoid different parts of the code using different namespaces.
         """
         self.win = win
         self.obj = spins_obj
@@ -3226,7 +3291,7 @@ class ScreenStack:
         # Push home screen (HOME_ST=0) as the initial screen
         self.push(HOME_ST, 0)
 
-    def push(self, screen, prev_pos, force=False):
+    def push(self, screen, prev_pos=None, force=False):
         """
         Push a new screen onto the stack with validation and loop prevention.
 
@@ -3238,6 +3303,8 @@ class ScreenStack:
         Returns:
             Previous position if successful, None if blocked by validation
         """
+        if prev_pos is None:
+            prev_pos = self.win.pick_pos
         # Loop prevention: Check if screen is already on the stack
         if not force and self.curr and screen == self.curr.num:
             # Trying to push the current screen again - ignore
@@ -3285,6 +3352,12 @@ class ScreenStack:
         self.win.pick_pos = self.win.scroll_pos = 0
         return 0
 
+    def get_curr_obj(self):
+        """ get the current screen object """
+        if self.curr:
+            return self.screen_objects.get(self.curr.num, None)
+        return None
+
     def pop(self, force=False):
         """
         Pop the top screen from the stack.

{console_window-1.3.2 → console_window-1.3.3}/pyproject.toml

@@ -23,7 +23,7 @@ name = "console_window"
 # UNIFIED PROJECT METADATA (Replaces [tool.flit.metadata])
 [project]
 name = "console-window" 
-version = "1.3.2"
+version = "1.3.3"
 description = "A robust curses wrapper for creating Text User Interfaces (TUIs)."
 readme = "README.md"
 requires-python = ">=3.8"