A widget and grid based framework for building command line user interfaces in python.
—
Modal popup dialogs for user interaction including messages, warnings, errors, yes/no confirmations, text input, menu selection, forms, file dialogs, and loading indicators.
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)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))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))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 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)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 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)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