Welcome to PyMsgBox’s documentation!¶

Contents:

Quickstart¶

On Linux Python 2, you need to first install Tkinter by running: sudo apt-get install python-tk

All of the arguments to PyMsgBox functions are optional.

>>> import pymsgbox
>>> pymsgbox.alert('This is an alert.')
>>> pymsgbox.confirm('Click OK to continue, click Cancel to cancel.')
>>> pymsgbox.prompt('Enter your name.')
>>> pymsgbox.password('Enter your password. (It will appear hidden in this text field.)')

Here are the default arguments for each function.

>>> pymsgbox.alert(text='', title='', button='OK')
>>> pymsgbox.confirm(text='', title='', buttons=['OK', 'Cancel'])
>>> pymsgbox.prompt(text='', title='' , defaultValue='')
>>> pymsgbox.password(text='', title='', defaultValue='', mask='*')

To use native operating system message boxes, run the following:

>>> import pymsgbox.native as pymsgbox

(Only a few of the message boxes have native support. Unsupported message boxes will default to the normal message boxes.)

PyMsgBox Basics¶

Installation¶

PyMsgBox can be installed from PyPI with pip:

pip install PyMsgBox

OS X and Linux may require sudo to install the module:

sudo pip install PyMsgBox

PyMsgBox uses Python’s built-in TKinter module for its GUI. It is cross-platform and runs on Python 2 and Python 3.

PyMsgBox’s code is derived from Stephen Raymond Ferg’s EasyGui. http://easygui.sourceforge.net/

Usage¶

There are four functions in PyMsgBox, which follow JavaScript’s message box naming conventions:

alert(text='', title='', button='OK')
Displays a simple message box with text and a single OK button. Returns the text of the button clicked on.
>>> pymsgbox.alert('This is an alert.', 'Alert!')
'OK'
confirm(text='', title='', buttons=['OK', 'Cancel'])
Displays a message box with OK and Cancel buttons. Number and text of buttons can be customized. Returns the text of the button clicked on.
>>> pymsgbox.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'])
"Yes, I'm sure."
prompt(text='', title='', defaultValue='')
Displays a message box with text input, and OK & Cancel buttons. Returns the text entered, or None if Cancel was clicked.
>>> pymsgbox.prompt('What does the fox say?', default='This reference dates this example.')
'This reference dates this example.'
password(text='', title='', defaultValue='', mask='*')
Displays a message box with text input, and OK & Cancel buttons. Typed characters appear as *. Returns the text entered, or None if Cancel was clicked.
>>> pymsgbox.password('Enter your password.')
'12345'

Timeout¶

All four functions have a timeout parameter which takes a number of milliseconds. At the end of the timeout, the message box will close and have a return value of 'Timeout'.

>>> pymsgbox.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'], timeout=2000)  # closes after 2000 milliseconds (2 seconds)
"Timeout"

Localization¶

You can change the default 'OK', 'Cancel‘, and 'Timeout' strings by changing pymsgbox.OK_TEXT, pymsgbox.CANCEL_TEXT, and pymsgbox.TIMEOUT_TEXT variables respectively.

Native Message Boxes¶

In addition to displaying message boxes using Python’s built-in TkInter GUI toolkit, PyMsgBox also has limited support for displaying message boxes by calling the operating system’s native functions. These exist in the native module. To use them, call:

>>> import pymsgbox
>>> pymsgbox.native.alert('This is an alert.', 'The title.')

Or, to avoid changing your function calls to use pymsgbox.native, run:

>>> import pymsgbox.native as pymsgbox

Support¶

These are the platforms and functions that have native message box support. Functions that do are not supported will default back to the normal TkInter-based message box.

Support as of v1.0.1:

	Windows	OS X	Linux	JVM / Jython
`alert()`	Yes	No	No	No
`confirm()`	Yes	No	No	No
`prompt()`	No	No	No	No
`password()`	No	No	No	No

Special Notes¶

Windows - alert()¶

The message box will only show a button with text “OK”, no matter what is passed for the button argument. The button argument will be the text that is returned by the function, just like the TkInter alert().

>>> pymsgbox.native.alert('This is an alert.', 'Alert!')
'OK'

Windows - confirm()¶

There will only be buttons “OK” and “Cancel”, no matter what is passed for the buttons argument. If “OK” is clicked, the first item in the buttons list is returned (by default, this is 'OK'). If “Cancel” is clicked, the second item in the buttons list is returned (by default, this is 'Cancel'), just like the TkInter confirm().

>>> pymsgbox.native.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'])
"Yes, I'm sure."