0
# py_cui
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: py_cui
7
- **Language**: Python  
8
- **Installation**: `pip install py-cui`
9
- **Minimum Python**: 3.6+
10
- **Platform**: Cross-platform (Windows support via windows-curses)
11

12
## Core Imports
13

14
```python
15
import py_cui
16
```
17

18
Main CUI class:
19

20
```python
21
from py_cui import PyCUI
22
```
23

24
Color constants:
25

26
```python
27
from py_cui import WHITE_ON_BLACK, BLACK_ON_GREEN, RED_ON_BLACK
28
```
29

30
## Basic Usage
31

32
```python
33
import py_cui
34

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

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

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

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

51
# Start the CUI
52
root.start()
53
```
54

55
## Architecture
56

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

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

66
The design provides three key operating modes:
67
- **Overview Mode**: Navigate between widgets using arrow keys, Enter to focus
68
- **Focus Mode**: Widget has full keyboard control, Escape to exit focus
69
- **Popup Mode**: Modal popups take complete control until dismissed
70

71
## Capabilities
72

73
### Main Interface Management
74

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

77
```python { .api }
78
class PyCUI:
79
    def __init__(num_rows: int, num_cols: int, auto_focus_buttons: bool = True, 
80
                 exit_key = py_cui.keys.KEY_Q_LOWER, simulated_terminal: List[int] = None): ...
81
    def start() -> None: ...
82
    def stop() -> None: ...
83
    def run_on_exit(command: Callable[[], Any]) -> None: ...
84
    def set_title(title: str) -> None: ...
85
    def set_status_bar_text(text: str) -> None: ...
86
    def get_absolute_size() -> Tuple[int, int]: ...
87
    def set_refresh_timeout(timeout: int) -> None: ...
88
    def set_on_draw_update_func(update_function: Callable[[], Any]) -> None: ...
89
    def toggle_unicode_borders() -> None: ...
90
    def set_widget_border_characters(upper_left_corner: str, upper_right_corner: str,
91
                                    lower_left_corner: str, lower_right_corner: str, 
92
                                    horizontal: str, vertical: str) -> None: ...
93
```
94

95
[Main Interface](./main-interface.md)
96

97
### Widget Creation and Management
98

99
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.
100

101
```python { .api }
102
def add_scroll_menu(title: str, row: int, column: int, row_span: int = 1, 
103
                   column_span: int = 1, padx: int = 1, pady: int = 0) -> ScrollMenu: ...
104
def add_checkbox_menu(title: str, row: int, column: int, row_span: int = 1, 
105
                     column_span: int = 1, padx: int = 1, pady: int = 0, 
106
                     checked_char: str = "X") -> CheckBoxMenu: ...
107
def add_text_box(title: str, row: int, column: int, row_span: int = 1,
108
                 column_span: int = 1, padx: int = 1, pady: int = 0, 
109
                 initial_text: str = "", password: bool = False) -> TextBox: ...
110
def add_text_block(title: str, row: int, column: int, row_span: int = 1,
111
                   column_span: int = 1, padx: int = 1, pady: int = 0, 
112
                   initial_text: str = "") -> ScrollTextBlock: ...
113
def add_label(title: str, row: int, column: int, row_span: int = 1,
114
              column_span: int = 1, padx: int = 1, pady: int = 0) -> Label: ...
115
def add_block_label(title: str, row: int, column: int, row_span: int = 1,
116
                    column_span: int = 1, padx: int = 1, pady: int = 0, 
117
                    center: bool = True) -> BlockLabel: ...
118
def add_button(title: str, row: int, column: int, row_span: int = 1,
119
               column_span: int = 1, padx: int = 1, pady: int = 0,
120
               command: Callable[[], Any] = None) -> Button: ...
121
def add_slider(title: str, row: int, column: int, row_span: int = 1,
122
               column_span: int = 1, padx: int = 1, pady: int = 0,
123
               min_val: int = 0, max_val: int = 100, step: int = 1, 
124
               init_val: int = 0) -> SliderWidget: ...
125
def add_custom_widget(widget_class: type, title: str, row: int, column: int, 
126
                     row_span: int, column_span: int, padx: int, pady: int, 
127
                     *args, **kwargs) -> Widget: ...
128
```
129

130
[Widgets](./widgets.md)
131

132
### Popup Dialogs
133

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

136
```python { .api }
137
def show_message_popup(title: str, text: str, color: int = WHITE_ON_BLACK) -> None: ...
138
def show_warning_popup(title: str, text: str) -> None: ...
139
def show_error_popup(title: str, text: str) -> None: ...
140
def show_yes_no_popup(title: str, command: Callable[[bool], Any]) -> None: ...
141
def show_text_box_popup(title: str, command: Callable[[str], Any], 
142
                       initial_text: str = '', password: bool = False) -> None: ...
143
def show_menu_popup(title: str, menu_items: List[str], command: Callable[[str], Any], 
144
                   run_command_if_none: bool = False) -> None: ...
145
def show_loading_icon_popup(title: str, message: str, callback: Callable[[], Any] = None) -> None: ...
146
def show_loading_bar_popup(title: str, num_items: List[int], callback: Callable[[], Any] = None) -> None: ...
147
def show_form_popup(title: str, fields: List[str], passwd_fields: List[str] = [], 
148
                   required: List[str] = [], callback: Callable[[], Any] = None) -> None: ...
149
def show_filedialog_popup(popup_type: str = "openfile", initial_dir: str = ".", 
150
                         callback: Callable[[], Any] = None, ascii_icons: bool = True, 
151
                         limit_extensions: List[str] = []) -> None: ...
152
def increment_loading_bar() -> None: ...
153
def stop_loading_popup() -> None: ...
154
def close_popup() -> None: ...
155
```
156

157
[Popups](./popups.md)
158

159
### Key Bindings and Events
160

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

163
```python { .api }
164
def add_key_command(key: Union[int, List[int]], command: Callable[[], Any]) -> None: ...
165
def set_widget_cycle_key(forward_cycle_key: int = None, reverse_cycle_key: int = None) -> None: ...
166
```
167

168
[Key Bindings](./key-bindings.md)
169

170
### Widget Management
171

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

174
```python { .api }
175
def get_widgets() -> Dict[int, Optional[Widget]]: ...
176
def forget_widget(widget: Widget) -> None: ...
177
def get_selected_widget() -> Optional[Widget]: ...
178
def set_selected_widget(widget_id: int) -> None: ...
179
def move_focus(widget: Widget, auto_press_buttons: bool = True) -> None: ...
180
def lose_focus() -> None: ...
181
def get_element_at_position(x: int, y: int) -> Optional[UIElement]: ...
182
```
183

184
### Widget Sets
185

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

188
```python { .api }
189
def create_new_widget_set(num_rows: int, num_cols: int) -> WidgetSet: ...
190
def apply_widget_set(new_widget_set: WidgetSet) -> None: ...
191
```
192

193
### Debug and Logging
194

195
Enable logging and live debug functionality for development and troubleshooting.
196

197
```python { .api }
198
def enable_logging(log_file_path: str = "py_cui.log", 
199
                  logging_level = logging.DEBUG,
200
                  live_debug_key: int = py_cui.keys.KEY_CTRL_D) -> None: ...
201
def set_toggle_live_debug_key(toggle_debug_key: int) -> None: ...
202
```
203

204
### Utility Functions
205

206
Helper functions for text formatting and other utilities.
207

208
```python { .api }
209
def fit_text(width: int, text: str, center: bool = False) -> str: ...
210
__version__: str  # Version information
211
```
212

213
### Colors and Styling
214

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

217
```python { .api }
218
# Color constants
219
WHITE_ON_BLACK: int
220
BLACK_ON_GREEN: int  
221
RED_ON_BLACK: int
222
YELLOW_ON_BLACK: int
223
# ... additional color constants
224
```
225

226
[Colors and Styling](./colors-styling.md)
227

228
## Types
229

230
```python { .api }
231
# Main classes
232
class PyCUI: ...
233

234
# Widget base class and specific widgets  
235
class Widget: ...
236
class ScrollMenu: ...
237
class CheckBoxMenu: ...
238
class TextBox: ...
239
class ScrollTextBlock: ...
240
class Label: ...
241
class BlockLabel: ...
242
class Button: ...
243

244
# Control widgets
245
class SliderWidget: ...
246

247
# Popup classes
248
class MessagePopup: ...
249
class YesNoPopup: ...
250
class TextBoxPopup: ...
251
class MenuPopup: ...
252
class LoadingIconPopup: ...
253
class LoadingBarPopup: ...
254
class FormPopup: ...
255
class FileDialogPopup: ...
256

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

260
# Layout and rendering
261
class Grid: ...
262
class Renderer: ...
263
class StatusBar: ...
264

265
# Utility types
266
class ColorRule: ...
267
```