Skip to content

Font icons#

The superqt.fonticon module provides a set of utilities for working with font icons such as Font Awesome or Material Design Icons.

Basic Example#

from fonticon_fa5 import FA5S

from qtpy.QtCore import QSize
from qtpy.QtWidgets import QApplication, QPushButton

from superqt.fonticon import icon, pulse

app = QApplication([])

btn2 = QPushButton()
btn2.setIcon(icon(FA5S.smile, color="blue"))
btn2.setIconSize(QSize(225, 225))
btn2.show()

app.exec()

Font icons

Font Icon plugins#

Ready-made fonticon packs are available as plugins.

A great way to search across most available icons libraries from a single search interface is to use glyphsearch: https://glyphsearch.com/

If a font library you'd like to use is unavailable as a superqt plugin, please open a feature request

Font Awesome 6#

Browse available icons at https://fontawesome.com/v6/search

pip install fonticon-fontawesome6

Font Awesome 5#

Browse available icons at https://fontawesome.com/v5/search

pip install fonticon-fontawesome5

Material Design Icons 7#

Browse available icons at https://materialdesignicons.com/

pip install fonticon-materialdesignicons7

Material Design Icons 6#

Browse available icons at https://materialdesignicons.com/ (note that the search defaults to v7, see changes from v6 in the changelog)

pip install fonticon-materialdesignicons6

See also#

superqt.fonticon is a pluggable system, and font icon packs may use the "superqt.fonticon" entry point to register themselves with superqt. See fonticon-cookiecutter for a template, or look through the following repos for examples:

API#

superqt.fonticon.icon(glyph_key, scale_factor=DEFAULT_SCALING_FACTOR, color=None, opacity=1, animation=None, transform=None, states=None) #

Create a QIcon for glyph_key, with a number of optional settings.

The glyph_key (e.g. 'fa5s.smile') represents a Font-family & style, and a glyph. In most cases, the key should be provided by a plugin in the environment, like:

...but fonts can also be added manually using addFont.

Parameters:

Name Type Description Default
glyph_key str

String encapsulating a font-family, style, and glyph. e.g. 'fa5s.smile'.

 required
scale_factor float

Scale factor (fraction of widget height), When widget icon is painted on widget, it will use font.setPixelSize(round(wdg.height() * scale_factor)). by default 0.875.

 DEFAULT_SCALING_FACTOR
color ValidColor

Color for the font, by default None. (e.g. The default QColor) Valid color types include QColor, int, str, Qt.GlobalColor, tuple (of integer: RGB[A]) (anything that can be passed to QColor).

 None
opacity float

Opacity of icon, by default 1

 1
animation Animation

Animation for the icon. A subclass of superqt.fonticon.Animation, that provides a concrete animate method. (see "spin" and "pulse" for examples). by default None.

 None
transform QTransform

A QTransform to apply when painting the icon, by default None

 None
states dict

Provide additional styling for the icon in different states. states must be a mapping of string to dict, where:

  • the key represents a QIcon.State ("on", "off"), a QIcon.Mode ("normal", "active", "selected", "disabled"), or any combination of a state & mode separated by an underscore (e.g. "off_active", "selected_on", etc...).
  • the value is a dict with all of the same key/value meanings listed above as parameters to this function (e.g. glyph_key, color,scale_factor, animation, etc...)

Missing keys in the state dicts will be taken from the default options, provided by the parameters above.

 None

Returns:

Type Description
QFontIcon

A subclass of QIcon. Can be used wherever QIcons are used, such as widget.setIcon()

Examples:

simple example (using the string 'fa5s.smile' assumes the fonticon-fontawesome5 plugin is installed)

>>> btn = QPushButton()
>>> btn.setIcon(icon('fa5s.smile'))

can also directly import from fonticon_fa5

>>> from fonticon_fa5 import FA5S
>>> btn.setIcon(icon(FA5S.smile))

with animation

>>> btn2 = QPushButton()
>>> btn2.setIcon(icon(FA5S.spinner, animation=pulse(btn2)))

complicated example

>>> btn = QPushButton()
>>> btn.setIcon(
...     icon(
...         FA5S.ambulance,
...         color="blue",
...         states={
...             "active": {
...                 "glyph": FA5S.bath,
...                 "color": "red",
...                 "scale_factor": 0.5,
...                 "animation": pulse(btn),
...             },
...             "disabled": {
...                 "color": "green",
...                 "scale_factor": 0.8,
...                 "animation": spin(btn)
...             },
...         },
...     )
... )
>>> btn.setIconSize(QSize(256, 256))
>>> btn.show()

options: heading_level: 3

superqt.fonticon.setTextIcon(widget, glyph_key, size=None) #

Set text on a widget to a specific font & glyph.

This is an alternative to setting a QIcon with a pixmap. It may be easier to combine with dynamic stylesheets.

Parameters:

Name Type Description Default
widget QWidget

A widget supporting a setText method.

 required
glyph_key str

String encapsulating a font-family, style, and glyph. e.g. 'fa5s.smile'.

 required
size int

Size for QFont. passed to setPixelSize, by default None

 None

options: heading_level: 3

superqt.fonticon.font(font_prefix, size=None) #

Create QFont for font_prefix.

Parameters:

Name Type Description Default
font_prefix str

Font_prefix, such as 'fa5s' or 'mdi6', representing a font-family and style.

 required
size int

Size for QFont. passed to setPixelSize, by default None

 None

Returns:

Type Description
QFont

QFont instance that can be used to add fonticons to widgets.

options: heading_level: 3

superqt.fonticon.IconOpts dataclass #

Options for rendering an icon.

Parameters:

Name Type Description Default
glyph_key str

The key of the glyph to use, e.g. 'fa5s.smile', by default None

 _Unset
scale_factor float

The scale factor to use, by default None

 _Unset
color ValidColor

The color to use, by default None. Colors may be specified as a string, QColor, Qt.GlobalColor, or a 3 or 4-tuple of integers.

 _Unset
opacity float

The opacity to use, by default None

 _Unset
animation Animation

The animation to use, by default None

 _Unset

options: heading_level: 3

superqt.fonticon.addFont(filepath, prefix, charmap=None) #

Add OTF/TTF file at filepath to the registry under prefix.

If you'd like to later use a fontkey in the form of prefix.some-name, then charmap must be provided and provide a mapping for all of the glyph names to their unicode numbers. If a charmap is not provided, glyphs must be directly accessed with their unicode as something like key.￿.

Note

in most cases, users will not need this. Instead, they should install a font plugin, like:

Parameters:

Name Type Description Default
filepath str

Path to an OTF or TTF file containing the fonts

 required
prefix str

A prefix that will represent this font file when used for lookup. For example, 'fa5s' for 'Font-Awesome 5 Solid'.

 required
charmap Dict[str, str]

optional mapping for all of the glyph names to their unicode numbers. See note above.

 None

Returns:

Type Description
(Tuple[str, str], optional)

font-family and font-style for the file just registered, or None if something goes wrong.

options: heading_level: 3

Animations#

the animation parameter to icon() accepts a subclass of Animation that will be

superqt.fonticon.Animation #

Bases: ABC

Base icon animation class.

animate(painter) abstractmethod #

Setup and start the timer for the animation.

options: heading_level: 3

superqt.fonticon.pulse #

Bases: spin

Animation that spins an icon in slower, discrete steps.

options: heading_level: 3

superqt.fonticon.spin #

Bases: Animation

Animation that smoothly spins an icon.

options: heading_level: 3