0
# Dialog Functions
1

2
Dialog functions provide modal interfaces for user interaction including message boxes, file selection, and input prompts. All dialog functions can optionally be associated with a parent window for proper positioning and behavior.
3

4
## Capabilities
5

6
### Message Dialogs
7

8
Message dialogs display information to the user and wait for acknowledgment.
9

10
```python { .api }
11
def warn(title, text, master=None):
12
    """
13
    Display a warning message box.
14
    
15
    Args:
16
        title (str): Title text for the dialog
17
        text (str): Warning message to display
18
        master (App, optional): Parent window for dialog positioning
19
        
20
    Returns:
21
        None
22
    """
23

24
def info(title, text, master=None):
25
    """
26
    Display an information message box.
27
    
28
    Args:
29
        title (str): Title text for the dialog
30
        text (str): Information message to display
31
        master (App, optional): Parent window for dialog positioning
32
        
33
    Returns:
34
        None
35
    """
36

37
def error(title, text, master=None):
38
    """
39
    Display an error message box.
40
    
41
    Args:
42
        title (str): Title text for the dialog
43
        text (str): Error message to display
44
        master (App, optional): Parent window for dialog positioning
45
        
46
    Returns:
47
        None
48
    """
49
```
50

51
#### Usage Example
52

53
```python
54
from guizero import App, PushButton, warn, info, error
55

56
app = App()
57

58
def show_warning():
59
    warn("Warning", "This is a warning message!", app)
60

61
def show_info():
62
    info("Information", "This is an informational message.", app)
63

64
def show_error():
65
    error("Error", "Something went wrong!", app)
66

67
PushButton(app, text="Show Warning", command=show_warning)
68
PushButton(app, text="Show Info", command=show_info)  
69
PushButton(app, text="Show Error", command=show_error)
70

71
app.display()
72
```
73

74
### Question Dialogs
75

76
Question dialogs prompt the user for responses and return their input.
77

78
```python { .api }
79
def yesno(title, text, master=None):
80
    """
81
    Display a yes/no question dialog.
82
    
83
    Args:
84
        title (str): Title text for the dialog
85
        text (str): Question to ask the user
86
        master (App, optional): Parent window for dialog positioning
87
        
88
    Returns:
89
        bool: True if user clicked Yes, False if user clicked No
90
    """
91

92
def question(title, question, initial_value=None, master=None):
93
    """
94
    Display a text input question dialog.
95
    
96
    Args:
97
        title (str): Title text for the dialog
98
        question (str): Question or prompt text
99
        initial_value (str, optional): Default text in the input field
100
        master (App, optional): Parent window for dialog positioning
101
        
102
    Returns:
103
        str: User's text input, or None if cancelled
104
    """
105
```
106

107
#### Usage Example
108

109
```python
110
from guizero import App, PushButton, Text, yesno, question
111

112
app = App()
113
result_text = Text(app, text="Results will appear here")
114

115
def ask_yes_no():
116
    answer = yesno("Confirm", "Do you want to continue?", app)
117
    result_text.value = f"You answered: {'Yes' if answer else 'No'}"
118

119
def ask_question():
120
    name = question("Input", "What is your name?", "Enter name here", app)
121
    if name:
122
        result_text.value = f"Hello, {name}!"
123
    else:
124
        result_text.value = "No name entered"
125

126
PushButton(app, text="Ask Yes/No", command=ask_yes_no)
127
PushButton(app, text="Ask Question", command=ask_question)
128

129
app.display()
130
```
131

132
### File Selection Dialogs
133

134
File dialogs allow users to select files or folders from their filesystem.
135

136
```python { .api }
137
def select_file(title="Select file", folder=".", filetypes=[["All files", "*.*"]], 
138
                save=False, master=None, filename=""):
139
    """
140
    Display a file selection dialog.
141
    
142
    Args:
143
        title (str): Dialog title text
144
        folder (str): Initial directory to open
145
        filetypes (list): List of file type filters as [description, pattern] pairs
146
        save (bool): True for save dialog, False for open dialog
147
        master (App, optional): Parent window for dialog positioning
148
        filename (str): Initial filename (for save dialogs)
149
        
150
    Returns:
151
        str: Selected file path, or None if cancelled
152
    """
153

154
def select_folder(title="Select folder", folder=".", master=None):
155
    """
156
    Display a folder selection dialog.
157
    
158
    Args:
159
        title (str): Dialog title text
160
        folder (str): Initial directory to open
161
        master (App, optional): Parent window for dialog positioning
162
        
163
    Returns:
164
        str: Selected folder path, or None if cancelled
165
    """
166
```
167

168
#### Usage Example
169

170
```python
171
from guizero import App, PushButton, Text, select_file, select_folder
172
import os
173

174
app = App()
175
path_text = Text(app, text="No file selected")
176

177
def choose_file():
178
    # Define file type filters
179
    filetypes = [
180
        ["Text files", "*.txt"],
181
        ["Python files", "*.py"],
182
        ["All files", "*.*"]
183
    ]
184
    
185
    filepath = select_file(
186
        title="Choose a file",
187
        folder=os.path.expanduser("~"),
188
        filetypes=filetypes,
189
        master=app
190
    )
191
    
192
    if filepath:
193
        path_text.value = f"Selected: {os.path.basename(filepath)}"
194
    else:
195
        path_text.value = "No file selected"
196

197
def save_file():
198
    filetypes = [["Text files", "*.txt"], ["All files", "*.*"]]
199
    
200
    filepath = select_file(
201
        title="Save file as",
202
        folder=os.path.expanduser("~"),
203
        filetypes=filetypes,
204
        save=True,
205
        filename="document.txt",
206
        master=app
207
    )
208
    
209
    if filepath:
210
        path_text.value = f"Save to: {os.path.basename(filepath)}"
211
    else:
212
        path_text.value = "Save cancelled"
213

214
def choose_folder():
215
    folderpath = select_folder(
216
        title="Choose a folder",
217
        folder=os.path.expanduser("~"),
218
        master=app
219
    )
220
    
221
    if folderpath:
222
        path_text.value = f"Folder: {os.path.basename(folderpath)}"
223
    else:
224
        path_text.value = "No folder selected"
225

226
PushButton(app, text="Open File", command=choose_file)
227
PushButton(app, text="Save File", command=save_file)
228
PushButton(app, text="Choose Folder", command=choose_folder)
229

230
app.display()
231
```
232

233
### Color Selection Dialog
234

235
The color dialog allows users to select colors using a standard color picker interface.
236

237
```python { .api }
238
def select_color(color=None, master=None):
239
    """
240
    Display a color selection dialog.
241
    
242
    Args:
243
        color: Initial color selection (name, hex, or RGB tuple)
244
        master (App, optional): Parent window for dialog positioning
245
        
246
    Returns:
247
        str: Selected color as hex string (#RRGGBB), or None if cancelled
248
    """
249
```
250

251
#### Usage Example
252

253
```python
254
from guizero import App, PushButton, Text, Box, select_color
255

256
app = App()
257

258
# Display current color
259
color_display = Box(app, width=100, height=50)
260
color_display.bg = "white"
261

262
color_text = Text(app, text="Color: #FFFFFF")
263

264
def pick_color():
265
    # Start with current color
266
    current_color = color_display.bg
267
    
268
    selected_color = select_color(color=current_color, master=app)
269
    
270
    if selected_color:
271
        # Update display
272
        color_display.bg = selected_color
273
        color_text.value = f"Color: {selected_color}"
274

275
PushButton(app, text="Pick Color", command=pick_color)
276

277
app.display()
278
```
279

280
## File Type Filters
281

282
The `select_file` function accepts a list of file type filters to limit what files are shown:
283

284
```python
285
# Common file type examples
286
filetypes = [
287
    ["Text files", "*.txt"],
288
    ["Python files", "*.py"],  
289
    ["Image files", "*.png *.jpg *.gif"],
290
    ["All files", "*.*"]
291
]
292

293
# Multiple extensions for one type
294
filetypes = [
295
    ["Documents", "*.txt *.doc *.docx"],
296
    ["Images", "*.png *.jpg *.jpeg *.gif *.bmp"],
297
    ["All files", "*.*"]
298
]
299
```
300

301
## Dialog Best Practices
302

303
### Parent Window Association
304

305
Always pass the parent app/window to ensure proper dialog behavior:
306

307
```python
308
# Good - dialog appears over parent window
309
result = yesno("Confirm", "Continue?", master=app)
310

311
# Avoid - dialog may appear anywhere on screen
312
result = yesno("Confirm", "Continue?")
313
```
314

315
### Error Handling
316

317
Handle cases where users cancel dialogs:
318

319
```python
320
def open_file():
321
    filepath = select_file(master=app)
322
    
323
    if filepath:
324
        # User selected a file
325
        try:
326
            with open(filepath, 'r') as f:
327
                content = f.read()
328
            # Process file content
329
        except IOError:
330
            error("Error", f"Could not read file: {filepath}", app)
331
    else:
332
        # User cancelled - no action needed
333
        pass
334
```
335

336
### Input Validation
337

338
Validate user input from question dialogs:
339

340
```python
341
def get_age():
342
    age_str = question("Input", "Enter your age:", master=app)
343
    
344
    if age_str:
345
        try:
346
            age = int(age_str)
347
            if age < 0:
348
                error("Error", "Age cannot be negative", app)
349
            else:
350
                info("Success", f"Your age is {age}", app)
351
        except ValueError:
352
            error("Error", "Please enter a valid number", app)
353
```
354

355
## Platform Considerations
356

357
Dialog appearance and behavior may vary between operating systems:
358

359
- **Windows**: Standard Windows dialog styling
360
- **macOS**: Native macOS dialog appearance  
361
- **Linux**: Depends on desktop environment (GTK/Qt styling)
362

363
File path separators and default locations are handled automatically by the underlying system.