0
# Main Interface Management
1
2
Core functionality for creating and managing the CUI application, including initialization, lifecycle management, layout configuration, and the main event loop.
3
4
## Capabilities
5
6
### CUI Initialization
7
8
Creates the main CUI interface with specified grid dimensions and configuration options.
9
10
```python { .api }
11
class PyCUI:
12
def __init__(num_rows: int, num_cols: int, auto_focus_buttons: bool = True,
13
exit_key = py_cui.keys.KEY_Q_LOWER, simulated_terminal: List[int] = None):
14
"""
15
Initialize the main CUI interface.
16
17
Parameters:
18
- num_rows: Number of rows in the grid layout
19
- num_cols: Number of columns in the grid layout
20
- auto_focus_buttons: If True, buttons auto-execute on focus (default: True)
21
- exit_key: Key code for exiting the CUI (default: 'q')
22
- simulated_terminal: [height, width] for testing (optional)
23
"""
24
```
25
26
Usage example:
27
```python
28
import py_cui
29
30
# Create a 3x3 grid CUI
31
root = py_cui.PyCUI(3, 3)
32
33
# Create with custom exit key (Escape)
34
root = py_cui.PyCUI(2, 4, exit_key=py_cui.keys.KEY_ESCAPE)
35
```
36
37
### CUI Lifecycle
38
39
Controls the CUI application lifecycle including starting, stopping, and exit handling.
40
41
```python { .api }
42
def start() -> None:
43
"""Start the CUI main event loop."""
44
45
def stop() -> None:
46
"""Stop the CUI and exit the main loop."""
47
48
def run_on_exit(command: Callable[[], Any]) -> None:
49
"""
50
Set callback function to run when CUI exits.
51
52
Parameters:
53
- command: No-argument function to execute on exit
54
"""
55
```
56
57
Usage example:
58
```python
59
def cleanup():
60
print("CUI is closing...")
61
62
root = py_cui.PyCUI(3, 3)
63
root.run_on_exit(cleanup)
64
root.start() # Blocks until CUI exits
65
```
66
67
### Title and Status Bar Management
68
69
Controls the title bar at the top and status bar at the bottom of the CUI.
70
71
```python { .api }
72
def set_title(title: str) -> None:
73
"""
74
Set the title bar text.
75
76
Parameters:
77
- title: Text to display in the title bar
78
"""
79
80
def set_status_bar_text(text: str) -> None:
81
"""
82
Set the status bar text when in overview mode.
83
84
Parameters:
85
- text: Text to display in the status bar
86
"""
87
```
88
89
Usage example:
90
```python
91
root = py_cui.PyCUI(3, 3)
92
root.set_title('My Application v1.0')
93
root.set_status_bar_text('Press TAB to cycle widgets, ENTER to select')
94
```
95
96
### Layout and Appearance Configuration
97
98
Controls visual appearance including borders, refresh timing, and update callbacks.
99
100
```python { .api }
101
def set_refresh_timeout(timeout: int) -> None:
102
"""
103
Set auto-refresh timeout in seconds.
104
105
Parameters:
106
- timeout: Number of seconds between automatic refreshes
107
"""
108
109
def toggle_unicode_borders() -> None:
110
"""Toggle between Unicode and ASCII border characters."""
111
112
def set_widget_border_characters(upper_left_corner: str, upper_right_corner: str,
113
lower_left_corner: str, lower_right_corner: str,
114
horizontal: str, vertical: str) -> None:
115
"""
116
Set custom border characters for widgets.
117
118
Parameters:
119
- upper_left_corner: Character for upper left corner
120
- upper_right_corner: Character for upper right corner
121
- lower_left_corner: Character for lower left corner
122
- lower_right_corner: Character for lower right corner
123
- horizontal: Character for horizontal borders
124
- vertical: Character for vertical borders
125
"""
126
127
def set_on_draw_update_func(update_function: Callable[[], Any]) -> None:
128
"""
129
Set function to call on each draw cycle.
130
131
Parameters:
132
- update_function: No-argument function called on each frame
133
"""
134
135
def get_absolute_size() -> Tuple[int, int]:
136
"""
137
Get CUI dimensions in characters.
138
139
Returns:
140
Tuple of (height, width) in terminal characters
141
"""
142
```
143
144
Usage example:
145
```python
146
root = py_cui.PyCUI(3, 3)
147
148
# Enable Unicode borders
149
root.toggle_unicode_borders()
150
151
# Set custom border style
152
root.set_widget_border_characters('┌', '┐', '└', '┘', '─', '│')
153
154
# Auto-refresh every 2 seconds
155
root.set_refresh_timeout(2)
156
157
# Update function called each frame
158
def update_clock():
159
import datetime
160
root.set_status_bar_text(f'Current time: {datetime.datetime.now()}')
161
162
root.set_on_draw_update_func(update_clock)
163
```
164
165
### Widget Set Management
166
167
Manages groups of widgets that can be switched between dynamically.
168
169
```python { .api }
170
def create_new_widget_set(num_rows: int, num_cols: int) -> WidgetSet:
171
"""
172
Create a new widget set for dynamic switching.
173
174
Parameters:
175
- num_rows: Number of rows in the new widget set grid
176
- num_cols: Number of columns in the new widget set grid
177
178
Returns:
179
New WidgetSet instance
180
"""
181
182
def apply_widget_set(new_widget_set: WidgetSet) -> None:
183
"""
184
Switch to a different widget set.
185
186
Parameters:
187
- new_widget_set: WidgetSet to switch to
188
"""
189
```
190
191
Usage example:
192
```python
193
root = py_cui.PyCUI(3, 3)
194
195
# Create alternate widget set
196
alt_set = root.create_new_widget_set(2, 2)
197
alt_button = alt_set.add_button('Switch Back', 0, 0,
198
command=lambda: root.apply_widget_set(main_set))
199
200
# Create main widget set
201
main_set = root.create_new_widget_set(3, 3)
202
main_button = main_set.add_button('Switch Views', 0, 0,
203
command=lambda: root.apply_widget_set(alt_set))
204
205
root.apply_widget_set(main_set)
206
root.start()
207
```
208
209
### Debug and Logging
210
211
Enables logging and live debug functionality for development and troubleshooting.
212
213
```python { .api }
214
def enable_logging(log_file_path: str = "py_cui.log",
215
logging_level = logging.DEBUG,
216
live_debug_key: int = py_cui.keys.KEY_CTRL_D) -> None:
217
"""
218
Enable logging for py_cui with optional live debug mode.
219
220
Parameters:
221
- log_file_path: Path to log file (default: "py_cui.log")
222
- logging_level: Logging level (default: logging.DEBUG)
223
- live_debug_key: Key to toggle live debug display (default: Ctrl+D)
224
"""
225
226
def set_toggle_live_debug_key(toggle_debug_key: int) -> None:
227
"""
228
Set key for toggling live debug mode.
229
230
Parameters:
231
- toggle_debug_key: Key code for debug toggle
232
"""
233
```
234
235
Usage example:
236
```python
237
import logging
238
239
root = py_cui.PyCUI(3, 3)
240
root.enable_logging('debug.log', logging.INFO, py_cui.keys.KEY_F12)
241
```