msl.qt.prompt module¶

Convenience functions to prompt the user.

The following functions create a dialog window to either notify the user of an event that happened or to request information from the user.

msl.qt.prompt.critical(message, *, title=None, font=None)[source]¶

Display a critical message in a dialog window.

Parameters:

message (str or Exception) – The message to display. The message can use HTML/CSS markup, for example, '<html>A critical error occurred!</html>'
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).

msl.qt.prompt.double(message, *, title=None, font=None, value=0, minimum=-2147483647, maximum=2147483647, step=1, decimals=2)[source]¶

Request a double-precision value (a Python float data type).

Parameters:

message (str) – The message that is shown to the user to describe what the value represents. The message can use HTML/CSS markup, for example, '<html>Enter a mass, in μg</html>'
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).
value (float, optional) – The initial value.
minimum (float, optional) – The minimum value that the user can enter.
maximum (float, optional) – The maximum value that the user can enter.
step (float, optional) – The step size by which the value is increased and decreased.
decimals (int, optional) – The number of digits that are displayed after the decimal point.

Returns:

float or None – The value or None if the user cancelled the request.

msl.qt.prompt.filename(*, title='Select File', directory=None, filters=None, multiple=False)[source]¶

Request to select the file(s) to open.

Parameters:

title (str, optional) – The text to display in the title bar of the dialog window.
directory (str, optional) – The initial directory to start in.

filters (str, list of str or dict, optional) –

Only filenames that match the specified filters are shown.

Examples:

'Images (*.png *.xpm *.jpg)'
'Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)'
['Images (*.png *.xpm *.jpg)', 'Text files (*.txt)', 'XML files (*.xml)']
{'Images': ('*.png', '*.xpm', '*.jpg'), 'Text files': '*.txt'}

multiple (bool, optional) – Whether multiple files can be selected.

Returns:

str, list of str or None – The name(s) of the file(s) to open or None if the user cancelled the request.

msl.qt.prompt.folder(*, title='Select Folder', directory=None)[source]¶

Request to select an existing folder or to create a new folder.

Parameters:

title (str, optional) – The text to display in the title bar of the dialog window.
directory (str, optional) – The initial directory to start in.

Returns:

str or None – The name of the selected folder or None if the user cancelled the request.

msl.qt.prompt.information(message, *, title=None, font=None)[source]¶

Display an information message in a dialog window.

Parameters:

message (str or Exception) – The message to display. The message can use HTML/CSS markup, for example, '<html>The temperature is 21.3 °C</html>'
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).

msl.qt.prompt.integer(message, *, title=None, font=None, value=0, minimum=-2147483647, maximum=2147483647, step=1)[source]¶

Request an integer value.

Parameters:

message (str) – The message that is shown to the user to describe what the value represents. The message can use HTML/CSS markup, for example, '<html>Enter a mass, in μg</html>'
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).
value (int, optional) – The initial value.
minimum (int, optional) – The minimum value that the user can enter.
maximum (int, optional) – The maximum value that the user can enter.
step (int, optional) – The step size by which the value is increased and decreased.

Returns:

int or None – The value or None if the user cancelled the request.

msl.qt.prompt.item(message, items, *, title=None, font=None, index=0)[source]¶

Request an item from a list of items.

Parameters:

message (str) – The message that is shown to the user to describe what the list of items represent. The message can use HTML/CSS markup.
items (list or tuple) – The list of items to choose from. The items can be of any data type.
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).
index (int, optional) – The index of the initial item that is selected.

Returns:

The selected item or None if the user cancelled the request.

Notes

The data type of the selected item is preserved. For example, if items = [1, 2.0, 2+3j, 'hello', b'world', True, QtWidgets.QPushButton] and the user selects the 2+3j item then a complex data type is returned.

msl.qt.prompt.comments(*, path=None, title=None, even_row_color='#FFFFFF', odd_row_color='#EAF2F8')[source]¶

Ask the user to enter comments.

Opens a QtWidgets.QDialog to allow for a user to enter comments about a task that they are performing. The dialog provides a table of all the previous comments that have been used. Comments that are in the table can be deleted by selecting the desired row(s) and pressing the Delete key or the comment in a row can be selected by double-clicking on a row.

This function is useful when acquiring data, and you want to include comments about how the data was acquired. Using a prompt to enter comments forces you to enter a new comment (or use a previous comment) every time you acquire data rather than having the comments in a for example, QtWidgets.QPlainTextEdit, which you might forget to update before acquiring the next data set.

Parameters:

path (str, optional) – The path to a JSON file that contains the history of the comments that have been used. If None then the default file is used. The file will automatically be created if it does not exist.
title (str, optional) – The text to display in the title bar of the dialog window.
even_row_color – The background color of the even-numbered rows in the history table. See to_qcolor() for details about the different data types that are supported.
odd_row_color – The background color of the odd-numbered rows in the history table. See to_qcolor() for details about the different data types that are supported.

Returns:

str – The comment that was entered.

msl.qt.prompt.save(*, title='Save As', directory=None, filters=None, options=None)[source]¶

Request to enter the name of a file to save.

Parameters:

title (str, optional) – The text to display in the title bar of the dialog window.
directory (str, optional) – The initial directory to start in.

filters (str, list of str or dict, optional) –

Only filenames that match the specified filters are shown.

Examples:

'Images (*.png *.xpm *.jpg)'
'Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)'
['Images (*.png *.xpm *.jpg)', 'Text files (*.txt)', 'XML files (*.xml)']
{'Images': ('*.png', '*.xpm', '*.jpg'), 'Text files': '*.txt'}

options (QtWidgets.QFileDialog.Option, optional) – Specify additional options on how to run the dialog.

Returns:

str or None – The name of the file to save or None if the user cancelled the request.

msl.qt.prompt.text(message, *, title=None, font=None, value='', multi_line=False, echo=EchoMode.Normal)[source]¶

Request text.

Parameters:

message (str) – The message that is shown to the user to describe what the list of items represent. The message can use HTML/CSS markup.
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).
value (str, optional) – The initial value.
multi_line (bool, optional) – Whether the entered text can span multiple lines.
echo (int or QLineEdit.EchoMode, optional) – The echo mode for the text value. Useful if requesting a password.

Returns:

str or None – The text that the user entered or None if the user cancelled the request.

msl.qt.prompt.password(message, *, title=None, font=None)[source]¶

Request a password.

Parameters:

message (str) – The message that is shown to the user to describe what the list of items represent. The message can use HTML/CSS markup.
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).

Returns:

str or None – The password or None if the user cancelled the request.

msl.qt.prompt.warning(message, *, title=None, font=None)[source]¶

Display a warning message in a dialog window.

Parameters:

message (str or Exception) – The message to display. The message can use HTML/CSS markup, for example, '<html>A warning...</html>'
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).

msl.qt.prompt.ok_cancel(message, *, title=None, font=None, default=True)[source]¶

Ask for a response to a message where the logical options are Ok or Cancel.

Parameters:

message (str) – The message to ask the user. The message can use HTML/CSS markup.
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).
default (bool, optional) – The answer to be selected by default. If True then Ok is the default answer, otherwise Cancel is the default answer.

Returns:

bool or None – True if the user answered Ok, None if the user answered Cancel.

msl.qt.prompt.yes_no(message, *, title=None, font=None, default=True)[source]¶

Ask for a response to a message where the logical options are Yes or No.

Parameters:

message (str) – The message to ask the user. The message can use HTML/CSS markup.
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).
default (bool, optional) – The answer to be selected by default. If True then Yes is the default answer, otherwise No is the default answer.

Returns:

bool – True if the user answered Yes, False if the user answered No.

msl.qt.prompt.yes_no_cancel(message, *, title=None, font=None, default=True)[source]¶

Ask for a response to a message where the logical options are Yes, No or Cancel.

Parameters:

message (str) – The message to ask the user. The message can use HTML/CSS markup.
title (str, optional) – The text to display in the title bar of the dialog window. If None then uses the text in the title bar of the active window.
font (int, str, tuple or QtGui.QFont, optional) – The font to use. If an int then the point size, if a str then the family name, if a tuple then the (family name, point size).
default (bool, optional) – The answer to be selected by default. If True then Yes is the default answer, if False then No is the default answer, else if None then Cancel is the default answer.

Returns:

bool or None – True if the user answered Yes, False if the user answered No, or None if the user answered Cancel.