Font icons¶
superqt.fonticon creates QIcons from the characters (glyphs) of icon fonts,
such as Font Awesome or
Material Design Icons. Icon fonts are
installed as plugins: superqt doesn't come with any.
Compared with QIconifyIcon, font icons don't need network
access, can be animated, and can be the text of a label or button (see the
comparison).
Installing a font¶
These icon fonts are available as plugins, and as extras of superqt:
| Font | Install | Browse the icons |
|---|---|---|
| Font Awesome 6 | pip install "superqt[font-fa6]" |
https://fontawesome.com/v6/search |
| Font Awesome 5 | pip install "superqt[font-fa5]" |
https://fontawesome.com/v5/search |
| Material Design Icons 7 | pip install "superqt[font-mi7]" |
https://pictogrammers.com/library/mdi/ |
| Material Design Icons 6 | pip install "superqt[font-mi6]" |
https://pictogrammers.com/library/mdi/ (shows version 7: see the changes from version 6) |
Other fonts are available as separate packages:
GlyphSearch searches several icon libraries at once. If you'd like to use a font that isn't available as a plugin, please open a feature request.
Basic example¶
from fonticon_fa5 import FA5S
from qtpy.QtCore import QSize
from qtpy.QtWidgets import QApplication, QPushButton
from superqt.fonticon import icon
app = QApplication([])
button = QPushButton()
button.setIcon(icon(FA5S.smile, color="royalblue"))
button.setIconSize(QSize(96, 96))
button.show()
app.exec()
Glyphs are named by keys in the form "prefix.name", such as "fa5s.smile",
or by the constants of the classes that the plugins provide, such as
FA5S.smile, which IDEs autocomplete (and check for typos).
Colors and states¶
icon takes the color, scale, opacity, and transform of the glyph. Without a
color, glyphs are black, whatever the widget's palette: for a dark theme, pass a
color (for example, one from the palette).
states gives other options (including another glyph) for other states and
modes of the icon. Its keys are a state ("on", "off"), a mode ("normal",
"active", "selected", "disabled"), or both (as in "on_disabled"). For
example, a red heart when a checkable button is checked:
button.setCheckable(True)
button.setIcon(
icon(
FA5S.smile,
color="gray",
states={"on": {"glyph_key": FA5S.heart, "color": "red"}},
)
)
In modes other than normal (such as disabled), a glyph without a color for that mode is adjusted by the style, like any other icon (for example, grayed out when disabled).
Animations¶
The animation argument of icon() takes an
Animation, such as spin or pulse, created
with the widget that shows the icon:
from fonticon_fa5 import FA5S
from qtpy.QtGui import QPalette
from qtpy.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget
from superqt.fonticon import icon, pulse, spin
app = QApplication([])
window = QWidget()
layout = QHBoxLayout(window)
color = window.palette().color(QPalette.ColorRole.ButtonText).name() # (dark themes)
spinning = QPushButton("spin")
spinning.setIcon(icon(FA5S.sync, color=color, animation=spin(spinning)))
layout.addWidget(spinning)
pulsing = QPushButton("pulse")
pulsing.setIcon(icon(FA5S.spinner, color=color, animation=pulse(pulsing)))
layout.addWidget(pulsing)
window.show()
app.exec()
Glyphs as text¶
setTextIcon makes a glyph the text of a widget, such as a label or a button,
by setting its text to the glyph and its font to the icon font. The glyph is then
drawn as text, in the widget's text color, so it follows the palette and style
sheets:
font returns the QFont of an icon font (by its prefix, such as "fa5s"), for
drawing glyphs yourself.
Writing a plugin¶
Font packages register themselves with the "superqt.fonticon"
entry point
(superqt.fonticon.ENTRY_POINT), and define their glyphs with an
IconFont subclass (whose metaclass,
IconFontMeta, turns its attributes into glyph keys).
fonticon-cookiecutter is
a template for a new one, and the packages above are examples, such as
fonticon-fontawesome6.
To use a font file without writing a package, see
addFont.
API¶
Icons¶
icon
¶
icon(
glyph_key: str,
scale_factor: float = DEFAULT_SCALING_FACTOR,
color: ValidColor | None = None,
opacity: float = 1,
animation: Animation | None = None,
transform: QTransform | None = None,
states: dict[str, IconOptionDict | IconOpts]
| None = None,
) -> QFontIcon
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:
- fonticon-fontawesome5 ('fa5s' & 'fa5r' prefixes)
- fonticon-materialdesignicons6 ('mdi6' prefix)
...but fonts can also be added manually using addFont.
Parameters:
-
glyph_key(str) –String encapsulating a font-family, style, and glyph. e.g. 'fa5s.smile'.
-
scale_factor(float, default:DEFAULT_SCALING_FACTOR) –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. -
color(ValidColor, default:None) –Color for the font, by default None. (e.g. The default
QColor) Valid color types includeQColor,int,str,Qt.GlobalColor,tuple(of integer: RGB[A]) (anything that can be passed toQColor). -
opacity(float, default:1) –Opacity of icon, by default 1
-
animation(Animation, default:None) –Animation for the icon. A subclass of superqt.fonticon.Animation, that provides a concrete
animatemethod. (see "spin" and "pulse" for examples). by default None. -
transform(QTransform, default:None) –A
QTransformto apply when painting the icon, by default None -
states(dict, default:None) –Provide additional styling for the icon in different states.
statesmust be a mapping of string to dict, where:- the key represents a
QIcon.State("on", "off"), aQIcon.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.
- the key represents a
Returns:
-
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)
can also directly import from fonticon_fa5
with animation
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()
IconOpts
¶
IconOpts(
glyph_key: str | Unset = _Unset,
scale_factor: float | Unset = _Unset,
color: ValidColor | Unset = _Unset,
opacity: float | Unset = _Unset,
animation: Animation | Unset | None = _Unset,
transform: QTransform | Unset | None = _Unset,
)
Options for rendering an icon.
Parameters:
-
glyph_key(str, default:_Unset) –The key of the glyph to use, e.g.
'fa5s.smile', by defaultNone -
scale_factor(float, default:_Unset) –The scale factor to use, by default
None -
color(ValidColor, default:_Unset) –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. -
opacity(float, default:_Unset) –The opacity to use, by default
None -
animation(Animation, default:_Unset) –The animation to use, by default
None
Text¶
setTextIcon
¶
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:
font
¶
Create QFont for font_prefix.
Parameters:
-
font_prefix(str) –Font_prefix, such as 'fa5s' or 'mdi6', representing a font-family and style.
-
size(int, default:None) –Size for QFont. passed to
setPixelSize, by default None
Returns:
-
QFont–QFont instance that can be used to add fonticons to widgets.
Fonts¶
addFont
¶
addFont(
filepath: str,
prefix: str,
charmap: dict[str, str] | None = None,
) -> tuple[str, str] | 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:
-
filepath(str) –Path to an OTF or TTF file containing the fonts
-
prefix(str) –A prefix that will represent this font file when used for lookup. For example, 'fa5s' for 'Font-Awesome 5 Solid'.
-
charmap(Dict[str, str], default:None) –optional mapping for all of the glyph names to their unicode numbers. See note above.
Returns:
IconFont
¶
Helper class that provides a standard way to create an IconFont.
Examples:
class FA5S(IconFont):
__font_file__ = '...'
some_char = 0xfa42
IconFontMeta
¶
IconFont metaclass.
This updates the value of all class attributes to be prefaced with the class name (lowercase), and makes sure that all values are valid characters.
Examples:
This metaclass turns the following class:
class FA5S(metaclass=IconFontMeta):
__font_file__ = 'path/to/font.otf'
some_char = 0xfa42
into this:
class FA5S:
__font_file__ = path/to/font.otf'
some_char = 'fa5s.既'
In usage, this means that someone could use icon(FA5S.some_char) (provided
that the FA5S class/namespace has already been registered). This makes
IDE attribute checking and autocompletion easier.
Animations¶
Animation
¶
Base icon animation class.
spin
¶
Animation that smoothly spins an icon.
pulse
¶
Animation that spins an icon in slower, discrete steps.