0
# PyMsgBox
1

2
A simple, cross-platform, pure Python module for JavaScript-like message boxes. PyMsgBox provides four essential dialog functions that create modal message boxes for user interaction, supporting both cross-platform tkinter implementation and native Windows dialogs when available.
3

4
## Package Information
5

6
- **Package Name**: PyMsgBox
7
- **Language**: Python
8
- **Installation**: `pip install PyMsgBox`
9

10
## Core Imports
11

12
```python
13
import pymsgbox
14
```
15

16
All functions available via star import:
17

18
```python
19
from pymsgbox import *
20
```
21

22
Specific function imports:
23

24
```python
25
from pymsgbox import alert, confirm, prompt, password
26
```
27

28
## Basic Usage
29

30
```python
31
import pymsgbox
32

33
# Display a simple alert
34
pymsgbox.alert('Hello World!', 'My Alert')
35

36
# Get user confirmation
37
result = pymsgbox.confirm('Do you want to continue?', 'Confirm Action')
38
if result == 'OK':
39
    print('User confirmed')
40

41
# Get text input from user
42
name = pymsgbox.prompt('Enter your name:', 'User Input')
43
if name:
44
    print(f'Hello, {name}!')
45

46
# Get password input (masked)
47
password = pymsgbox.password('Enter password:', 'Authentication')
48
if password:
49
    print('Password entered')
50
```
51

52
## Capabilities
53

54
### Alert Dialogs
55

56
Displays a simple message box with text and a single button. Returns the text of the button clicked.
57

58
```python { .api }
59
def alert(text='', title='', button='OK', root=None, timeout=None, icon=NO_ICON, _tkinter=False):
60
    """
61
    Display a simple message box with text and a single button.
62
    
63
    Parameters:
64
    - text (str): Message text to display
65
    - title (str): Window title
66
    - button (str): Text for the button (default: 'OK')
67
    - root: Tkinter root window (optional)
68
    - timeout (int): Timeout in milliseconds (tkinter only)
69
    - icon: Icon type for Windows native dialogs (NO_ICON, STOP, QUESTION, WARNING, INFO)
70
    - _tkinter (bool): Force tkinter implementation on Windows
71
    
72
    Returns:
73
    str: Text of the button clicked
74
    """
75
```
76

77
### Confirmation Dialogs
78

79
Displays a message box with customizable buttons for user confirmation. Returns the text of the button clicked.
80

81
```python { .api }
82
def confirm(text='', title='', buttons=('OK', 'Cancel'), root=None, timeout=None, icon=QUESTION, _tkinter=False):
83
    """
84
    Display a message box with customizable buttons for confirmation.
85
    
86
    Parameters:
87
    - text (str): Message text to display
88
    - title (str): Window title  
89
    - buttons (tuple/list): Button texts (default: ('OK', 'Cancel'))
90
    - root: Tkinter root window (optional)
91
    - timeout (int): Timeout in milliseconds (tkinter only)
92
    - icon: Icon type for Windows native dialogs
93
    - _tkinter (bool): Force tkinter implementation on Windows
94
    
95
    Returns:
96
    str: Text of the button clicked
97
    """
98
```
99

100
### Text Input Dialogs
101

102
Displays a message box with a text input field and OK/Cancel buttons. Returns the entered text or None if cancelled.
103

104
```python { .api }
105
def prompt(text='', title='', default='', root=None, timeout=None):
106
    """
107
    Display a message box with text input field.
108
    
109
    Parameters:
110
    - text (str): Message text to display
111
    - title (str): Window title
112
    - default (str): Default text in input field
113
    - root: Tkinter root window (optional)
114
    - timeout (int): Timeout in milliseconds
115
    
116
    Returns:
117
    str: Text entered by user, or None if cancelled
118
    """
119
```
120

121
### Password Input Dialogs
122

123
Displays a message box with a masked text input field and OK/Cancel buttons. Returns the entered text or None if cancelled.
124

125
```python { .api }
126
def password(text='', title='', default='', mask='*', root=None, timeout=None):
127
    """
128
    Display a message box with masked text input field.
129
    
130
    Parameters:
131
    - text (str): Message text to display
132
    - title (str): Window title
133
    - default (str): Default text in input field
134
    - mask (str): Character used to mask input (default: '*')
135
    - root: Tkinter root window (optional)
136
    - timeout (int): Timeout in milliseconds
137
    
138
    Returns:
139
    str: Text entered by user, or None if cancelled
140
    """
141
```
142

143
## Constants
144

145
### Button Text Constants
146

147
Standard button text constants for consistent UI:
148

149
```python { .api }
150
OK_TEXT = 'OK'
151
CANCEL_TEXT = 'Cancel'
152
YES_TEXT = 'Yes'
153
NO_TEXT = 'No'
154
RETRY_TEXT = 'Retry'
155
ABORT_TEXT = 'Abort'
156
IGNORE_TEXT = 'Ignore'
157
TRY_AGAIN_TEXT = 'Try Again'  # Note: Windows native code incorrectly references "TRY_TEXT"
158
CONTINUE_TEXT = 'Continue'
159
```
160

161
### Icon Constants (Windows)
162

163
Icon types for Windows native message boxes:
164

165
```python { .api }
166
NO_ICON = 0
167
STOP = 0x10      # Error/stop icon
168
QUESTION = 0x20  # Question mark icon
169
WARNING = 0x30   # Warning/exclamation icon
170
INFO = 0x40      # Information icon
171

172
# Additional icon constant aliases (note: some contain intentional typos from original)
173
MB_ICONHAND = MB_ICONSTOP = MB_ICONERRPR = 0x10  # ICONERRPR has typo in original
174
MB_ICONQUESTION = 0x20
175
MB_ICONEXCLAIMATION = 0x30  # ICONEXCLAIMATION has typo in original  
176
MB_ICONASTERISK = MB_ICONINFOMRAITON = 0x40  # ICONINFOMRAITON has typo in original
177
```
178

179
### Windows MessageBox Constants (Advanced)
180

181
Low-level constants used internally for Windows MessageBox API:
182

183
```python { .api }
184
# Button type flags
185
MB_OK = 0x0
186
MB_OKCANCEL = 0x1
187
MB_ABORTRETRYIGNORE = 0x2
188
MB_YESNOCANCEL = 0x3
189
MB_YESNO = 0x4
190
MB_RETRYCANCEL = 0x5
191
MB_CANCELTRYCONTINUE = 0x6
192

193
# Default button flags
194
MB_DEFAULTBUTTON1 = 0x0
195
MB_DEFAULTBUTTON2 = 0x100
196
MB_DEFAULTBUTTON3 = 0x200
197
MB_DEFAULTBUTTON4 = 0x300
198

199
# Display flags
200
MB_SETFOREGROUND = 0x10000
201
MB_TOPMOST = 0x40000
202

203
# Return value constants
204
IDABORT = 0x3
205
IDCANCEL = 0x2
206
IDCONTINUE = 0x11
207
IDIGNORE = 0x5
208
IDNO = 0x7
209
IDOK = 0x1
210
IDRETRY = 0x4
211
IDTRYAGAIN = 0x10
212
IDYES = 0x6
213
```
214

215
### Special Return Values
216

217
```python { .api }
218
TIMEOUT_RETURN_VALUE = 'Timeout'  # Returned when dialog times out
219
```
220

221
## Platform Behavior
222

223
### Cross-Platform (All Systems)
224
- Uses tkinter for all dialog types
225
- Supports timeout parameter for automatic dismissal
226
- Full customization of button text and count
227
- Works on Windows, macOS, and Linux
228

229
### Windows-Specific Enhancements
230
- Native Windows MessageBox API used for `alert()` and `confirm()` when possible
231
- Better OS integration and native look-and-feel
232
- Falls back to tkinter when:
233
  - Timeout is specified
234
  - Custom button combinations not supported natively
235
  - `_tkinter=True` is explicitly set
236
- `prompt()` and `password()` always use tkinter (no native Windows equivalent)
237

238
## Error Handling
239

240
PyMsgBox handles various error conditions gracefully:
241

242
- **Missing tkinter**: Functions assert tkinter availability before use
243
- **Window closure**: Returns default button text when window is closed via X button
244
- **Timeout**: Returns `TIMEOUT_RETURN_VALUE` when dialog times out
245
- **Invalid parameters**: Converts text parameters to strings automatically
246

247
## Usage Examples
248

249
### Custom Button Combinations
250

251
```python
252
import pymsgbox
253

254
# Yes/No dialog
255
result = pymsgbox.confirm('Save changes?', 'Save', buttons=('Yes', 'No'))
256

257
# Three-button dialog
258
result = pymsgbox.confirm('How to proceed?', 'Options', 
259
                         buttons=('Save', 'Discard', 'Cancel'))
260

261
# Single custom button
262
pymsgbox.alert('Task completed successfully!', 'Success', button='Awesome!')
263
```
264

265
### Timeout Dialogs
266

267
```python
268
import pymsgbox
269

270
# Auto-dismiss after 5 seconds
271
result = pymsgbox.alert('This will close automatically', 'Auto Close', timeout=5000)
272
if result == pymsgbox.TIMEOUT_RETURN_VALUE:
273
    print('Dialog timed out')
274

275
# Timed confirmation
276
result = pymsgbox.confirm('Quick decision needed!', 'Hurry', timeout=3000)
277
```
278

279
### Input Validation
280

281
```python
282
import pymsgbox
283

284
# Get non-empty input
285
while True:
286
    name = pymsgbox.prompt('Enter your name (required):', 'Registration')
287
    if name:  # Not None and not empty
288
        break
289
    if name is None:  # User cancelled
290
        print('Registration cancelled')
291
        break
292

293
# Password with confirmation
294
password = pymsgbox.password('Enter new password:', 'Set Password')
295
if password:
296
    confirm_pwd = pymsgbox.password('Confirm password:', 'Confirm')
297
    if password == confirm_pwd:
298
        print('Password set successfully')
299
    else:
300
        pymsgbox.alert('Passwords do not match!', 'Error')
301
```
302

303
### Integration with GUI Applications
304

305
```python
306
import tkinter as tk
307
import pymsgbox
308

309
# Create main window
310
root = tk.Tk()
311
root.title("My Application")
312

313
def show_dialog():
314
    # Pass root window for proper modal behavior
315
    result = pymsgbox.confirm('Are you sure?', 'Confirm', root=root)
316
    if result == 'OK':
317
        pymsgbox.alert('Action confirmed!', 'Result', root=root)
318

319
button = tk.Button(root, text="Show Dialog", command=show_dialog)
320
button.pack(pady=20)
321

322
root.mainloop()
323
```