easygui API

easygui.buttonbox(msg='', title=' ', choices=('Button[1]', 'Button[2]', 'Button[3]'), image=None, images=None, default_choice=None, cancel_choice=None, callback=None, run=True)

Display a msg, a title, an image, and a set of buttons. The buttons are defined by the members of the choices global_state.

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• choices (list) – a list or tuple of the choices to be displayed
• image (str) – (Only here for backward compatibility)
• images (str) – Filename of image or iterable or iteratable of iterable to display
• default_choice (str) – The choice you want highlighted when the gui appears

Returns:

the text of the button that the user selected

easygui.diropenbox(msg=None, title=None, default=None)

A dialog to get a directory name. Note that the msg argument, if specified, is ignored.

Returns the name of a directory, or None if user chose to cancel.

If the “default” argument specifies a directory name, and that directory exists, then the dialog box will start with that directory.

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• default (str) – starting directory when dialog opens

Returns:

Normalized path selected by user

easygui.fileopenbox(msg=None, title=None, default='*', filetypes=None, multiple=False)

A dialog to get a file name.

About the “default” argument

The “default” argument specifies a filepath that (normally) contains one or more wildcards. fileopenbox will display only files that match the default filepath. If omitted, defaults to “*” (all files in the current directory).

WINDOWS EXAMPLE:

...default="c:/myjunk/*.py"

will open in directory c:myjunkand show all Python files.

WINDOWS EXAMPLE:

...default="c:/myjunk/test*.py"

will open in directory c:myjunkand show all Python files whose names begin with “test”.

Note that on Windows, fileopenbox automatically changes the path separator to the Windows path separator (backslash).

About the “filetypes” argument

If specified, it should contain a list of items, where each item is either:

• a string containing a filemask # e.g. “*.txt”
• a list of strings, where all of the strings except the last one are filemasks (each beginning with “*.”, such as “*.txt” for text files, “*.py” for Python files, etc.). and the last string contains a filetype description

EXAMPLE:

filetypes = ["*.css", ["*.htm", "*.html", "HTML files"]  ]

Note

If the filetypes list does not contain (“All files”,”*”), it will be added.

If the filetypes list does not contain a filemask that includes the extension of the “default” argument, it will be added. For example, if default=”*abc.py” and no filetypes argument was specified, then “*.py” will automatically be added to the filetypes argument.

Parameters:

• msg (str) – the msg to be displayed.
• title (str) – the window title
• default (str) – filepath with wildcards
• filetypes (object) – filemasks that a user can choose, e.g. “*.txt”
• multiple (bool) – If true, more than one file can be selected

Returns:

the name of a file, or None if user chose to cancel

easygui.filesavebox(msg=None, title=None, default='', filetypes=None)

A file to get the name of a file to save. Returns the name of a file, or None if user chose to cancel.

The “default” argument should contain a filename (i.e. the current name of the file to be saved). It may also be empty, or contain a filemask that includes wildcards.

The “filetypes” argument works like the “filetypes” argument to fileopenbox.

Parameters:

• msg (str) – the msg to be displayed.
• title (str) – the window title
• default (str) – default filename to return
• filetypes (object) – filemasks that a user can choose, e.g. ” *.txt”

Returns:

the name of a file, or None if user chose to cancel

easygui.textbox(msg='', title=' ', text='', codebox=False, callback=None, run=True)

Display a message and a text to edit

msg : string

text displayed in the message area (instructions...)

title : str

the window title

text: str, list or tuple

text displayed in textAreas (editable)

codebox: bool

if True, don’t wrap and width is set to 80 chars

callback: function

if set, this function will be called when OK is pressed

run: bool

if True, a box object will be created and returned, but not run

None

If cancel is pressed

str

If OK is pressed returns the contents of textArea

easygui.ynbox(msg='Shall I continue?', title=' ', choices=('[<F1>]Yes', '[<F2>]No'), image=None, default_choice='[<F1>]Yes', cancel_choice='[<F2>]No')

Display a msgbox with choices of Yes and No.

The returned value is calculated this way:

if the first choice ("Yes") is chosen, or if the dialog is cancelled:
    return True
else:
    return False

If invoked without a msg argument, displays a generic request for a confirmation that the user wishes to continue. So it can be used this way:

if ynbox():
    pass # continue
else:
    sys.exit(0)  # exit the program

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• choices (list) – a list or tuple of the choices to be displayed
• image (str) – Filename of image to display
• default_choice (str) – The choice you want highlighted when the gui appears
• cancel_choice (str) – If the user presses the ‘X’ close, which button should be pressed

Returns:

True if ‘Yes’ or dialog is cancelled, False if ‘No’

easygui.ccbox(msg='Shall I continue?', title=' ', choices=('C[o]ntinue', 'C[a]ncel'), image=None, default_choice='Continue', cancel_choice='Cancel')

Display a msgbox with choices of Continue and Cancel.

The returned value is calculated this way:

if the first choice ("Continue") is chosen,
  or if the dialog is cancelled:
    return True
else:
    return False

If invoked without a msg argument, displays a generic request for a confirmation that the user wishes to continue. So it can be used this way:

if ccbox():
    pass # continue
else:
    sys.exit(0)  # exit the program

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• choices (list) – a list or tuple of the choices to be displayed
• image (str) – Filename of image to display
• default_choice (str) – The choice you want highlighted when the gui appears
• cancel_choice (str) – If the user presses the ‘X’ close, which button should be pressed

Returns:

True if ‘Continue’ or dialog is cancelled, False if ‘Cancel’

easygui.boolbox(msg='Shall I continue?', title=' ', choices=('[Y]es', '[N]o'), image=None, default_choice='Yes', cancel_choice='No')

Display a boolean msgbox.

The returned value is calculated this way:

if the first choice is chosen, or if the dialog is cancelled:
    returns True
else:
    returns False

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• choices (list) – a list or tuple of the choices to be displayed
• image (str) – Filename of image to display
• default_choice (str) – The choice you want highlighted when the gui appears
• cancel_choice (str) – If the user presses the ‘X’ close, which button should be pressed

Returns:

True if first button pressed or dialog is cancelled, False if second button is pressed

easygui.indexbox(msg='Shall I continue?', title=' ', choices=('Yes', 'No'), image=None, default_choice='Yes', cancel_choice='No')

Display a buttonbox with the specified choices.

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• choices (list) – a list or tuple of the choices to be displayed
• image (str) – Filename of image to display
• default_choice (str) – The choice you want highlighted when the gui appears
• cancel_choice (str) – If the user presses the ‘X’ close, which button should be pressed

Returns:

the index of the choice selected, starting from 0

easygui.msgbox(msg='(Your message goes here)', title=' ', ok_button='OK', image=None, root=None)

Display a message box

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• ok_button (str) – text to show in the button
• image (str) – Filename of image to display
• root (tk_widget) – Top-level Tk widget

Returns:

the text of the ok_button

easygui.integerbox(msg='', title=' ', default=None, lowerbound=0, upperbound=99, image=None, root=None)

Show a box in which a user can enter an integer.

In addition to arguments for msg and title, this function accepts integer arguments for “default”, “lowerbound”, and “upperbound”.

The default, lowerbound, or upperbound may be None.

When the user enters some text, the text is checked to verify that it can be converted to an integer between the lowerbound and upperbound.

If it can be, the integer (not the text) is returned.

If it cannot, then an error msg is displayed, and the integerbox is redisplayed.

If the user cancels the operation, None is returned.

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• default (int) – The default value to return
• lowerbound (int) – The lower-most value allowed
• upperbound (int) – The upper-most value allowed
• image (str) – Filename of image to display
• root (tk_widget) – Top-level Tk widget

Returns:

the integer value entered by the user

easygui.multenterbox(msg='Fill in values for the fields.', title=' ', fields=[], values=[], callback=None, run=True)

Show screen with multiple data entry fields.

If there are fewer values than names, the list of values is padded with empty strings until the number of values is the same as the number of names.

If there are more values than names, the list of values is truncated so that there are as many values as names.

Returns a list of the values of the fields, or None if the user cancels the operation.

Here is some example code, that shows how values returned from multenterbox can be checked for validity before they are accepted:

msg = "Enter your personal information"
title = "Credit Card Application"
fieldNames = ["Name","Street Address","City","State","ZipCode"]
fieldValues = []  # we start with blanks for the values
fieldValues = multenterbox(msg,title, fieldNames)

# make sure that none of the fields was left blank
while 1:
    if fieldValues is None: break
    errmsg = ""
    for i in range(len(fieldNames)):
        if fieldValues[i].strip() == "":
            errmsg += ('"%s" is a required field.\n\n' % fieldNames[i])
    if errmsg == "":
        break # no problems found
    fieldValues = multenterbox(errmsg, title, fieldNames, fieldValues)

print("Reply was: %s" % str(fieldValues))

Parameters:

• msg (str) – the msg to be displayed.
• title (str) – the window title
• fields (list) – a list of fieldnames.
• values (list) – a list of field values

Returns:

String

easygui.enterbox(msg='Enter something.', title=' ', default='', strip=True, image=None, root=None)

Show a box in which a user can enter some text.

You may optionally specify some default text, which will appear in the enterbox when it is displayed.

Example:

reply = enterbox(....)
if reply:
    ...
else:
    ...

Parameters:

• msg (str) – the msg to be displayed.
• title (str) – the window title
• default (str) – value returned if user does not change it
• strip (bool) – If True, the return value will have its whitespace stripped before being returned

Returns:

the text that the user entered, or None if he cancels the operation.

easygui.exceptionbox(msg=None, title=None)

Display a box that gives information about an exception that has just been raised.

The caller may optionally pass in a title for the window, or a msg to accompany the error information.

Note that you do not need to (and cannot) pass an exception object as an argument. The latest exception will automatically be used.

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title

Returns:

None

easygui.choicebox(msg='Pick an item', title='', choices=[], preselect=0, callback=None, run=True)

Present the user with a list of choices. return the choice that he selects.

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• choices (list) – a list or tuple of the choices to be displayed

Returns:

List containing choice selected or None if cancelled

easygui.codebox(msg='', title=' ', text='')

Display some text in a monospaced font, with no line wrapping. This function is suitable for displaying code and text that is formatted using spaces.

The text parameter should be a string, or a list or tuple of lines to be displayed in the textbox.

Parameters:

• msg (str) – the msg to be displayed
• title (str) – the window title
• text (str) – what to display in the textbox

easygui.passwordbox(msg='Enter your password.', title=' ', default='', image=None, root=None)

Show a box in which a user can enter a password. The text is masked with asterisks, so the password is not displayed.

Parameters:

• msg (str) – the msg to be displayed.
• title (str) – the window title
• default (str) – value returned if user does not change it

Returns:

the text that the user entered, or None if he cancels the operation.

easygui.multpasswordbox(msg='Fill in values for the fields.', title=' ', fields=(), values=(), callback=None, run=True)

Same interface as multenterbox. But in multpassword box, the last of the fields is assumed to be a password, and is masked with asterisks.

Parameters:

• msg (str) – the msg to be displayed.
• title (str) – the window title
• fields (list) – a list of fieldnames.
• values (list) – a list of field values

Returns:

String

Example

Here is some example code, that shows how values returned from multpasswordbox can be checked for validity before they are accepted:

msg = "Enter logon information"
title = "Demo of multpasswordbox"
fieldNames = ["Server ID", "User ID", "Password"]
fieldValues = []  # we start with blanks for the values
fieldValues = multpasswordbox(msg,title, fieldNames)

# make sure that none of the fields was left blank
while 1:
    if fieldValues is None: break
    errmsg = ""
    for i in range(len(fieldNames)):
        if fieldValues[i].strip() == "":
            errmsg = errmsg + ('"%s" is a required field.\n\n' %
             fieldNames[i])
        if errmsg == "": break # no problems found
    fieldValues = multpasswordbox(errmsg, title,
      fieldNames, fieldValues)

print("Reply was: %s" % str(fieldValues))

easygui.multchoicebox(msg='Pick an item', title='', choices=[], preselect=0, callback=None, run=True)

Same as choicebox, but the user can select many items.

class easygui.EgStore(filename)

Bases: object

A class to support persistent storage.

You can use EgStore to support the storage and retrieval of user settings for an EasyGui application.

First: define a class named Settings as a subclass of EgStore

class Settings(EgStore):
    def __init__(self, filename):  # filename is required
        # specify default values for variables that this application wants to remember
        self.user_id = ''
        self.target_server = ''
        settings.restore()

Second: create a persistent Settings object*

settings = Settings('app_settings.txt')
settings.user_id = 'obama_barak'
settings.targetServer = 'whitehouse1'
settings.store()

# run code that gets a new value for user_id, and persist the settings
settings.user_id = 'biden_joe'
settings.store()

Example C: recover the Settings instance, change an attribute, and store it again.

settings = Settings('app_settings.txt')
settings.restore()
print settings
settings.user_id = 'vanrossum_g'
settings.store()

kill()

Delete this store’s file if it exists.

restore()

store()

Save this store to a pickle file. All directories in filename must already exist.

easygui.abouteasygui()

shows the easygui revision history

easygui.egdemo()

Run the EasyGui demo.