or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

colors-styling.md index.md key-bindings.md main-interface.md popups.md widgets.md

tile.json

tessl/pypi-py-cui

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

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/py-cui@0.1.x

To install, run

npx @tessl/cli install tessl/pypi-py-cui@0.1.0

py_cui

A comprehensive Python library for building command line user interfaces (CUI/TUI) using a widget-based and grid layout approach. py_cui provides pre-built interactive widgets, popup dialogs, custom key bindings, color rendering rules, and a grid-based layout manager, designed for maximum reusability across CLI applications, development tools, games, and any application requiring styled terminal-based user interfaces.

Package Information

Package Name: py_cui
Language: Python
Installation: pip install py-cui
Minimum Python: 3.6+
Platform: Cross-platform (Windows support via windows-curses)

Core Imports

import py_cui

Main CUI class:

from py_cui import PyCUI

Color constants:

from py_cui import WHITE_ON_BLACK, BLACK_ON_GREEN, RED_ON_BLACK

Basic Usage

import py_cui

# Create the main CUI object with a 3x3 grid
root = py_cui.PyCUI(3, 3)
root.set_title('My CUI Application')

# Add widgets to the grid
scroll_menu = root.add_scroll_menu('Menu', 0, 0)
scroll_menu.add_item('Option 1')
scroll_menu.add_item('Option 2')

text_box = root.add_text_box('Input', 0, 1)
button = root.add_button('Submit', 0, 2, command=lambda: print('Clicked!'))

# Add a text block for output
output_block = root.add_text_block('Output', 1, 0, column_span=3)
output_block.set_text('Welcome to py_cui!')

# Start the CUI
root.start()

Architecture

py_cui follows a structured widget-based architecture with these key components:

PyCUI: Main interface class managing the entire CUI, grid layout, widgets, and event handling
Grid System: Flexible grid-based layout manager allowing widgets to span multiple rows/columns
Widget Hierarchy: Base Widget class extended by specific widget types (ScrollMenu, TextBox, Button, etc.)
Renderer: Handles drawing widgets, borders, colors, and text to the terminal using curses
Popup System: Modal dialogs for messages, forms, file selection, and loading indicators
Event System: Key bindings for both global (overview mode) and widget-specific (focus mode) interactions

The design provides three key operating modes:

Overview Mode: Navigate between widgets using arrow keys, Enter to focus
Focus Mode: Widget has full keyboard control, Escape to exit focus
Popup Mode: Modal popups take complete control until dismissed

Capabilities

Main Interface Management

Core functionality for creating and managing the CUI application, including initialization, lifecycle management, layout configuration, and the main event loop.

class PyCUI:
    def __init__(num_rows: int, num_cols: int, auto_focus_buttons: bool = True, 
                 exit_key = py_cui.keys.KEY_Q_LOWER, simulated_terminal: List[int] = None): ...
    def start() -> None: ...
    def stop() -> None: ...
    def run_on_exit(command: Callable[[], Any]) -> None: ...
    def set_title(title: str) -> None: ...
    def set_status_bar_text(text: str) -> None: ...
    def get_absolute_size() -> Tuple[int, int]: ...
    def set_refresh_timeout(timeout: int) -> None: ...
    def set_on_draw_update_func(update_function: Callable[[], Any]) -> None: ...
    def toggle_unicode_borders() -> None: ...
    def set_widget_border_characters(upper_left_corner: str, upper_right_corner: str,
                                    lower_left_corner: str, lower_right_corner: str, 
                                    horizontal: str, vertical: str) -> None: ...

Main Interface

Widget Creation and Management

Methods for creating and managing all widget types including scroll menus, text boxes, buttons, labels, and custom widgets. Includes widget positioning, removal, and focus management.

def add_scroll_menu(title: str, row: int, column: int, row_span: int = 1, 
                   column_span: int = 1, padx: int = 1, pady: int = 0) -> ScrollMenu: ...
def add_checkbox_menu(title: str, row: int, column: int, row_span: int = 1, 
                     column_span: int = 1, padx: int = 1, pady: int = 0, 
                     checked_char: str = "X") -> CheckBoxMenu: ...
def add_text_box(title: str, row: int, column: int, row_span: int = 1,
                 column_span: int = 1, padx: int = 1, pady: int = 0, 
                 initial_text: str = "", password: bool = False) -> TextBox: ...
def add_text_block(title: str, row: int, column: int, row_span: int = 1,
                   column_span: int = 1, padx: int = 1, pady: int = 0, 
                   initial_text: str = "") -> ScrollTextBlock: ...
def add_label(title: str, row: int, column: int, row_span: int = 1,
              column_span: int = 1, padx: int = 1, pady: int = 0) -> Label: ...
def add_block_label(title: str, row: int, column: int, row_span: int = 1,
                    column_span: int = 1, padx: int = 1, pady: int = 0, 
                    center: bool = True) -> BlockLabel: ...
def add_button(title: str, row: int, column: int, row_span: int = 1,
               column_span: int = 1, padx: int = 1, pady: int = 0,
               command: Callable[[], Any] = None) -> Button: ...
def add_slider(title: str, row: int, column: int, row_span: int = 1,
               column_span: int = 1, padx: int = 1, pady: int = 0,
               min_val: int = 0, max_val: int = 100, step: int = 1, 
               init_val: int = 0) -> SliderWidget: ...
def add_custom_widget(widget_class: type, title: str, row: int, column: int, 
                     row_span: int, column_span: int, padx: int, pady: int, 
                     *args, **kwargs) -> Widget: ...

Widgets

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.

def show_message_popup(title: str, text: str, color: int = WHITE_ON_BLACK) -> None: ...
def show_warning_popup(title: str, text: str) -> None: ...
def show_error_popup(title: str, text: str) -> None: ...
def show_yes_no_popup(title: str, command: Callable[[bool], Any]) -> None: ...
def show_text_box_popup(title: str, command: Callable[[str], Any], 
                       initial_text: str = '', password: bool = False) -> None: ...
def show_menu_popup(title: str, menu_items: List[str], command: Callable[[str], Any], 
                   run_command_if_none: bool = False) -> None: ...
def show_loading_icon_popup(title: str, message: str, callback: Callable[[], Any] = None) -> None: ...
def show_loading_bar_popup(title: str, num_items: List[int], callback: Callable[[], Any] = None) -> None: ...
def show_form_popup(title: str, fields: List[str], passwd_fields: List[str] = [], 
                   required: List[str] = [], callback: Callable[[], Any] = None) -> None: ...
def show_filedialog_popup(popup_type: str = "openfile", initial_dir: str = ".", 
                         callback: Callable[[], Any] = None, ascii_icons: bool = True, 
                         limit_extensions: List[str] = []) -> None: ...
def increment_loading_bar() -> None: ...
def stop_loading_popup() -> None: ...
def close_popup() -> None: ...

Popups

Key Bindings and Events

Global and widget-specific key binding system for handling user input, navigation, and custom commands in both overview and focus modes.

def add_key_command(key: Union[int, List[int]], command: Callable[[], Any]) -> None: ...
def set_widget_cycle_key(forward_cycle_key: int = None, reverse_cycle_key: int = None) -> None: ...

Key Bindings

Widget Management

Methods for managing widget focus, selection, and removal after creation.

def get_widgets() -> Dict[int, Optional[Widget]]: ...
def forget_widget(widget: Widget) -> None: ...
def get_selected_widget() -> Optional[Widget]: ...
def set_selected_widget(widget_id: int) -> None: ...
def move_focus(widget: Widget, auto_press_buttons: bool = True) -> None: ...
def lose_focus() -> None: ...
def get_element_at_position(x: int, y: int) -> Optional[UIElement]: ...

Widget Sets

Create and manage groups of widgets that can be switched between dynamically.

def create_new_widget_set(num_rows: int, num_cols: int) -> WidgetSet: ...
def apply_widget_set(new_widget_set: WidgetSet) -> None: ...

Debug and Logging

Enable logging and live debug functionality for development and troubleshooting.

def enable_logging(log_file_path: str = "py_cui.log", 
                  logging_level = logging.DEBUG,
                  live_debug_key: int = py_cui.keys.KEY_CTRL_D) -> None: ...
def set_toggle_live_debug_key(toggle_debug_key: int) -> None: ...

Utility Functions

Helper functions for text formatting and other utilities.

def fit_text(width: int, text: str, center: bool = False) -> str: ...
__version__: str  # Version information

Colors and Styling

Color system with predefined color pairs, custom color rules for syntax highlighting, border customization, and visual theming options.

# Color constants
WHITE_ON_BLACK: int
BLACK_ON_GREEN: int  
RED_ON_BLACK: int
YELLOW_ON_BLACK: int
# ... additional color constants

Colors and Styling

Types

# Main classes
class PyCUI: ...

# Widget base class and specific widgets  
class Widget: ...
class ScrollMenu: ...
class CheckBoxMenu: ...
class TextBox: ...
class ScrollTextBlock: ...
class Label: ...
class BlockLabel: ...
class Button: ...

# Control widgets
class SliderWidget: ...

# Popup classes
class MessagePopup: ...
class YesNoPopup: ...
class TextBoxPopup: ...
class MenuPopup: ...
class LoadingIconPopup: ...
class LoadingBarPopup: ...
class FormPopup: ...
class FileDialogPopup: ...

# Widget Set for managing groups of widgets
class WidgetSet: ...

# Layout and rendering
class Grid: ...
class Renderer: ...
class StatusBar: ...

# Utility types
class ColorRule: ...

Version

Tile

Files

tessl/pypi-py-cui

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

py_cui

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Main Interface Management

Widget Creation and Management

Popup Dialogs

Key Bindings and Events

Widget Management

Widget Sets

Debug and Logging

Utility Functions

Colors and Styling

Types

index.mddocs/