fxicons

Icon management functionality for fxgui.

This module provides utilities for loading, caching, and manipulating icons from multiple icon libraries including Material Icons, Font Awesome, Simple Icons, and custom DCC (Digital Content Creation) icons.

The module supports

• Multiple icon libraries with configurable defaults
• Icon color customization
• Automatic caching using LRU cache for performance
• Icon superposition for composite icons
• Pixmap and QIcon conversion utilities

Functions:

Name	Description
get_icon	Get a QIcon from an icon library.
get_pixmap	Get a QPixmap from an icon library.
get_icon_path	Get the file path of an icon.
clear_icon_cache	Clear the icon LRU cache.
set_default_icon_library	Set the default icon library.
set_icon_defaults	Configure default icon parameters.
add_library	Add a custom icon library.

Examples:

Basic icon usage:

>>> from fxgui.fxicons import get_icon
>>> icon = get_icon("home")
>>> colored_icon = get_icon("settings", color="#FF5722")

Using different libraries:

>>> fa_icon = get_icon("lemon", library="fontawesome")
>>> dcc_icon = get_icon("houdini", library="dcc")

add_library

add_library(
    library: str, pattern: str, defaults: Dict, root: Optional[Path] = None
)

Add a new icon library to the available libraries.

Parameters:

Name	Type	Description	Default
library	str	The name of the library.	required
pattern	str	The pattern to use for the library. Valid placeholders are: - {root}: The root path for the library. - {library}: The name of the library. - {style}: The style of the icon. - {icon_name}: The name of the icon. - {extension}: The extension of the icon.	required
defaults	Dict	The default values for the library.	required
root	Optional[Path]	The root path for the library. Defaults to fxconstants.ICONS_ROOT.	None

Examples:

>>> add_library(
...    library="houdini",
...    pattern="{root}/{library}/{style}/{icon_name}.{extension}",
...    defaults={
...        "extension": "svg",
...        "style": "CROWDS",
...        "color": None,
...        "width": 48,
...        "height": 48,
...    },
...    root=str(Path.home() / "Pictures" / "Icons"),
... )

change_pixmap_color

change_pixmap_color(pixmap: QPixmap, color: str) -> QPixmap

Change the color of a pixmap.

Uses QPainter with composition mode for efficient colorization while preserving the original alpha channel.

Parameters:

Name	Type	Description	Default
pixmap	QPixmap	The pixmap to change the color of.	required
color	str	The color to apply.	required

Returns:

Name	Type	Description
QPixmap	QPixmap	The pixmap with the new color applied.

clear_icon_cache

clear_icon_cache() -> None

Clear the icon and pixmap LRU caches.

This should be called when changing themes to ensure icons are regenerated with the new color scheme.

Examples:

>>> clear_icon_cache()

convert_icon_to_pixmap

convert_icon_to_pixmap(
    icon: QIcon, desired_size: Optional[QSize] = None
) -> Optional[QPixmap]

Converts a QIcon to a QPixmap.

Parameters:

Name	Type	Description	Default
icon	QIcon	The QIcon to convert.	required
desired_size	Optional[QSize]	The desired size for the pixmap (QSize). If None, the default size is 48x48.	None

Returns:

Type	Description
Optional[QPixmap]	A QPixmap or None if no suitable pixmap is available.

Examples:

Let the size be decided

>>> icon = hou.qt.Icon("MISC_python")
>>> pixmap = convert_icon_to_pixmap(icon)

Choose a size

>>> icon = hou.qt.Icon("MISC_python")
>>> pixmap = convert_icon_to_pixmap(icon, QSize(48, 48))

get_available_icons_in_library

get_available_icons_in_library(library: str) -> List[str]

Get all available icon names in the specified library.

Parameters:

Name	Type	Description	Default
library	str	The name of the library.	required

Returns:

Type	Description
List[str]	List[str]: The available icon names in the library.

Raises:

Type	Description
ValueError	If the library does not exist.
FileNotFoundError	If no icons are found in the library.

Examples:

>>> print(get_available_icons_in_library("dcc"))
["3d_equalizer", "adobe_photoshop", "blender", "hiero"]

get_available_libraries

get_available_libraries() -> List[str]

Get all available icon libraries.

Returns:

Type	Description
List[str]	List[str]: The available icon libraries.

Examples:

>>> print(get_available_libraries())
["beacon", "dcc", "material", "fontawesome"]

get_icon

get_icon(
    icon_name: str,
    width: Optional[int] = None,
    height: Optional[int] = None,
    color: Optional[str] = None,
    library: Optional[str] = None,
    style: Optional[str] = None,
    extension: Optional[str] = None,
) -> QIcon

Get a QIcon of the specified icon.

Parameters:

Name	Type	Description	Default
icon_name	str	The name of the icon.	required
width	Optional[int]	The width of the pixmap. Defaults to None.	None
height	Optional[int]	The height of the pixmap. Defaults to None.	None
color	Optional[str]	The color to convert the pixmap to. Defaults to None.	None
library	Optional[str]	The library of the icon. Defaults to None.	None
style	Optional[str]	The style of the icon. Defaults to None.	None
extension	Optional[str]	The extension of the icon. Defaults to None.	None

Returns:

Name	Type	Description
QIcon	QIcon	The QIcon of the icon.

Examples:

>>> get_icon("add", color="red")
>>> get_icon("lemon", library="fontawesome")

get_icon_color

get_icon_color() -> str

Get the current default icon color.

Returns the icon color from the current theme. This is the canonical source for icon color and is synchronized with the theme.

Returns:

Type	Description
str	The current default icon color as a hex string.

Examples:

>>> color = get_icon_color()
>>> print(color)  # "#b4b4b4" for dark theme

get_icon_path

get_icon_path(
    icon_name: str,
    library: Optional[str] = None,
    style: Optional[str] = None,
    extension: Optional[str] = None,
) -> str

Get the path of the specified icon.

Parameters:

Name	Type	Description	Default
icon_name	str	The name of the icon.	required
library	Optional[str]	The library of the icon. Defaults to None.	None
style	Optional[str]	The style of the icon. Defaults to None.	None
extension	Optional[str]	The extension of the icon. Defaults to None.	None

Raises:

Type	Description
FileNotFoundError	If verify is True and the icon does not exist.

Returns:

Name	Type	Description
str	str	The path of the icon.

Examples:

>>> get_icon_path("add")
>>> get_icon_path("lemon", library="fontawesome")

get_pixmap

get_pixmap(
    icon_name: str,
    width: Optional[int] = None,
    height: Optional[int] = None,
    color: Optional[str] = None,
    library: Optional[str] = None,
    style: Optional[str] = None,
    extension: Optional[str] = None,
) -> QPixmap

Get a QPixmap of the specified icon.

Parameters:

Name	Type	Description	Default
icon_name	str	The name of the icon.	required
width	Optional[int]	The width of the pixmap. Defaults to None.	None
height	Optional[int]	The height of the pixmap. Defaults to None.	None
color	Optional[str]	The color to convert the pixmap to. Defaults to None.	None
library	Optional[str]	The library of the icon. Defaults to None.	None
style	Optional[str]	The style of the icon. Defaults to None.	None
extension	Optional[str]	The extension of the icon. Defaults to None.	None

Returns:

Name	Type	Description
QPixmap	QPixmap	The QPixmap of the icon.

Examples:

>>> get_pixmap("add", color="red")
>>> get_pixmap("lemon", library="fontawesome")

has_transparency

has_transparency(mask: QBitmap) -> bool

Check if a mask has any transparency.

Parameters:

Name	Type	Description	Default
mask	QBitmap	The mask to check.	required

Returns:

Name	Type	Description
bool	bool	True if the mask has transparency, False otherwise.

refresh_all_icons

refresh_all_icons() -> None

Refresh icons on all registered widgets.

This is automatically called by sync_colors_with_theme(), but can be called manually if needed.

set_default_icon_library

set_default_icon_library(library: str)

Set the default icon library.

Parameters:

Name	Type	Description	Default
library	str	The name of the library to set as default.	required

Raises:

Type	Description
ValueError	If the library does not exist.

Examples:

>>> set_default_icon_library("fontawesome")

set_icon

set_icon(widget, icon_name: str, **kwargs) -> QIcon

Set an icon on a widget and register it for automatic theme updates.

This is the recommended way to set icons on widgets. The icon will automatically refresh when the theme changes.

Parameters:

Name	Type	Description	Default
widget		The widget to set the icon on (QAction, QPushButton, etc.).	required
icon_name	str	The name of the icon.	required
**kwargs		Optional parameters passed to get_icon (width, height, color, library, style, extension).	{}

Returns:

Type	Description
QIcon	The QIcon that was set on the widget.

Examples:

>>> from fxgui import fxicons
>>> fxicons.set_icon(my_button, "save")
>>> fxicons.set_icon(my_action, "home", library="material")

set_icon_defaults

set_icon_defaults(apply_to: Optional[str] = None, **kwargs: Any) -> None

Set the default values for the icons.

Parameters:

Name	Type	Description	Default
apply_to	Optional[str]	The library to apply the defaults to. If set to None, the defaults will be applied to all libraries. Defaults to None.	None
**kwargs	Any	The default values to set.	{}

Examples:

>>> set_icon_defaults(color="red", width=32, height=32)
>>> set_icon_defaults(apply_to="material", color="blue")

superpose_icons

superpose_icons(*icons: QIcon) -> QIcon

Superpose multiple icons.

Parameters:

Name	Type	Description	Default
*icons	QIcon	Icons to superpose. Add the icons in the order you want them to be superposed, from background to foreground.	()

Returns:

Name	Type	Description
QIcon	QIcon	The QIcon of the superposed icons.

Notes

The size of the resulting icon is the size of the first icon.

Examples:

>>> icon_a = get_icon("add")
>>> icon_b = get_icon("lemon", library="fontawesome")
>>> superposed_icon = superpose_icons(icon_a, icon_b)

sync_colors_with_theme

sync_colors_with_theme() -> None

Synchronize icon colors with the current theme from fxstyle.

This function reads the icon color from the current theme's JSONC configuration and updates all icon library defaults accordingly. It also clears the icon cache and refreshes all registered widget icons.

This is automatically called by fxstyle.apply_theme(), but can also be called manually when needed.

Examples:

>>> from fxgui import fxicons
>>> fxicons.sync_colors_with_theme()