msl.qt.convert module

Functions to convert objects.

msl.qt.convert.icon_to_base64(icon, *, fmt='png')[source]

Convert an icon to a QtCore.QByteArray encoded as Base64.

This function is useful if you want to save icons in a database, use it in a data URI scheme, or if you want to use icons in your GUI and rather than loading icons from a file on the hard disk you define your icons in a Python module as Base64 variables. Loading the icons from the hard disk means that you must also distribute the icons with your Python code if you share your code.

Parameters:

  • icon – An icon with a data type that is handled by to_qicon().

  • fmt (str, optional) – The icon format to use when converting. The supported values are: BMP, JPG, JPEG and PNG.

Returns:

QtCore.QByteArray – The Base64 representation of the icon.

Raises:

  • OSError – If the icon file cannot be found.

  • ValueError – If the icon format, fmt, to use for converting is not supported.

msl.qt.convert.number_to_si(number, unicode=True)[source]

Convert a number to be represented with an SI prefix.

The hecto (h), deka (da), deci (d) and centi (c) prefixes are not used.

Parameters:

  • number (int or float) – The number to convert.

  • unicode (bool, optional) – Whether to use the unicode µ symbol for micro.

Returns:

  • float – The number rescaled.

  • str – The SI prefix.

Examples

>>> number_to_si(0.0123)
(12.3, 'm')
>>> number_to_si(123456.789)
(123.456789, 'k')
>>> number_to_si(712.123e14)
(71.2123, 'P')
>>> number_to_si(1.23e-13)
(123.0, 'f')
msl.qt.convert.print_base64(icon, *, size=None, name='', line_width=80, file=None)[source]

Print the Base64 representation of an icon.

Parameters:

  • icon – Passed to to_qicon().

  • size – Passed to to_qicon().

  • name (str, optional) – The name of the icon.

  • line_width (int, optional) – The maximum number of characters in a line.

  • file (file-like object) – Where to print the output. Default is sys.stdout.

Examples

>>> print_base64(QtWidgets.QStyle.StandardPixmap.SP_MediaPlay, size=16)
b'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAk6AAAJOgHwZJJKAAA' \
b'AGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48GgAAAJ9JREFUOI3djzEKwlAQRGcXO1' \
b'ERrIQw/i7gCTyOvZfyTtaBjaCVEH9n8V3bID/GpBKnnJ157AA/p6Io1kPy8m6QjCLyVFVWVXXvA' \
b'2jOdPdFSqkheRoFaGlL8hFCOHQFshMAzDLZCKA0s+uQD9qaA7iQPI8FAEBjZpsxgCgiOzNbAkjt' \
b'w6Sn6O5+rOt63xX4BLiZ2arvtdyEqaqW35T/RC/uTS/6P1rpJAAAAABJRU5ErkJggg=='

>>> print_base64(QtWidgets.QStyle.StandardPixmap.SP_MediaPlay, name='my_play_icon', size=32)
my_play_icon = b'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAk6' \
               b'AAAJOgHwZJJKAAAAGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48' \
               b'GgAAAaVJREFUWIXtlLFuE0EURc8bO8gyiiMhUYC8M2vHldPhz+AD6LDSp0FU' \
               b'QMsHUEJBAx+QjoKGKlIKhCihcDSzcYEsCylGXoTA+yhQUBSReLXebINPOzP3' \
               b'Hr0nDaxZs4Qoim5fZb657LDf718zxhw7595ba3cqF0jT1ABz4I4x5sBa+7zb' \
               b'7W5VJnAGUdUtERkuFoujOI53ASlD4NKQOI4bqjoBNs8dzYBj4H4I4cMqAnkn' \
               b'cJ4WsAO8s9a+arfbN6oW+CsiIvdqtdqo0+nsFckruoJ/8Q2YqOowSZKDvAKr' \
               b'TuAsm8C2iLxxzu07525VLXBKC7gLfHLOPR4MBhtVCwBsAC1VfTSdTo+iKNqu' \
               b'WgAAEVHglzEmu+hO/Yq6f/LnB30aQngGLKoUOAHe1uv1vdFoNFl2uUyBmYh8' \
               b'AYbe+8O8j8oQ+AGkIvLEe/8CuHDfZQsoMFPV/SzLHo7H469FQgoJiMgJEIBh' \
               b'COFjkYyiAt+BNMuyB0mSvF6l+JS8/4CKyAx42Wg0OmWVw5IJNJvNbD6fXwcO' \
               b'RWTXe/+5rOLc9Hq9m5WXrlnzX/EbbYB/8sxND3cAAAAASUVORK5CYII='
msl.qt.convert.rescale_icon(icon, size, *, aspect_mode=AspectRatioMode.KeepAspectRatio)[source]

Rescale an icon.

Parameters:

  • icon – Any object that is supported by to_qicon().

  • size (int, float, tuple of int or QtCore.QSize) – Rescale the icon to the specified size. If an int then set the width and the height to be the size value. If a float then a scaling factor. If a tuple then the (width, height) values.

  • aspect_mode (QtCore.Qt.AspectRatioMode, optional) – How to maintain the aspect ratio if rescaling. The default mode is to keep the aspect ratio.

Returns:

QtGui.QPixmap – The rescaled icon.

msl.qt.convert.si_to_number(string)[source]

Convert a string with an SI prefix to a number.

Parameters:

string (str) – The string to convert.

Returns:

float – The number.

Examples

>>> si_to_number('12.3m')
0.0123
>>> si_to_number('123.456789k')
123456.789
>>> si_to_number('71.2123P')
7.12123e+16
>>> si_to_number('123f')
1.23e-13
msl.qt.convert.to_qcolor(*args)[source]

Convert the input argument(s) into a QtGui.QColor.

Parameters:

args –

The argument(s) to convert to a QtGui.QColor.

  • R, G, B, [A] \(\rightarrow\) values can be int 0-255 or float 0.0-1.0

  • (R, G, B, [A]) \(\rightarrow\) tuple of int 0-255 or float 0.0-1.0

  • int or QtCore.Qt.GlobalColor \(\rightarrow\) a pre-defined enum value

  • float \(\rightarrow\) a greyscale value between 0.0-1.0

  • QtGui.QColor \(\rightarrow\) returns a copy

  • str \(\rightarrow\) see here for examples

Returns:

QtGui.QColor – The input argument(s) converted to a QtGui.QColor.

Examples

>>> color = to_qcolor(48, 127, 69)
>>> color = to_qcolor((48, 127, 69))
>>> color = to_qcolor(0.5)  # greyscale -> (127, 127, 127, 255)
>>> color = to_qcolor(0.2, 0.45, 0.3, 0.5)
>>> color = to_qcolor('red')
>>> color = to_qcolor(Qt.GlobalColor.darkBlue)
>>> color = to_qcolor(15)  # 15 == Qt.GlobalColor.darkBlue
msl.qt.convert.to_qfont(*args)[source]

Convert the input argument(s) into a QtGui.QFont.

Parameters:

args –

The argument(s) to convert to a QtGui.QFont.

  • If int or float then the point size.

  • If str then the font family name(s).

  • If QtGui.QFont then returns a copy.

  • If multiple arguments then

    • family name(s), point size

    • family name(s), point size, weight

    • family name(s), point size, weight, is italic

Returns:

QtGui.QFont – The input argument(s) converted to a QtGui.QFont.

Examples

>>> font = to_qfont(48)
>>> font = to_qfont(23.4)
>>> font = to_qfont('Ariel')
>>> font = to_qfont('Ariel', 16)
>>> font = to_qfont('Ariel', 16, QtGui.QFont.Weight.Bold)
>>> font = to_qfont('Ariel', 16, 50, True)

If you are using Qt 6.1+ then you can specify multiple family names >>> font = to_qfont(‘Ariel’, ‘Papyrus’) >>> font = to_qfont(‘Ariel’, ‘Papyrus’, ‘Helvetica [Cronyx]’, 16) >>> font = to_qfont(‘Ariel’, ‘Helvetica’, 16, QtGui.QFont.Weight.Bold) >>> font = to_qfont(‘Ariel’, ‘Papyrus’, ‘Times’, 16, QtGui.QFont.Weight.Bold, True)

msl.qt.convert.to_qicon(obj, *, size=None, aspect_mode=AspectRatioMode.KeepAspectRatio)[source]

Convert the input object to a QtGui.QIcon.

Parameters:

  • obj –

    The object to be converted to a QtGui.QIcon. The data type of obj can be one of:

    • QtGui.QIcon

    • QtGui.QPixmap

    • QtGui.QImage

    • QtWidgets.QStyle.StandardPixmap: One of the built-in Qt pixmaps. Example:

      to_qicon(QtWidgets.QStyle.SP_TitleBarMenuButton)
to_qicon(14)  # the QtWidgets.QStyle.SP_TrashIcon enum value

    • QtCore.QByteArray: A Base64 representation of an encoded icon.

      See icon_to_base64().

    • str: The path to an icon file or an icon embedded in a DLL or EXE file.

      If obj is a path to an icon file and only the filename is specified then the directories in sys.path and os.environ['PATH'] are also used to search for the icon file. If obj refers to an icon in a Windows DLL/EXE file then obj is the path to the DLL/EXE file and the icon index separated by the | character.

      The following examples illustrate the various ways to request an icon by passing in a str argument:

      # provide the full path to the icon file
to_qicon('D:/code/resources/icons/msl.png')
to_qicon('D:/code/resources/icons/photon.png')

# insert the folder where the icons are located in to sys.path
sys.path.insert(0, 'D:/code/resources/icons/')
# so now only the filename needs to be specified to load the icon
to_qicon('msl.png')
to_qicon('photon.png')

# load icon 23 from the Windows shell32.dll file
to_qicon('C:/Windows/System32/shell32.dll|23')

# load icon 0 from the Windows explorer.exe file
to_qicon('C:/Windows/explorer.exe|0')

# it is assumed that the DLL/EXE file is located in a default directory:
#   - a DLL file in C:/Windows/System32/
#   - an EXE file in C:/Windows/
# so the following is a simplified way to load an icon in a DLL file
to_qicon('shell32|23')
to_qicon('imageres|1')
to_qicon('compstui|51')
# and the following is a simplified way to load an icon in an EXE file
to_qicon('explorer|0')

  • size (int, float, tuple of int or QtCore.QSize, optional) – Rescale the icon to the specified size. If the value is None then do not rescale the icon. If an int then set the width and the height to be the size value. If a float then a scaling factor. If a tuple then the (width, height) values.

  • aspect_mode (QtCore.Qt.AspectRatioMode, optional) – How to maintain the aspect ratio if rescaling. The default mode is to keep the aspect ratio.

Returns:

QtGui.QIcon – The input object converted to a QtGui.QIcon.

Raises:

  • OSError – If the icon cannot be found.

  • TypeError – If the data type of obj or size is not supported.

Example

To view the standard icons that come with Qt and that come with Windows run:

>>> from msl.examples.qt import ShowStandardIcons  
>>> ShowStandardIcons()