0
# Popup Dialogs
1
2
Modal popup dialogs for user interaction including messages, warnings, errors, yes/no confirmations, text input, menu selection, forms, file dialogs, and loading indicators.
3
4
## Capabilities
5
6
### Message Popups
7
8
Simple modal popups for displaying messages, warnings, and errors to the user.
9
10
```python { .api }
11
def show_message_popup(title: str, text: str, color: int = WHITE_ON_BLACK) -> None:
12
"""
13
Show a message popup dialog.
14
15
Parameters:
16
- title: Popup title
17
- text: Message text to display
18
- color: Color pair for popup (default: WHITE_ON_BLACK)
19
"""
20
21
def show_warning_popup(title: str, text: str) -> None:
22
"""
23
Show a warning popup dialog with yellow background.
24
25
Parameters:
26
- title: Warning title
27
- text: Warning message text
28
"""
29
30
def show_error_popup(title: str, text: str) -> None:
31
"""
32
Show an error popup dialog with red background.
33
34
Parameters:
35
- title: Error title
36
- text: Error message text
37
"""
38
```
39
40
Usage example:
41
```python
42
root = py_cui.PyCUI(3, 3)
43
44
def show_info():
45
root.show_message_popup('Information', 'Process completed successfully!')
46
47
def show_warn():
48
root.show_warning_popup('Warning', 'This action cannot be undone.')
49
50
def show_err():
51
root.show_error_popup('Error', 'Failed to save file: Permission denied.')
52
53
info_btn = root.add_button('Info', 0, 0, command=show_info)
54
warn_btn = root.add_button('Warning', 0, 1, command=show_warn)
55
error_btn = root.add_button('Error', 0, 2, command=show_err)
56
```
57
58
### Confirmation Dialogs
59
60
Yes/No confirmation dialogs for user decisions.
61
62
```python { .api }
63
def show_yes_no_popup(title: str, command: Callable[[bool], Any]) -> None:
64
"""
65
Show a yes/no confirmation popup.
66
67
Parameters:
68
- title: Confirmation question/title
69
- command: Function called with True if 'yes' selected, False if 'no'
70
"""
71
```
72
73
Usage example:
74
```python
75
def handle_delete_confirmation(confirmed: bool):
76
if confirmed:
77
print('File deleted!')
78
root.show_message_popup('Success', 'File has been deleted.')
79
else:
80
print('Delete cancelled.')
81
82
root = py_cui.PyCUI(3, 3)
83
delete_btn = root.add_button('Delete File', 0, 0,
84
command=lambda: root.show_yes_no_popup(
85
'Delete file permanently?',
86
handle_delete_confirmation))
87
```
88
89
### Text Input Popups
90
91
Modal text input dialogs for collecting user text input.
92
93
```python { .api }
94
def show_text_box_popup(title: str, command: Callable[[str], Any],
95
initial_text: str = '', password: bool = False) -> None:
96
"""
97
Show a text input popup dialog.
98
99
Parameters:
100
- title: Input prompt/title
101
- command: Function called with entered text string
102
- initial_text: Pre-filled text (default: '')
103
- password: If True, show '*' instead of characters (default: False)
104
"""
105
```
106
107
Usage example:
108
```python
109
def handle_name_input(name: str):
110
if name.strip():
111
root.show_message_popup('Hello', f'Hello, {name}!')
112
else:
113
root.show_warning_popup('Error', 'Name cannot be empty.')
114
115
def handle_password_input(password: str):
116
if len(password) >= 8:
117
print('Password accepted')
118
else:
119
root.show_error_popup('Error', 'Password must be at least 8 characters.')
120
121
root = py_cui.PyCUI(3, 3)
122
name_btn = root.add_button('Enter Name', 0, 0,
123
command=lambda: root.show_text_box_popup(
124
'Enter your name:', handle_name_input))
125
126
pass_btn = root.add_button('Set Password', 0, 1,
127
command=lambda: root.show_text_box_popup(
128
'Enter password:', handle_password_input,
129
password=True))
130
```
131
132
### Menu Selection Popups
133
134
Modal menu popups for selecting from a list of options.
135
136
```python { .api }
137
def show_menu_popup(title: str, menu_items: List[str],
138
command: Callable[[str], Any],
139
run_command_if_none: bool = False) -> None:
140
"""
141
Show a menu selection popup dialog.
142
143
Parameters:
144
- title: Menu title
145
- menu_items: List of menu option strings
146
- command: Function called with selected menu item string
147
- run_command_if_none: If True, call command with None if no selection (default: False)
148
"""
149
```
150
151
Usage example:
152
```python
153
def handle_theme_selection(theme: str):
154
if theme:
155
print(f'Theme changed to: {theme}')
156
root.show_message_popup('Theme', f'Applied {theme} theme')
157
158
def handle_action_selection(action: str):
159
if action == 'Save':
160
print('Saving...')
161
elif action == 'Load':
162
print('Loading...')
163
elif action == 'Exit':
164
root.stop()
165
166
root = py_cui.PyCUI(3, 3)
167
theme_btn = root.add_button('Select Theme', 0, 0,
168
command=lambda: root.show_menu_popup(
169
'Choose Theme',
170
['Dark', 'Light', 'Blue', 'Green'],
171
handle_theme_selection))
172
173
action_btn = root.add_button('Actions', 0, 1,
174
command=lambda: root.show_menu_popup(
175
'Select Action',
176
['Save', 'Load', 'Exit'],
177
handle_action_selection))
178
```
179
180
### Loading Indicators
181
182
Loading popups that display progress indicators for long-running operations.
183
184
```python { .api }
185
def show_loading_icon_popup(title: str, message: str,
186
callback: Callable[[], Any] = None) -> None:
187
"""
188
Show a loading popup with spinning icon.
189
190
Parameters:
191
- title: Loading dialog title
192
- message: Loading message (will show as 'message...')
193
- callback: Function to call when loading completes (optional)
194
"""
195
196
def show_loading_bar_popup(title: str, num_items: List[int],
197
callback: Callable[[], Any] = None) -> None:
198
"""
199
Show a loading popup with progress bar.
200
201
Parameters:
202
- title: Loading dialog title
203
- num_items: Total number of items to process
204
- callback: Function to call when loading completes (optional)
205
"""
206
207
def increment_loading_bar() -> None:
208
"""Increment the progress bar by one step."""
209
210
def stop_loading_popup() -> None:
211
"""Close the loading popup and exit loading state."""
212
```
213
214
Usage example:
215
```python
216
import threading
217
import time
218
219
def background_task():
220
time.sleep(2) # Simulate work
221
root.stop_loading_popup()
222
223
def long_task_with_progress():
224
# Show progress bar for 5 items
225
root.show_loading_bar_popup('Processing', [5])
226
227
def process_items():
228
for i in range(5):
229
time.sleep(0.5) # Simulate processing
230
root.increment_loading_bar()
231
root.stop_loading_popup()
232
233
threading.Thread(target=process_items, daemon=True).start()
234
235
root = py_cui.PyCUI(3, 3)
236
spinner_btn = root.add_button('Loading Spinner', 0, 0,
237
command=lambda: [
238
root.show_loading_icon_popup('Processing', 'Please wait'),
239
threading.Thread(target=background_task, daemon=True).start()
240
])
241
242
progress_btn = root.add_button('Progress Bar', 0, 1, command=long_task_with_progress)
243
```
244
245
### Form Dialogs
246
247
Multi-field form popups for collecting structured user input.
248
249
```python { .api }
250
def show_form_popup(title: str, fields: List[str], passwd_fields: List[str] = [],
251
required: List[str] = [], callback: Callable[[], Any] = None) -> None:
252
"""
253
Show a form popup with multiple input fields.
254
255
Parameters:
256
- title: Form title
257
- fields: List of field names
258
- passwd_fields: Field names that should hide input (default: [])
259
- required: Field names that must be filled (default: [])
260
- callback: Function to call on form submission (optional)
261
"""
262
```
263
264
Usage example:
265
```python
266
def handle_form_submission():
267
# Form data available through popup object
268
print('Form submitted!')
269
270
def show_user_form():
271
root.show_form_popup(
272
'User Registration',
273
fields=['username', 'email', 'password', 'confirm_password'],
274
passwd_fields=['password', 'confirm_password'],
275
required=['username', 'email', 'password'],
276
callback=handle_form_submission
277
)
278
279
root = py_cui.PyCUI(3, 3)
280
form_btn = root.add_button('Registration Form', 0, 0, command=show_user_form)
281
```
282
283
### File Dialogs
284
285
File and directory selection popups for file operations.
286
287
```python { .api }
288
def show_filedialog_popup(popup_type: str = "openfile", initial_dir: str = ".",
289
callback: Callable[[], Any] = None, ascii_icons: bool = True,
290
limit_extensions: List[str] = []) -> None:
291
"""
292
Show a file dialog popup.
293
294
Parameters:
295
- popup_type: Type of dialog - 'openfile', 'opendir', or 'saveas' (default: 'openfile')
296
- initial_dir: Starting directory path (default: '.')
297
- callback: Function to call with selected file/directory path (optional)
298
- ascii_icons: Use ASCII icons instead of Unicode (default: True)
299
- limit_extensions: Only show files with these extensions (default: [])
300
"""
301
```
302
303
Usage example:
304
```python
305
def handle_file_selected():
306
print('File selected!')
307
308
def handle_dir_selected():
309
print('Directory selected!')
310
311
def open_file_dialog():
312
root.show_filedialog_popup(
313
popup_type='openfile',
314
initial_dir='/home/user/documents',
315
callback=handle_file_selected,
316
limit_extensions=['.txt', '.py', '.md']
317
)
318
319
def open_dir_dialog():
320
root.show_filedialog_popup(
321
popup_type='opendir',
322
initial_dir='/home/user',
323
callback=handle_dir_selected
324
)
325
326
def save_file_dialog():
327
root.show_filedialog_popup(
328
popup_type='saveas',
329
callback=handle_file_selected
330
)
331
332
root = py_cui.PyCUI(3, 3)
333
open_btn = root.add_button('Open File', 0, 0, command=open_file_dialog)
334
dir_btn = root.add_button('Select Dir', 0, 1, command=open_dir_dialog)
335
save_btn = root.add_button('Save As', 0, 2, command=save_file_dialog)
336
```
337
338
### Popup Management
339
340
Functions for managing popup state and behavior.
341
342
```python { .api }
343
def close_popup() -> None:
344
"""Close the current popup and return to normal mode."""
345
```
346
347
Usage example:
348
```python
349
def show_temp_message():
350
root.show_message_popup('Temporary', 'This will close automatically')
351
352
# Close popup after 2 seconds
353
def auto_close():
354
import time
355
time.sleep(2)
356
root.close_popup()
357
358
threading.Thread(target=auto_close, daemon=True).start()
359
360
root = py_cui.PyCUI(3, 3)
361
temp_btn = root.add_button('Temp Message', 0, 0, command=show_temp_message)
362
```