CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-py-cui

A widget and grid based framework for building command line user interfaces in python.

Pending
Overview
Eval results
Files

popups.mddocs/

Popup Dialogs

Modal popup dialogs for user interaction including messages, warnings, errors, yes/no confirmations, text input, menu selection, forms, file dialogs, and loading indicators.

Capabilities

Message Popups

Simple modal popups for displaying messages, warnings, and errors to the user.

def show_message_popup(title: str, text: str, color: int = WHITE_ON_BLACK) -> None:
    """
    Show a message popup dialog.
    
    Parameters:
    - title: Popup title
    - text: Message text to display
    - color: Color pair for popup (default: WHITE_ON_BLACK)
    """
    
def show_warning_popup(title: str, text: str) -> None:
    """
    Show a warning popup dialog with yellow background.
    
    Parameters:
    - title: Warning title
    - text: Warning message text
    """
    
def show_error_popup(title: str, text: str) -> None:
    """
    Show an error popup dialog with red background.
    
    Parameters:
    - title: Error title  
    - text: Error message text
    """

Usage example:

root = py_cui.PyCUI(3, 3)

def show_info():
    root.show_message_popup('Information', 'Process completed successfully!')
    
def show_warn():
    root.show_warning_popup('Warning', 'This action cannot be undone.')
    
def show_err():
    root.show_error_popup('Error', 'Failed to save file: Permission denied.')

info_btn = root.add_button('Info', 0, 0, command=show_info)
warn_btn = root.add_button('Warning', 0, 1, command=show_warn)
error_btn = root.add_button('Error', 0, 2, command=show_err)

Confirmation Dialogs

Yes/No confirmation dialogs for user decisions.

def show_yes_no_popup(title: str, command: Callable[[bool], Any]) -> None:
    """
    Show a yes/no confirmation popup.
    
    Parameters:
    - title: Confirmation question/title
    - command: Function called with True if 'yes' selected, False if 'no'
    """

Usage example:

def handle_delete_confirmation(confirmed: bool):
    if confirmed:
        print('File deleted!')
        root.show_message_popup('Success', 'File has been deleted.')
    else:
        print('Delete cancelled.')

root = py_cui.PyCUI(3, 3)
delete_btn = root.add_button('Delete File', 0, 0, 
                           command=lambda: root.show_yes_no_popup(
                               'Delete file permanently?', 
                               handle_delete_confirmation))

Text Input Popups

Modal text input dialogs for collecting user text input.

def show_text_box_popup(title: str, command: Callable[[str], Any], 
                       initial_text: str = '', password: bool = False) -> None:
    """
    Show a text input popup dialog.
    
    Parameters:
    - title: Input prompt/title
    - command: Function called with entered text string
    - initial_text: Pre-filled text (default: '')
    - password: If True, show '*' instead of characters (default: False)
    """

Usage example:

def handle_name_input(name: str):
    if name.strip():
        root.show_message_popup('Hello', f'Hello, {name}!')
    else:
        root.show_warning_popup('Error', 'Name cannot be empty.')

def handle_password_input(password: str):
    if len(password) >= 8:
        print('Password accepted')
    else:
        root.show_error_popup('Error', 'Password must be at least 8 characters.')

root = py_cui.PyCUI(3, 3) 
name_btn = root.add_button('Enter Name', 0, 0,
                          command=lambda: root.show_text_box_popup(
                              'Enter your name:', handle_name_input))
                              
pass_btn = root.add_button('Set Password', 0, 1,
                          command=lambda: root.show_text_box_popup(
                              'Enter password:', handle_password_input, 
                              password=True))

Menu Selection Popups

Modal menu popups for selecting from a list of options.

def show_menu_popup(title: str, menu_items: List[str], 
                   command: Callable[[str], Any],
                   run_command_if_none: bool = False) -> None:
    """
    Show a menu selection popup dialog.
    
    Parameters:
    - title: Menu title
    - menu_items: List of menu option strings
    - command: Function called with selected menu item string
    - run_command_if_none: If True, call command with None if no selection (default: False)
    """

Usage example:

def handle_theme_selection(theme: str):
    if theme:
        print(f'Theme changed to: {theme}')
        root.show_message_popup('Theme', f'Applied {theme} theme')

def handle_action_selection(action: str):
    if action == 'Save':
        print('Saving...')
    elif action == 'Load':  
        print('Loading...')
    elif action == 'Exit':
        root.stop()

root = py_cui.PyCUI(3, 3)
theme_btn = root.add_button('Select Theme', 0, 0,
                           command=lambda: root.show_menu_popup(
                               'Choose Theme',
                               ['Dark', 'Light', 'Blue', 'Green'],
                               handle_theme_selection))
                               
action_btn = root.add_button('Actions', 0, 1,
                            command=lambda: root.show_menu_popup(
                                'Select Action',
                                ['Save', 'Load', 'Exit'],
                                handle_action_selection))

Loading Indicators

Loading popups that display progress indicators for long-running operations.

def show_loading_icon_popup(title: str, message: str, 
                           callback: Callable[[], Any] = None) -> None:
    """
    Show a loading popup with spinning icon.
    
    Parameters:
    - title: Loading dialog title
    - message: Loading message (will show as 'message...')
    - callback: Function to call when loading completes (optional)
    """
    
def show_loading_bar_popup(title: str, num_items: List[int],
                          callback: Callable[[], Any] = None) -> None:
    """
    Show a loading popup with progress bar.
    
    Parameters:
    - title: Loading dialog title  
    - num_items: Total number of items to process
    - callback: Function to call when loading completes (optional)
    """
    
def increment_loading_bar() -> None:
    """Increment the progress bar by one step."""
    
def stop_loading_popup() -> None:
    """Close the loading popup and exit loading state."""

Usage example:

import threading
import time

def background_task():
    time.sleep(2)  # Simulate work
    root.stop_loading_popup()

def long_task_with_progress():
    # Show progress bar for 5 items
    root.show_loading_bar_popup('Processing', [5])
    
    def process_items():
        for i in range(5):
            time.sleep(0.5)  # Simulate processing
            root.increment_loading_bar()
        root.stop_loading_popup()
    
    threading.Thread(target=process_items, daemon=True).start()

root = py_cui.PyCUI(3, 3)
spinner_btn = root.add_button('Loading Spinner', 0, 0,
                             command=lambda: [
                                 root.show_loading_icon_popup('Processing', 'Please wait'),
                                 threading.Thread(target=background_task, daemon=True).start()
                             ])
                             
progress_btn = root.add_button('Progress Bar', 0, 1, command=long_task_with_progress)

Form Dialogs

Multi-field form popups for collecting structured user input.

def show_form_popup(title: str, fields: List[str], passwd_fields: List[str] = [],
                   required: List[str] = [], callback: Callable[[], Any] = None) -> None:
    """
    Show a form popup with multiple input fields.
    
    Parameters:
    - title: Form title
    - fields: List of field names
    - passwd_fields: Field names that should hide input (default: [])
    - required: Field names that must be filled (default: [])
    - callback: Function to call on form submission (optional)
    """

Usage example:

def handle_form_submission():
    # Form data available through popup object
    print('Form submitted!')

def show_user_form():
    root.show_form_popup(
        'User Registration',
        fields=['username', 'email', 'password', 'confirm_password'],
        passwd_fields=['password', 'confirm_password'],
        required=['username', 'email', 'password'],
        callback=handle_form_submission
    )

root = py_cui.PyCUI(3, 3)
form_btn = root.add_button('Registration Form', 0, 0, command=show_user_form)

File Dialogs

File and directory selection popups for file operations.

def show_filedialog_popup(popup_type: str = "openfile", initial_dir: str = ".",
                         callback: Callable[[], Any] = None, ascii_icons: bool = True,
                         limit_extensions: List[str] = []) -> None:
    """
    Show a file dialog popup.
    
    Parameters:
    - popup_type: Type of dialog - 'openfile', 'opendir', or 'saveas' (default: 'openfile')
    - initial_dir: Starting directory path (default: '.')
    - callback: Function to call with selected file/directory path (optional)
    - ascii_icons: Use ASCII icons instead of Unicode (default: True)
    - limit_extensions: Only show files with these extensions (default: [])
    """

Usage example:

def handle_file_selected():
    print('File selected!')

def handle_dir_selected():
    print('Directory selected!')

def open_file_dialog():
    root.show_filedialog_popup(
        popup_type='openfile',
        initial_dir='/home/user/documents',
        callback=handle_file_selected,
        limit_extensions=['.txt', '.py', '.md']
    )

def open_dir_dialog():
    root.show_filedialog_popup(
        popup_type='opendir', 
        initial_dir='/home/user',
        callback=handle_dir_selected
    )

def save_file_dialog():
    root.show_filedialog_popup(
        popup_type='saveas',
        callback=handle_file_selected
    )

root = py_cui.PyCUI(3, 3)
open_btn = root.add_button('Open File', 0, 0, command=open_file_dialog)
dir_btn = root.add_button('Select Dir', 0, 1, command=open_dir_dialog) 
save_btn = root.add_button('Save As', 0, 2, command=save_file_dialog)

Popup Management

Functions for managing popup state and behavior.

def close_popup() -> None:
    """Close the current popup and return to normal mode."""

Usage example:

def show_temp_message():
    root.show_message_popup('Temporary', 'This will close automatically')
    
    # Close popup after 2 seconds
    def auto_close():
        import time
        time.sleep(2)
        root.close_popup()
    
    threading.Thread(target=auto_close, daemon=True).start()

root = py_cui.PyCUI(3, 3)
temp_btn = root.add_button('Temp Message', 0, 0, command=show_temp_message)

Install with Tessl CLI

npx tessl i tessl/pypi-py-cui

docs

colors-styling.md

index.md

key-bindings.md

main-interface.md

popups.md

widgets.md

tile.json