Theme Manager

The ThemeManager is a QObject that allows for Trace to achieve a uniform look/feel throughout the application. It determines if the app should display a light or a dark theme and manages color palettes for each.

Theme

Bases: Enum

Theme enumeration for light and dark modes.

IconColors

Constants for icon color types.

ThemeManager(app, parent=None)

Bases: QObject

Theme manager for Qt applications with icon support. It manages both Qt palette themes and icon colors, providing a unified interface for light/dark mode switching with persistent settings.

Attributes:

Name	Type	Description
theme_changed	Signal	Signal emitted when theme changes, passes Theme enum value.
current_theme	Theme	Currently active theme.
app	QApplication	Qt application instance.
light_palette	QPalette	Palette configuration for light theme.
dark_palette	QPalette	Palette configuration for dark theme.
light_icon_colors	IconColorDict	Icon color mapping for light theme.
dark_icon_colors	IconColorDict	Icon color mapping for dark theme.

Parameters:

Name	Type	Description	Default
app	QApplication	The Qt application instance to manage themes for.	required
parent	QObject | None	Parent QObject for memory management, by default None.	None

Examples:

>>> app = QApplication(sys.argv)
>>> theme_manager = IntegratedThemeManager(app)
>>> theme_manager.set_theme(Theme.DARK)

Source code in trace/services/theme_manager.py

def __init__(
    self,
    app: QApplication,
    parent: QObject | None = None,
) -> None:
    """
    Initialize the integrated theme manager.

    Parameters
    ----------
    app : QApplication
        The Qt application instance to manage themes for.
    parent : QObject | None, optional
        Parent QObject for memory management, by default None.

    Examples
    --------
    >>> app = QApplication(sys.argv)
    >>> theme_manager = IntegratedThemeManager(app)
    >>> theme_manager.set_theme(Theme.DARK)
    """
    super().__init__(parent)
    self.app = app
    self.current_theme = Theme.LIGHT
    self.app.setStyle(QStyleFactory.create("Fusion"))

    self._setup_palettes()
    self._setup_icon_colors()

    # Load saved theme preference
    settings = QSettings()
    is_dark = settings.value("isDarkTheme", False, bool)
    self.set_theme(Theme.DARK if is_dark else Theme.LIGHT)

set_theme(theme)

Set the application theme.

Parameters:

Name	Type	Description	Default
theme	Theme	The theme to apply (Theme.LIGHT or Theme.DARK).	required

Examples:

>>> theme_manager.set_theme(Theme.DARK)
>>> theme_manager.set_theme(Theme.LIGHT)

Source code in trace/services/theme_manager.py

def set_theme(self, theme: Theme) -> None:
    """
    Set the application theme.

    Parameters
    ----------
    theme : Theme
        The theme to apply (Theme.LIGHT or Theme.DARK).

    Examples
    --------
    >>> theme_manager.set_theme(Theme.DARK)
    >>> theme_manager.set_theme(Theme.LIGHT)
    """
    self.current_theme = theme

    if theme == Theme.DARK:
        self.app.setPalette(self.dark_palette)
        stylesheet = dark_stylesheet.read_text()
    else:
        self.app.setPalette(self.light_palette)
        stylesheet = light_stylesheet.read_text()

    stylesheet = stylesheet.replace('url("assets/', f'url("{ASSETS_DIR}/')
    self.app.main_window.setStyleSheet(stylesheet)

    settings = QSettings()
    settings.setValue("isDarkTheme", theme == Theme.DARK)

    self.theme_changed.emit(theme)

toggle_theme()

Toggle between light and dark themes.

Switches from light to dark or dark to light, whichever is opposite to the current theme.

Examples:

>>> theme_manager.toggle_theme()  # Switches to opposite theme

Source code in trace/services/theme_manager.py

def toggle_theme(self) -> None:
    """
    Toggle between light and dark themes.

    Switches from light to dark or dark to light, whichever is opposite
    to the current theme.

    Examples
    --------
    >>> theme_manager.toggle_theme()  # Switches to opposite theme
    """
    new_theme = Theme.DARK if self.current_theme == Theme.LIGHT else Theme.LIGHT
    self.set_theme(new_theme)

get_current_theme()

Get the current theme.

Returns:

Type	Description
Theme	The currently active theme.

Source code in trace/services/theme_manager.py

def get_current_theme(self) -> Theme:
    """
    Get the current theme.

    Returns
    -------
    Theme
        The currently active theme.
    """
    return self.current_theme

get_icon_color(color_type=IconColors.PRIMARY)

Get icon color for the current theme.

Parameters:

Name	Type	Description	Default
color_type	str	The type of icon color to retrieve, by default IconColors.PRIMARY. Must be one of the IconColors constants.	PRIMARY

Returns:

Type	Description
ColorHex	Hex color string (e.g., '#ffffff') appropriate for the current theme.

Examples:

>>> color = theme_manager.get_icon_color(IconColors.PRIMARY)
>>> warning_color = theme_manager.get_icon_color(IconColors.WARNING)

Source code in trace/services/theme_manager.py

def get_icon_color(self, color_type: str = IconColors.PRIMARY) -> ColorHex:
    """
    Get icon color for the current theme.

    Parameters
    ----------
    color_type : str, optional
        The type of icon color to retrieve, by default IconColors.PRIMARY.
        Must be one of the IconColors constants.

    Returns
    -------
    ColorHex
        Hex color string (e.g., '#ffffff') appropriate for the current theme.

    Examples
    --------
    >>> color = theme_manager.get_icon_color(IconColors.PRIMARY)
    >>> warning_color = theme_manager.get_icon_color(IconColors.WARNING)
    """
    colors = self.dark_icon_colors if self.current_theme == Theme.DARK else self.light_icon_colors
    return colors.get(color_type, colors[IconColors.PRIMARY])

create_icon(icon_name, color_type=IconColors.PRIMARY, scale_factor=1.0, custom_color=None)

Create a themed icon using qtawesome.

Parameters:

Name	Type	Description	Default
icon_name	str	The qtawesome icon name (e.g., 'fa.home', 'mdi.gear').	required
color_type	str	The type of icon color to use, by default IconColors.PRIMARY.	PRIMARY
scale_factor	float	Scale factor for icon size, by default 1.0.	1.0
custom_color	ColorHex | None	Custom hex color to override theme color, by default None.	None

Returns:

Type	Description
QIcon | None	The created icon, or None if qtawesome is not available.

Examples:

>>> icon = theme_manager.create_icon('fa.home')
>>> warning_icon = theme_manager.create_icon('fa.exclamation-triangle', IconColors.WARNING)
>>> custom_icon = theme_manager.create_icon('fa.gear', custom_color='#ff0000')

Source code in trace/services/theme_manager.py

def create_icon(
    self,
    icon_name: str,
    color_type: str = IconColors.PRIMARY,
    scale_factor: float = 1.0,
    custom_color: ColorHex | None = None,
) -> QIcon | None:
    """
    Create a themed icon using qtawesome.

    Parameters
    ----------
    icon_name : str
        The qtawesome icon name (e.g., 'fa.home', 'mdi.gear').
    color_type : str, optional
        The type of icon color to use, by default IconColors.PRIMARY.
    scale_factor : float, optional
        Scale factor for icon size, by default 1.0.
    custom_color : ColorHex | None, optional
        Custom hex color to override theme color, by default None.

    Returns
    -------
    QIcon | None
        The created icon, or None if qtawesome is not available.

    Examples
    --------
    >>> icon = theme_manager.create_icon('fa.home')
    >>> warning_icon = theme_manager.create_icon('fa.exclamation-triangle', IconColors.WARNING)
    >>> custom_icon = theme_manager.create_icon('fa.gear', custom_color='#ff0000')
    """
    color = custom_color or self.get_icon_color(color_type)
    return qta.icon(icon_name, color=color, scale_factor=scale_factor)

get_all_icon_colors()

Get all available icon colors for the current theme.

Returns:

Type	Description
IconColorDict	Dictionary mapping color type names to hex color strings.

Examples:

>>> colors = theme_manager.get_all_icon_colors()
>>> primary_color = colors[IconColors.PRIMARY]

Source code in trace/services/theme_manager.py

def get_all_icon_colors(self) -> IconColorDict:
    """
    Get all available icon colors for the current theme.

    Returns
    -------
    IconColorDict
        Dictionary mapping color type names to hex color strings.

    Examples
    --------
    >>> colors = theme_manager.get_all_icon_colors()
    >>> primary_color = colors[IconColors.PRIMARY]
    """
    return self.dark_icon_colors.copy() if self.current_theme == Theme.DARK else self.light_icon_colors.copy()