0
# Message Boxes
1

2
Cross-platform dialog boxes for user interaction including alerts, confirmations, text input, and password prompts. These functions provide a simple way to display information and collect user input through native system dialogs.
3

4
## Capabilities
5

6
### Alert Messages
7

8
Display informational messages to the user with a single acknowledgment button.
9

10
```python { .api }
11
def alert(text='', title='', button='OK'):
12
    """
13
    Display an alert message box with single button.
14
    
15
    Parameters:
16
    - text (str): Message text to display (default: '')
17
    - title (str): Window title (default: '')
18
    - button (str): Button text (default: 'OK')
19
    
20
    Returns:
21
    str: Text of the button clicked (always the button parameter value)
22
    
23
    Example:
24
    pyautogui.alert('Process completed successfully!', 'Success')
25
    pyautogui.alert('Warning: This action cannot be undone', 'Warning', 'I Understand')
26
    """
27
```
28

29
### Confirmation Dialogs
30

31
Present the user with multiple choice options for decision making.
32

33
```python { .api }
34
def confirm(text='', title='', buttons=['Cancel', 'OK']):
35
    """
36
    Display confirmation dialog with multiple buttons.
37
    
38
    Parameters:
39
    - text (str): Message text to display (default: '')
40
    - title (str): Window title (default: '')
41
    - buttons (list): List of button text options (default: ['Cancel', 'OK'])
42
    
43
    Returns:
44
    str: Text of the button clicked, or None if dialog was closed/cancelled
45
    
46
    Examples:
47
    result = pyautogui.confirm('Save changes before closing?', 'Confirm', ['Save', 'Don\'t Save', 'Cancel'])
48
    if result == 'Save':
49
        # Save the file
50
        pass
51
    elif result == 'Don\'t Save':
52
        # Close without saving
53
        pass
54
    # If result is 'Cancel' or None, do nothing
55
    """
56
```
57

58
### Text Input Prompts
59

60
Collect text input from the user through input dialog boxes.
61

62
```python { .api }
63
def prompt(text='', title='', default=''):
64
    """
65
    Display text input dialog box.
66
    
67
    Parameters:
68
    - text (str): Prompt message to display (default: '')
69
    - title (str): Window title (default: '')
70
    - default (str): Default text in input field (default: '')
71
    
72
    Returns:
73
    str: User input text, or None if dialog was cancelled
74
    
75
    Examples:
76
    name = pyautogui.prompt('Enter your name:', 'User Registration')
77
    if name:
78
        print(f"Hello, {name}!")
79
    
80
    filename = pyautogui.prompt('Save as:', 'Save File', default='document.txt')
81
    """
82
```
83

84
### Password Input
85

86
Collect sensitive text input with masked display for password and credential entry.
87

88
```python { .api }
89
def password(text='', title='', default='', mask='*'):
90
    """
91
    Display password input dialog with masked text entry.
92
    
93
    Parameters:
94
    - text (str): Prompt message to display (default: '')
95
    - title (str): Window title (default: '')
96
    - default (str): Default text in input field (default: '')
97
    - mask (str): Character to display instead of actual characters (default: '*')
98
    
99
    Returns:
100
    str: User input text (unmasked), or None if dialog was cancelled
101
    
102
    Examples:
103
    password = pyautogui.password('Enter password:', 'Login')
104
    if password:
105
        # Use password for authentication
106
        authenticate(password)
107
    
108
    pin = pyautogui.password('Enter PIN:', 'Security', mask='•')
109
    """
110
```
111

112
## Usage Examples
113

114
```python
115
import pyautogui
116

117
# Simple alert notifications
118
pyautogui.alert('File saved successfully!')
119
pyautogui.alert('Operation completed', 'Status Update')
120
pyautogui.alert('Custom button text', title='Custom Title', button='Got It')
121

122
# Confirmation dialogs
123
result = pyautogui.confirm('Do you want to continue?')
124
if result == 'OK':
125
    print("User chose to continue")
126
else:
127
    print("User cancelled or closed dialog")
128

129
# Custom confirmation with multiple options
130
choice = pyautogui.confirm(
131
    'What would you like to do with this file?',
132
    'File Action',
133
    ['Open', 'Delete', 'Rename', 'Cancel']
134
)
135

136
if choice == 'Open':
137
    # Open the file
138
    pass
139
elif choice == 'Delete':
140
    # Delete the file
141
    pass
142
elif choice == 'Rename':
143
    # Rename the file
144
    pass
145
# If choice is 'Cancel' or None, do nothing
146

147
# Text input prompts
148
username = pyautogui.prompt('Enter username:', 'Login')
149
if username:
150
    password = pyautogui.password('Enter password:', 'Login')
151
    if password:
152
        print(f"Attempting login for user: {username}")
153
        # Perform login with username and password
154
    else:
155
        print("Password entry cancelled")
156
else:
157
    print("Username entry cancelled")
158

159
# Input with default values
160
email = pyautogui.prompt(
161
    'Enter your email address:',
162
    'Account Setup',
163
    default='user@example.com'
164
)
165

166
# Complex workflow with error handling
167
def get_user_credentials():
168
    """Get username and password from user with validation"""
169
    while True:
170
        username = pyautogui.prompt('Username:', 'Login Required')
171
        if username is None:  # User cancelled
172
            return None, None
173
        
174
        if not username.strip():
175
            pyautogui.alert('Username cannot be empty!', 'Error')
176
            continue
177
        
178
        password = pyautogui.password('Password:', 'Login Required')
179
        if password is None:  # User cancelled
180
            return None, None
181
        
182
        if len(password) < 6:
183
            pyautogui.alert('Password must be at least 6 characters!', 'Error')
184
            continue
185
        
186
        return username, password
187

188
# Use the function
189
username, password = get_user_credentials()
190
if username and password:
191
    print("Credentials obtained successfully")
192
else:
193
    print("Login cancelled by user")
194

195
# Save/Don't Save/Cancel pattern
196
def prompt_save_changes():
197
    """Common save dialog pattern"""
198
    response = pyautogui.confirm(
199
        'You have unsaved changes. What would you like to do?',
200
        'Unsaved Changes',
201
        ['Save', "Don't Save", 'Cancel']
202
    )
203
    
204
    if response == 'Save':
205
        # Save the document
206
        filename = pyautogui.prompt('Save as:', 'Save Document', default='untitled.txt')
207
        if filename:
208
            print(f"Saving as {filename}")
209
            return 'saved'
210
        else:
211
            return 'cancelled'  # User cancelled save dialog
212
    elif response == "Don't Save":
213
        return 'discard'
214
    else:  # Cancel or None
215
        return 'cancelled'
216

217
# Configuration and setup dialogs
218
def setup_application():
219
    """Application setup using multiple dialogs"""
220
    # Get user preferences
221
    name = pyautogui.prompt('Enter your name:', 'Setup')
222
    if not name:
223
        return False
224
    
225
    # Theme selection
226
    theme = pyautogui.confirm(
227
        'Choose your preferred theme:',
228
        'Theme Selection',
229
        ['Light', 'Dark', 'Auto']
230
    )
231
    if not theme:
232
        return False
233
    
234
    # Auto-save preference
235
    autosave = pyautogui.confirm(
236
        'Enable auto-save every 5 minutes?',
237
        'Auto-save',
238
        ['Yes', 'No']
239
    )
240
    
241
    # Summary
242
    summary = f"""Setup Summary:
243
Name: {name}
244
Theme: {theme}
245
Auto-save: {autosave}"""
246
    
247
    confirm_setup = pyautogui.confirm(
248
        summary + '\n\nProceed with these settings?',
249
        'Confirm Setup',
250
        ['Yes', 'No']
251
    )
252
    
253
    return confirm_setup == 'Yes'
254

255
# Run setup
256
if setup_application():
257
    pyautogui.alert('Setup completed successfully!', 'Welcome')
258
else:
259
    pyautogui.alert('Setup cancelled', 'Setup')
260
```
261

262
## Platform Behavior
263

264
### Windows
265
- Uses native Windows message boxes (MessageBox API)
266
- Appearance matches Windows system theme
267
- Supports all dialog types with full customization
268

269
### macOS
270
- Uses native Cocoa alerts and dialogs
271
- Appearance matches macOS system theme
272
- Dialog positioning follows macOS conventions
273

274
### Linux
275
- Uses Tkinter dialogs (cross-desktop compatibility)
276
- Basic appearance that works across different desktop environments
277
- May not match specific desktop themes perfectly
278

279
## Return Value Handling
280

281
```python
282
# Always check for None return values
283
result = pyautogui.confirm('Continue?')
284
if result is None:
285
    print("Dialog was closed or cancelled")
286
elif result == 'OK':
287
    print("User confirmed")
288
else:
289
    print(f"User selected: {result}")
290

291
# Safe text input handling
292
text = pyautogui.prompt('Enter text:')
293
if text is not None:  # User didn't cancel
294
    if text.strip():  # User entered non-empty text
295
        process_text(text)
296
    else:
297
        print("Empty text entered")
298
else:
299
    print("Input cancelled")
300
```
301

302
## Integration with PyMsgBox
303

304
PyAutoGUI's message box functions are provided by the PyMsgBox library. For advanced usage or additional dialog types, you can import PyMsgBox directly:
305

306
```python
307
import pymsgbox
308

309
# PyAutoGUI functions are aliases for PyMsgBox functions
310
# These are equivalent:
311
pyautogui.alert('Message')
312
pymsgbox.alert('Message')
313
```