EasyGUI_Qt API

EasyGUI_Qt: procedural gui based on PyQt

EasyGUI_Qt is inspired by EasyGUI and contains a number of different basic graphical user interface components

easygui_qt.easygui_qt.get_choice(message='Select one item', title='Title', choices=None)

Simple dialog to ask a user to select an item within a drop-down list

Parameters:

• message – Message displayed to the user, inviting a response
• title – Window title
• choices – iterable (list or tuple) containing the names of the items that can be selected.

Returns:

a string, or None if “cancel” is clicked or window is closed.

>>> import easygui_qt as easy
>>> choices = ["CPython", "Pypy", "Jython", "IronPython"]
>>> reply = easy.get_choice("What is the best Python implementation",
...                         choices=choices)

easygui_qt.easygui_qt.get_list_of_choices(title='Title', choices=None)

Show a list of possible choices to be selected.

Parameters:

• title – Window title
• choices – iterable (list, tuple, …) containing the choices as strings

Returns:

a list of selected items, otherwise an empty list.

>>> import easygui_qt as easy
>>> choices = easy.get_list_of_choices()

easygui_qt.easygui_qt.get_float(message='Choose a number', title='Title', default_value=0.0, min_=-10000, max_=10000, decimals=3)

Simple dialog to ask a user to select a floating point number within a certain range and a maximum precision.

Parameters:

• message – Message displayed to the user, inviting a response
• title – Window title
• default_value – Default value for value appearing in the text box; set to the closest of min_ or max_ if outside of allowed range.
• min – Minimum value allowed
• max – Maximum value allowed
• decimals – Indicate the maximum decimal precision allowed

Returns:

a floating-point number, or None if “cancel” is clicked or window is closed.

>>> import easygui_qt as easy
>>> number = easy.get_float()

Note: depending on the locale of the operating system where this is used, instead of a period being used for indicating the decimals, a comma may appear instead; this is the case for the French version of Windows for example. Therefore, entry of floating point values in this situation will require the use of a comma instead of a period. However, the internal representation will still be the same, and the number passed to Python will be using the familar notation.

easygui_qt.easygui_qt.get_int(message='Choose a number', title='Title', default_value=1, min_=0, max_=100, step=1)

Simple dialog to ask a user to select an integer within a certain range.

Note: get_int() and get_integer() are identical.

Parameters:

• message – Message displayed to the user, inviting a response
• title – Window title
• default_value – Default value for integer appearing in the text box; set to the closest of min_ or max_ if outside of allowed range.
• min – Minimum integer value allowed
• max – Maximum integer value allowed
• step – Indicate the change in integer value when clicking on arrows on the right hand side

Returns:

an integer, or None if “cancel” is clicked or window is closed.

>>> import easygui_qt as easy
>>> number = easy.get_int()

If default_value is larger than max_, it is set to max_; if it is smaller than min_, it is set to min_.

>>> number = easy.get_integer("Enter a number", default_value=125)

easygui_qt.easygui_qt.get_integer(message='Choose a number', title='Title', default_value=1, min_=0, max_=100, step=1)

Simple dialog to ask a user to select an integer within a certain range.

Note: get_int() and get_integer() are identical.

Parameters:

• message – Message displayed to the user, inviting a response
• title – Window title
• default_value – Default value for integer appearing in the text box; set to the closest of min_ or max_ if outside of allowed range.
• min – Minimum integer value allowed
• max – Maximum integer value allowed
• step – Indicate the change in integer value when clicking on arrows on the right hand side

Returns:

an integer, or None if “cancel” is clicked or window is closed.

>>> import easygui_qt as easy
>>> number = easy.get_int()

If default_value is larger than max_, it is set to max_; if it is smaller than min_, it is set to min_.

>>> number = easy.get_integer("Enter a number", default_value=125)

easygui_qt.easygui_qt.get_string(message='Enter your response', title='Title', default_response='')

Simple text input box. Used to query the user and get a string back.

Parameters:

• message – Message displayed to the user, inviting a response
• title – Window title
• default_response – default response appearing in the text box

Returns:

a string, or None if “cancel” is clicked or window is closed.

>>> import easygui_qt as easy
>>> reply = easy.get_string()

>>> reply = easy.get_string("new message", default_response="ready")

easygui_qt.easygui_qt.get_many_strings(title='Title', labels=None, masks=None)

Multiple strings input

Parameters:

• title – Window title
• labels – an iterable containing the labels for to use for the entries
• masks – optional parameter.

Returns:

An ordered dict containing the labels as keys, and the input from the user (empty string by default) as value

The parameter masks if set must be an iterable of the same length as choices and contain either True or False as entries indicating if the entry of the text is masked or not. For example, one could ask for a username and password using get_many_strings as follows [note that get_username_password exists and automatically takes care of specifying the masks and is a better choice for this use case.]

>>> import easygui_qt as easy
>>> labels = ["User name", 'Password']
>>> masks = [False, True]
>>> reply = easy.get_many_strings(labels=labels, masks=masks)
>>> reply
OrderedDict([('User name', 'aroberge'), ('Password', 'not a good password')])

easygui_qt.easygui_qt.get_password(message='Enter your password', title='Title')

Simple password input box. Used to query the user and get a string back.

Parameters:

• message – Message displayed to the user, inviting a response
• title – Window title

Returns:

a string, or None if “cancel” is clicked or window is closed.

>>> import easygui_qt as easy
>>> password = easy.get_password()

easygui_qt.easygui_qt.get_username_password(title='Title', labels=None)

User name and password input box.

Parameters:

• title – Window title
• labels – an iterable containing the labels for “user name” and “password”; if the value not specified, the default values will be used.

Returns:

An ordered dict containing the fields item as keys, and the input from the user (empty string by default) as value

Note: this function is a special case of get_many_strings where the required masks are provided automatically..

>>> import easygui_qt as easy
>>> reply = easy.get_username_password()
>>> reply
OrderedDict([('User name', 'aroberge'), ('Password', 'not a good password')])

easygui_qt.easygui_qt.get_new_password(title='Title', labels=None)

Change password input box.

Parameters:

• title – Window title
• labels – an iterable containing the labels for “Old password” and “New password” and “Confirm new password”. All three labels must be different strings as they are used as keys in a dict - however, they could differ only by a space.

Returns:

An ordered dict containing the fields item as keys, and the input from the user as values.

Note: this function is a special case of get_many_strings where the required masks are provided automatically..

>>> import easygui_qt as easy
>>> reply = easy.get_new_password()

easygui_qt.easygui_qt.get_yes_or_no(message='Answer this question', title='Title')

Simple yes or no question.

Parameters:

• question – Question (string) asked
• title – Window title (string)

Returns:

True for “Yes”, False for “No”, and None for “Cancel”.

>>> import easygui_qt as easy
>>> choice = easy.get_yes_or_no()

easygui_qt.easygui_qt.get_continue_or_cancel(message='Processed will be cancelled!', title='Title', continue_button_text='Continue', cancel_button_text='Cancel')

Continue or cancel question, shown as a warning (i.e. more urgent than simple message)

Parameters:

• question – Question (string) asked
• title – Window title (string)
• continue_button_text – text to display on button
• cancel_button_text – text to display on button

Returns:

True for “Continue”, False for “Cancel”

>>> import easygui_qt as easy
>>> choice = easy.get_continue_or_cancel()

easygui_qt.easygui_qt.get_color_hex()

Using a color dialog, returns a color in hexadecimal notation i.e. a string ‘#RRGGBB’ or “None” if color dialog is dismissed.

>>> import easygui_qt as easy
>>> color = easy.get_color_hex()

easygui_qt.easygui_qt.get_color_rgb(app=None)

Using a color dialog, returns a color in rgb notation i.e. a tuple (r, g, b) or “None” if color dialog is dismissed.

>>> import easygui_qt as easy
>>> easy.set_language('fr')
>>> color = easy.get_color_rgb()

easygui_qt.easygui_qt.get_date(title='Select Date')

Calendar widget

Parameters:title – window title Returns:the selected date as a datetime.date instance

>>> import easygui_qt as easy
>>> date = easy.get_date()

easygui_qt.easygui_qt.get_directory_name(title='Get directory')

Gets the name (full path) of an existing directory

Parameters:title – Window title Returns:the name of a directory or an empty string if cancelled.

>>> import easygui_qt as easy
>>> easy.get_directory_name()

By default, this dialog initially displays the content of the current working directory.

easygui_qt.easygui_qt.get_file_names(title='Get existing file names')

Gets the names (full path) of existing files

Parameters:title – Window title Returns:the list of names (paths) of files selected. (It can be an empty list.)

>>> import easygui_qt as easy
>>> easy.get_file_names()

By default, this dialog initially displays the content of the current working directory.

easygui_qt.easygui_qt.get_save_file_name(title='File name to save')

Gets the name (full path) of of a file to be saved.

Parameters:title – Window title Returns:the name (path) of file selected

The user is warned if the file already exists and can choose to cancel. However, this dialog actually does NOT save any file: it only return a string containing the full path of the chosen file.

>>> import easygui_qt as easy
>>> easy.get_save_file_name()

By default, this dialog initially displays the content of the current working directory.

easygui_qt.easygui_qt.handle_exception(title='Exception raised!')

Displays a traceback in a window if an exception is raised. If the user clicks on “abort”, sys.exit() is called and the program ends. If the user clicks on “ignore”, the program resumes its execution.

Parameters:title – the window title

easygui_qt.easygui_qt.set_font_size(font_size)

Simple method to set font size.

Parameters:font_size – integer value

Does not create a GUI widget; but affects the appearance of future GUI widgets.

>>> import easygui_qt as easy
>>> easy.set_font_size(20)
>>> easy.show_message()

easygui_qt.easygui_qt.get_language(title='Select language', name='Language codes', instruction=None)

Dialog to choose language based on some locale code for files found on default path.

Parameters:

• title – Window title
• name – Heading for valid values of locale appearing in checkboxes
• instruction – Like the name says; when set to None, a default string is used which includes the current language used.

The first time an EasyGUI_Qt widget is created in a program, the PyQt language files found in the standard location of the user’s computer are scanned and recorded; these provide some translations of standard GUI components (like name of buttons). Note that “en” is not found as a locale (at least, not on the author’s computer) but using “default” reverts the choice to the original (English here).

>>> import easygui_qt as easy
>>> easy.get_language()

easygui_qt.easygui_qt.set_language(locale)

Sets the locale, if available

Parameters:locale – standard code for locale (e.g. ‘fr’, ‘en_CA’)

Does not create a GUI widget, but affect the appearance of widgets created afterwards

>>> import easygui_qt as easy
>>> easy.set_locale('es')

>>> # after setting the locale
>>> easy.get_yes_or_no()

easygui_qt.easygui_qt.get_abort(message='Major problem - or at least we think there is one...', title='Major problem encountered!')

Displays a message about a problem. If the user clicks on “abort”, sys.exit() is called and the program ends. If the user clicks on “ignore”, the program resumes its execution.

Parameters:

• title – the window title
• message – the message to display

>>> import easygui_qt as easy
>>> easy.get_abort()

easygui_qt.easygui_qt.show_message(message='Message', title='Title')

Simple message box.

Parameters:

• message – message string
• title – window title

>>> import easygui_qt as easy
>>> easy.show_message()

easygui_qt.easygui_qt.show_file(file_name=None, title='Title', file_type='text')

Displays a file in a window. While it looks as though the file can be edited, the only changes that happened are in the window and nothing can be saved.

Parameters:

• title – the window title
• file_name – the file name, (path) relative to the calling program
• file_type – possible values: text, code, html, python.

By default, file_type is assumed to be text; if set to code, the content is displayed with a monospace font and, if set to python, some code highlighting is done. If the file_type is html, it is processed assuming it follows html syntax.

Note: a better Python code hightlighter would be most welcome!

>>> import easygui_qt as easy
>>> easy.show_file()

easygui_qt.easygui_qt.show_text(title='Title', text='')

Displays some text in a window.

Parameters:

• title – the window title
• code – a string to display in the window.

>>> import easygui_qt as easy
>>> easy.show_code()

easygui_qt.easygui_qt.show_code(title='Title', text='')

Displays some text in a window, in a monospace font.

Parameters:

• title – the window title
• code – a string to display in the window.

>>> import easygui_qt as easy
>>> easy.show_code()

easygui_qt.easygui_qt.show_html(title='Title', text='')

Displays some html text in a window.

Parameters:

• title – the window title
• code – a string to display in the window.

>>> import easygui_qt as easy
>>> easy.show_html()

easygui_qt.easygui_qt.find_help()

Opens a web browser, pointing at the documention about EasyGUI_Qt available on the web.