fxstyle

fxstyle ¶

Styling, theming, and color management for fxgui.

This module provides comprehensive styling functionality including

Multiple theme support with dynamic theme switching
Theme persistence across application restarts (via fxconfig)
QSS stylesheet loading with dynamic color replacement
Custom QProxyStyle for standard icon overrides
Theme toggling with icon cache invalidation
Color loading from YAML configuration files with inheritance support

Theme Color Reference¶

Each theme in style.yaml defines these semantic color roles:

Accent Colors (interactive highlights): - accent_primary: Hover borders, selections, progress gradients (end) - accent_secondary: Gradient starts, item hover backgrounds

Surface Colors (backgrounds): - surface: Main widget/window backgrounds, buttons, selected tabs - surface_alt: Alternate row backgrounds in lists/tables - surface_sunken: Recessed areas - inputs, lists, menus, status bar - tooltip: Tooltip backgrounds

Border Colors: - border: Standard borders on inputs, containers, menus - border_light: Subtle borders - tooltips, buttons, tabs - border_strong: Emphasized borders - frames, separators

Text Colors: - text: Primary text for all widgets - text_muted: De-emphasized text - inactive tabs, placeholders - text_disabled: Disabled widget text - text_on_accent_primary: Text on accent_primary backgrounds (optional, auto-computed) - text_on_accent_secondary: Text on accent_secondary backgrounds (optional, auto-computed)

Interactive States: - state_hover: Hover state backgrounds - state_pressed: Pressed/checked/active backgrounds

Scrollbar: - scrollbar_track: Track/gutter background - scrollbar_thumb: Draggable thumb - scrollbar_thumb_hover: Thumb hover state

Layout: - grid: Table gridlines, header borders - separator: Separator/splitter hover backgrounds

Slider: - slider_thumb: Slider handle color - slider_thumb_hover: Slider handle hover/pressed

Icon: - icon: Monochrome icon tint color

Theme Font Reference¶

The color file may also name typefaces by role, in a fonts: mapping that a theme can override role by role:

- ``title``: Reached from QSS through the ``fxTitle`` property; see
  :func:`mark_as_title`
- ``body``: Every widget, through the ``*`` selector
- ``mono``: Code, logs, anything whose columns must line up

Each role is a family stack. A missing section, a missing role or an empty value all mean the platform default UI font, so a color file written before roles existed renders unchanged. Families the running Qt does not have are dropped and the platform default appended, so a role always resolves to something real.

Because :func:set_color_file replaces this file wholesale, a consumer declaring fonts: in its own copy has full typographic control with no further API. Font files those names refer to are registered with :func:register_fonts.

Classes:

Name	Description
`FXProxyStyle`	Custom style providing Material Design icons for Qt standard icons.
`FXThemeManager`	Singleton that emits signals when theme changes.
`FXThemeAware`	Mixin for widgets that auto-update on theme changes.

Functions:

Name	Description
`load_stylesheet`	Load and customize QSS stylesheets.
`get_colors`	Get the cached color configuration.
`set_color_file`	Set a custom color configuration file.
`apply_theme`	Apply a theme to all registered roots (stylesheet + icons).
`get_available_themes`	Get list of available theme names.
`get_theme`	Get the current theme name.
`get_theme_colors`	Get the color palette for the current theme.
`get_accent_colors`	Get primary/secondary accent colors.
`get_icon_color`	Get the icon tint color for current theme.
`register_fonts`	Register font files so a color file may name them.
`get_fonts`	Get the resolved font stack for every role.
`get_font_family`	Get the resolved font stack for one role.
`mark_as_title`	Draw a widget's text in the title font role.
`is_light_theme`	Check if the current theme is light or dark.
`save_theme`	Save the current theme to persistent storage.
`load_saved_theme`	Load the previously saved theme.
`set_default_theme`	Set the theme to fall back to when none is saved.
`get_default_theme`	Get the theme to fall back to when none is saved.

Constants

STYLE_FILE: Path to the default QSS stylesheet. DEFAULT_COLOR_FILE: Path to the default color configuration. TITLE_PROPERTY: Dynamic property name selecting the title font role.

Examples:

Loading a stylesheet with a theme:

>>> from fxgui import fxstyle
>>> stylesheet = fxstyle.load_stylesheet(theme="dracula")
>>> widget.setStyleSheet(stylesheet)

New code should prefer apply_theme / register_themed_root instead.

Applying a theme to a window:

>>> fxstyle.apply_theme("one_dark_pro")

For DCC-embedded windows, call fxstyle.register_themed_root(window) once at construction; FXMainWindow does this automatically.

Getting colors for custom widgets:

>>> colors = fxstyle.get_theme_colors()
>>> surface = colors["surface"]  # Main background
>>> sunken = colors["surface_sunken"]  # Input/list backgrounds
>>> text = colors["text"]  # Primary text color

Theme persistence (automatic): Themes are automatically saved when using apply_theme(). On next application startup, the saved theme is automatically loaded.

Classes¶

FXProxyStyle ¶

FXProxyStyle(*args, **kwargs)

Bases: QProxyStyle


              flowchart TD
              fxgui.fxstyle.FXProxyStyle[FXProxyStyle]

              

              click fxgui.fxstyle.FXProxyStyle href "" "fxgui.fxstyle.FXProxyStyle"

A custom style class that extends QProxyStyle to provide custom icons.

This style provides theme-aware standard icons (file dialogs, message boxes, etc.) using Material Design icons from the fxicons library.

Note

Qt stylesheets bypass QProxyStyle's drawControl() method, which means icon colorization for item views (lists, trees) and menus cannot be handled here when stylesheets are applied. Use FXIconColorDelegate from fxwidgets for icon colorization in item views instead.

Examples:

>>> from fxgui import fxstyle
>>> # Apply to application
>>> fxstyle.set_style(app, "Fusion")

Methods:

Name	Description
`set_icon_color`	Set the color of the icons.
`standardIcon`	Return an icon for the given standardIcon.

Methods:¶

set_icon_color ¶

set_icon_color(color: str)

Set the color of the icons.

Parameters:

Name	Type	Description	Default
`color` ¶	`str`	The color to set the icons to.	required

standardIcon ¶

standardIcon(
    standardIcon: StandardPixmap,
    option: Optional[QStyleOption] = None,
    widget: Optional[QWidget] = None,
) -> QIcon

Return an icon for the given standardIcon.

Parameters:

Name	Type	Description	Default
`standardIcon` ¶	`StandardPixmap`	The standard pixmap for which an icon should be returned.	required
`option` ¶	`Optional[QStyleOption]`	An option that can be used to fine-tune the look of the icon. Defaults to None.	`None`
`widget` ¶	`Optional[QWidget]`	The widget for which the icon is being requested. Defaults to None.	`None`

Returns:

Type	Description
`QIcon`	The icon for the standardIcon. If no custom icon is found,
`QIcon`	the default icon is returned.

FXThemeAware ¶

FXThemeAware(*args, **kwargs)

Mixin that makes widgets automatically respond to theme changes.

This mixin provides automatic theme updates for custom widgets. When the theme changes, connected widgets are notified and can update their appearance.

Usage

Inherit from FXThemeAware FIRST: class MyWidget(FXThemeAware, QWidget)
Override _on_theme_changed() to apply custom colors (optional)
Use self.theme property to access current theme colors
Optionally declare a theme_style class attribute for automatic QSS

Examples:

New API (recommended):

>>> from fxgui import fxstyle
>>> class FXMyWidget(FXThemeAware, QWidget):
...     # Option 1: Declarative QSS with color tokens
...     theme_style = '''
...         FXMyWidget {
...             background: @surface;
...             border: 1px solid @border;
...         }
...     '''
...
...     # Option 2: Programmatic colors in paintEvent
...     def paintEvent(self, event):
...         painter = QPainter(self)
...         painter.fillRect(self.rect(), QColor(self.theme.surface))

Legacy API (deprecated, still works):

>>> class FXMyWidget(FXThemeAware, QWidget):
...     def _apply_theme_styles(self):
...         colors = fxstyle.get_theme_colors()
...         self.setStyleSheet(f"background: {colors['surface']};")

Attributes:

Name	Type	Description
`theme`	`FXThemeColors`	Property returning current theme colors as a FXThemeColors object.
`theme_style`	`str`	Optional class attribute with QSS containing @color tokens.

Attributes¶

theme `property` ¶

theme: FXThemeColors

Get current theme colors as a namespace object.

Returns:

Type	Description
`FXThemeColors`	FXThemeColors object with color attributes (e.g., theme.surface,
`FXThemeColors`	theme.accent_primary, theme.text).

Examples:

>>> def paintEvent(self, event):
...     painter = QPainter(self)
...     painter.fillRect(self.rect(), QColor(self.theme.surface))
...     painter.setPen(QColor(self.theme.text))

Note

The returned object is a shared, cached snapshot of the current theme; treat it as read-only. It is rebuilt whenever the theme changes.

Methods:¶

__apply_theme_style_attribute ¶

__apply_theme_style_attribute() -> None

Process the theme_style class attribute and apply it.

__handle_theme_change ¶

__handle_theme_change(_theme_name: str = None) -> None

Internal handler for theme changes.

FXThemeColors ¶

FXThemeColors(colors_dict: dict)

Namespace for accessing theme colors with dot notation.

This class provides a convenient way to access theme colors using attribute access instead of dictionary lookup.

Examples:

>>> colors = FXThemeColors(fxstyle.get_theme_colors())
>>> colors.surface  # "#302f2f"
>>> colors.accent_primary  # "#2196F3"

Initialize with a colors dictionary.

Parameters:

Name	Type	Description	Default
`colors_dict` ¶	`dict`	Dictionary of color name to hex value mappings.	required

Methods:¶

FXThemeManager ¶

FXThemeManager()

Bases: QObject


              flowchart TD
              fxgui.fxstyle.FXThemeManager[FXThemeManager]

              

              click fxgui.fxstyle.FXThemeManager href "" "fxgui.fxstyle.FXThemeManager"

Singleton that emits theme_changed(str) when the theme changes.

Methods:

Name	Description
`notify_theme_changed`	Called by apply_theme() when theme changes.

Attributes:

Name	Type	Description
`current_theme`	`str`	Return the current theme name.

Attributes¶

current_theme `property` ¶

current_theme: str

Return the current theme name.

Methods:¶

notify_theme_changed ¶

notify_theme_changed(theme_name: str) -> None

Called by apply_theme() when theme changes.

Functions:¶

apply_theme ¶

apply_theme(
    *args, widget: Optional[QWidget] = None, theme: Optional[str] = None
) -> str

Apply a theme everywhere.

Canonical form::

fxstyle.apply_theme("dracula")

Updates the persistent theme state, rebuilds the theme stylesheet, re-applies it to every registered root (see :func:register_themed_root), refreshes icon colors, and emits theme_changed.

.. deprecated:: The old form apply_theme(widget, theme) still works: it registers widget as a themed root and proceeds. Prefer apply_theme(theme).

Parameters:

Name	Type	Description	Default
`theme` ¶	`Optional[str]`	The theme name to apply (e.g., "dark", "light").	`None`
`widget` ¶	`Optional[QWidget]`	Deprecated. A widget to register as a themed root.	`None`

Returns:

Type	Description
`str`	The theme that was applied.

Raises:

Type	Description
`ValueError`	If the theme does not exist.
`TypeError`	If no theme name was provided.

build_stylesheet ¶

build_stylesheet(theme: Optional[str] = None) -> str

Build the complete theme stylesheet.

Concatenates the platform font block, the base style.qss, and all fragments registered via :func:register_widget_style, then resolves every @token in a single pass. Pure: no global state is modified.

Parameters:

Name	Type	Description	Default
`theme` ¶	`Optional[str]`	Theme name. Defaults to the current theme.	`None`

Returns:

Type	Description
`str`	The ready-to-apply stylesheet string.

colors ¶

colors() -> FXThemeColors

Get the current theme colors as a namespace (canonical read API).

Cheap enough for paintEvent hot paths: the namespace is cached per theme and rebuilt only on theme switches. Treat it as read-only.

Returns:

Type	Description
`FXThemeColors`	FXThemeColors with one attribute per color role.

Examples:

>>> def paintEvent(self, event):
...     painter = QPainter(self)
...     painter.fillRect(self.rect(), QColor(fxstyle.colors().surface))

get_accent_colors ¶

get_accent_colors() -> dict

Get the accent colors for the current theme.

Accent colors are used for interactive elements:

primary: Hover borders on input widgets (QLineEdit, QComboBox, etc.), selection backgrounds, progress bar/slider gradients (end color), menu bar selections, pressed/selected items in item views.
secondary: Progress bar/slider gradients (start color), widget item hover backgrounds, menu pressed backgrounds, list/tree item hover highlights.

Returns:

Type	Description
`dict`	Dictionary containing 'primary' and 'secondary' accent colors
`dict`	from the current theme.

Examples:

>>> colors = get_accent_colors()
>>> primary = colors["primary"]  # "#2196F3" for dark theme
>>> secondary = colors["secondary"]  # "#1976D2" for dark theme

get_available_themes ¶

get_available_themes() -> list

Get a list of all available theme names from the color configuration.

Returns:

Type	Description
`list`	List of theme names (e.g., ["dark", "light", "dracula", "one_dark_pro"]).

Examples:

>>> themes = fxstyle.get_available_themes()
>>> print(themes)  # ['dark', 'light', 'dracula', 'one_dark_pro']

get_colors ¶

get_colors() -> dict

Get the cached color configuration dictionary.

This is the preferred way to access colors throughout the application. Colors are loaded once from the YAML file and cached for subsequent calls.

Returns:

Type	Description
`dict`	The complete color configuration containing 'feedback', 'dcc', and
`dict`	'themes' sections.

Examples:

>>> colors = fxstyle.get_colors()
>>> error_color = colors["feedback"]["error"]["foreground"]
>>> dark_surface = colors["themes"]["dark"]["surface"]

get_contrast_text_color ¶

get_contrast_text_color(background_hex: str) -> str

Determine whether to use white or black text on a given background.

Uses WCAG luminance calculation to ensure readable contrast.

Parameters:

Name	Type	Description	Default
`background_hex` ¶	`str`	The background color as a hex string.	required

Returns:

Type	Description
`str`	"#FFFFFF" for dark backgrounds, "#000000" for light backgrounds.

get_default_theme ¶

get_default_theme() -> str

Get the theme an application falls back to when none is saved.

Returns:

Type	Description
`str`	The name set by `set_default_theme`, or "dark".

get_feedback_colors ¶

get_feedback_colors() -> dict

Get the feedback/status colors for notifications and logging.

These colors are used by FXNotificationBanner, FXLogWidget, and other status/feedback widgets.

Each level provides both a foreground (text/icon) and background color designed to work together with appropriate contrast.

The function first checks for theme-specific feedback colors (defined within the current theme), then falls back to the global feedback colors for backward compatibility.

Returns:

Type	Description
`dict`	Dictionary with keys: 'debug', 'info', 'success', 'warning', 'error'.
`dict`	Each value is a dict with 'foreground' and 'background' keys.

Examples:

>>> colors = fxstyle.get_feedback_colors()
>>> colors["error"]["foreground"]  # "#ff4444"
>>> colors["error"]["background"]  # "#7b2323"
>>> colors["success"]["foreground"]  # "#8ac549"

get_font_family ¶

get_font_family(role: str = 'body', theme: Optional[str] = None) -> str

Get the resolved font stack for a single role.

Parameters:

Name	Type	Description	Default
`role` ¶	`str`	One of "title", "body", or "mono". Unknown roles fall back to "body". Defaults to "body".	`'body'`
`theme` ¶	`Optional[str]`	Theme name. Defaults to the current theme.	`None`

Returns:

Type	Description
`str`	A QSS `font-family` value.

Examples:

>>> fxstyle.get_font_family("mono")
'"Consolas", "Courier New", monospace'

get_fonts ¶

get_fonts(theme: Optional[str] = None) -> Dict[str, str]

Get the resolved font stack for every role in a theme.

Parameters:

Name	Type	Description	Default
`theme` ¶	`Optional[str]`	Theme name. Defaults to the current theme.	`None`

Returns:

Type	Description
`Dict[str, str]`	Mapping of role name ("title", "body", "mono") to a QSS
`Dict[str, str]`	`font-family` value, with unavailable families already
`Dict[str, str]`	removed, so this reports what will actually be drawn.

Examples:

>>> fxstyle.get_fonts()["body"]
'"Segoe UI"'

get_icon_color ¶

get_icon_color() -> str

Get the icon color for the current theme.

This color is used to tint monochrome SVG icons so they match the theme. It's applied by fxicons.get_icon() and FXProxyStyle for standard Qt icons.

Returns:

Type	Description
`str`	The icon color as a hex string from the current theme's configuration.

Examples:

>>> color = fxstyle.get_icon_color()
>>> print(color)  # "#b4b4b4" for dark, "#424242" for light

get_icon_on_accent_primary ¶

get_icon_on_accent_primary() -> str

Get the icon color for accent_primary backgrounds.

This color should be used for icons displayed on selected items or other elements that use the accent_primary color as their background.

If not explicitly defined in the theme, falls back to text_on_accent_primary, which is auto-computed based on the accent_primary color's luminance.

Returns:

Type	Description
`str`	The icon color as a hex string for use on accent_primary backgrounds.

Examples:

>>> color = fxstyle.get_icon_on_accent_primary()
>>> print(color)  # "#ffffff" for dark theme with blue accent

get_icon_on_accent_secondary ¶

get_icon_on_accent_secondary() -> str

Get the icon color for accent_secondary backgrounds.

This color should be used for icons displayed on hovered items or other elements that use the accent_secondary color as their background.

If not explicitly defined in the theme, falls back to text_on_accent_secondary, which is auto-computed based on the accent_secondary color's luminance.

Returns:

Type	Description
`str`	The icon color as a hex string for use on accent_secondary backgrounds.

Examples:

>>> color = fxstyle.get_icon_on_accent_secondary()
>>> print(color)  # "#ffffff" for dark theme with blue accent

get_luminance ¶

get_luminance(hex_color: str) -> float

Calculate the relative luminance of a color.

Uses the WCAG 2.0 formula for relative luminance.

Parameters:

Name	Type	Description	Default
`hex_color` ¶	`str`	A hex color string (e.g., "#007ACC" or "007ACC").	required

Returns:

Type	Description
`float`	The relative luminance value between 0 (black) and 1 (white).

get_theme ¶

get_theme() -> str

Get the current theme name.

On first access, the theme is loaded from persistent storage. If no theme was previously saved, defaults to "dark".

Returns:

Type	Description
`str`	The current theme name (e.g., "dark", "light").

get_theme_colors ¶

get_theme_colors() -> dict

Get the color palette for the current theme.

Returns a dictionary with all semantic color roles:

Surface Colors (Backgrounds):

surface: Main widget/window backgrounds, buttons, selected tabs
surface_alt: Alternate row backgrounds in lists/tables
surface_sunken: Recessed areas - input fields, lists, menus
tooltip: Tooltip backgrounds

Border Colors:

border: Standard borders on inputs, containers, menus
border_light: Subtle borders - tooltips, buttons, tabs
border_strong: Emphasized borders - frames, separators

Text Colors:

text: Primary text for all widgets
text_muted: De-emphasized text - inactive tabs, placeholders
text_disabled: Disabled widget text
text_on_accent_primary: Text on accent_primary backgrounds (optional)
text_on_accent_secondary: Text on accent_secondary backgrounds (optional)

Interactive States:

state_hover: Hover state backgrounds
state_pressed: Pressed/checked/active backgrounds

Scrollbar Colors:

scrollbar_track: Track/gutter background
scrollbar_thumb: Draggable thumb
scrollbar_thumb_hover: Thumb hover state

Layout Colors:

grid: Table gridlines, header borders
separator: Separator/splitter hover backgrounds

Slider Colors:

slider_thumb: Slider handle color
slider_thumb_hover: Slider handle hover/pressed

Icon Colors:

icon: Tint color for monochrome icons
icon_on_accent_primary: Icon color on accent_primary backgrounds (optional)
icon_on_accent_secondary: Icon color on accent_secondary backgrounds (optional)

Returns:

Type	Description
`dict`	Dictionary containing theme-specific colors.

Examples:

>>> colors = get_theme_colors()
>>> bg = colors["surface"]  # "#302f2f" for dark
>>> sunken = colors["surface_sunken"]  # Input/list backgrounds
>>> text = colors["text"]  # Primary text color

invalidate_standard_icon_map ¶

invalidate_standard_icon_map() -> None

Invalidate the cached standard icon map.

This should be called when changing themes so icons are regenerated with the new color scheme on next access.

is_light_theme ¶

is_light_theme() -> bool

Check if the current theme is a light theme.

Determines theme brightness by analyzing the surface color's lightness. This is more reliable than checking the theme name since it works with any custom theme.

Returns:

Type	Description
`bool`	True if the current theme is light, False if dark.

Examples:

>>> if fxstyle.is_light_theme():
...     use_dark_icons()
... else:
...     use_light_icons()

load_saved_theme ¶

load_saved_theme() -> str

Load the saved theme from persistent storage.

If no theme has been saved, returns the default theme -- "dark", or whatever set_default_theme was given.

Returns:

Type	Description
`str`	The saved theme name, or the default if none is saved or the
`str`	saved one is not offered by the current color file.

Examples:

>>> theme = fxstyle.load_saved_theme()
>>> print(theme)  # "dracula" if previously saved

load_stylesheet ¶

load_stylesheet(
    style_file: str = STYLE_FILE, extra: Optional[str] = None, theme: str = None
) -> str

Load the stylesheet and replace placeholders with actual values.

Note

Kept for backward compatibility and manual DCC styling. New code should rely on :func:register_themed_root / :func:apply_theme, which use :func:build_stylesheet (including registered widget fragments; this function does not).

Parameters:

Name	Type	Description	Default
`style_file` ¶	`str`	The path to the QSS file. Defaults to `STYLE_FILE`.	`STYLE_FILE`
`extra` ¶	`Optional[str]`	Extra stylesheet content to append. Defaults to None.	`None`
`theme` ¶	`str`	The theme to use (e.g., "dark", "light", "dracula"). If None, uses the saved theme from persistent storage.	`None`

Returns:

Type	Description
`str`	The stylesheet with all placeholders replaced.

mark_as_title ¶

mark_as_title(widget: QWidget, is_title: bool = True) -> None

Draw a widget's text in the theme's title font role.

Sets the dynamic property the theme stylesheet keys the title role on, then repolishes so the change lands on an already-shown widget. Only the family changes: size and weight keep coming from whatever rule or setFont call already governed the widget.

With a color file that leaves title empty, or names the same family for both roles, this is a no-op visually.

Parameters:

Name	Type	Description	Default
`widget` ¶	`QWidget`	The widget whose text is a title.	required
`is_title` ¶	`bool`	False removes the mark and returns the widget to the body role. Defaults to True.	`True`

Examples:

>>> heading = QLabel("Render Settings")
>>> fxstyle.mark_as_title(heading)

register_fonts ¶

register_fonts(paths) -> Dict[str, list]

Register font files with Qt so a color file may name them.

Hands each file to QFontDatabase.addApplicationFont and reports the outcome per file instead of swallowing it: a face that fails to load is not an error Qt raises, it is a family that silently is not there, and the stylesheet naming it then renders as an arbitrary substitution. Themed roots are restyled afterwards, so registering late is safe and call order does not matter.

Parameters:

Name	Type	Description	Default
`paths` ¶		A font file path, or an iterable of them. Anything `QFontDatabase` accepts (`.ttf`, `.otf`).	required

Returns:

Type	Description
`Dict[str, list]`	Mapping of each path, as given, to the family names Qt
`Dict[str, list]`	registered from it. **An empty list means that file did not
`Dict[str, list]`	load.** Those family names are the ones to put in the color
`Dict[str, list]`	file's `fonts:` section; a file's family is not always
`Dict[str, list]`	predictable from its filename.

Examples:

>>> loaded = fxstyle.register_fonts(brand_dir.glob("*.ttf"))
>>> missing = [path for path, families in loaded.items()
...            if not families]

Note

Qt needs a live QApplication before it will accept an application font. Called earlier than that, every file reports as failed.

register_themed_root ¶

register_themed_root(root: QObject) -> None

Register a widget (or QApplication) as a themed root.

The current theme stylesheet is applied to it immediately and re-applied on every subsequent :func:apply_theme call. Qt cascades the sheet to all descendants, so children need no registration.

Standalone apps: FXApplication registers itself; nothing to do. DCC-embedded windows: FXMainWindow registers itself when the running QApplication is foreign, so the host app is never restyled.

Roots are held weakly; destroyed widgets drop out automatically.

Parameters:

Name	Type	Description	Default
`root` ¶	`QObject`	Any object with `setStyleSheet` (QWidget or QApplication).	required

register_widget_style ¶

register_widget_style(qss: str) -> None

Register a widget's QSS fragment with the theme stylesheet.

Call once at module import time. The fragment may use @tokens (e.g. @surface, @border); use your widget's class name as selector to scope the rules. Identical fragments are registered once.

If themed roots already exist, the rebuilt sheet is re-applied to them immediately, so late registration is safe.

Parameters:

Name	Type	Description	Default
`qss` ¶	`str`	Stylesheet fragment with optional `@token` placeholders.	required

Examples:

>>> fxstyle.register_widget_style('''
...     MyWidget { background: @surface; border: 1px solid @border; }
... ''')

replace_colors ¶

replace_colors(
    stylesheet: str, colors_dict: dict = None, prefix: str = ""
) -> str

Replace color placeholders in a stylesheet with actual color values.

This function searches for placeholders in the format @{prefix}{key} and replaces them with the corresponding color values from the dictionary.

Parameters:

Name	Type	Description	Default
`stylesheet` ¶	`str`	The stylesheet string containing color placeholders.	required
`colors_dict` ¶	`dict`	Dictionary containing color definitions. Only top-level non-dict values are used. Defaults to colors from get_colors().	`None`
`prefix` ¶	`str`	Prefix for placeholder names. Defaults to empty string.	`''`

Returns:

Type	Description
`str`	The stylesheet with all matching placeholders replaced.

Examples:

>>> colors = {"primary": "#FF5722", "secondary": "#E64A19"}
>>> qss = "color: @primary; background: @secondary;"
>>> result = replace_colors(qss, colors)
>>> print(result)
'color: #FF5722; background: #E64A19;'

save_theme ¶

save_theme(theme: str) -> None

Save the current theme to persistent storage.

Parameters:

Name	Type	Description	Default
`theme` ¶	`str`	The theme name to save.	required

Examples:

>>> fxstyle.save_theme("dracula")

set_color_file ¶

set_color_file(color_file: str) -> None

Set a custom color configuration file.

This clears the color cache and sets the new file as the active color source. The next call to get_colors() will load from this file.

Supports both YAML (.yaml, .yml) files with inheritance via anchors.

Parameters:

Name	Type	Description	Default
`color_file` ¶	`str`	Path to the custom YAML color configuration file.	required

Examples:

>>> fxstyle.set_color_file("path/to/custom_theme.yaml")
>>> colors = fxstyle.get_colors()  # Loads from custom file

set_default_theme ¶

set_default_theme(theme: str) -> None

Set the theme an application falls back to when none is saved.

"dark" unless this is called. For an application that ships a theme of its own in a custom color file: without this, its own first run is indistinguishable from a person having chosen "dark", so it cannot both honour a saved choice and default to its own brand.

Not validated here, because the color file that has to offer the theme may be set afterwards; load_saved_theme falls back to "dark" if the file turns out not to offer it.

Parameters:

Name	Type	Description	Default
`theme` ¶	`str`	The theme name to fall back to.	required

Examples:

>>> fxstyle.set_color_file("studio_colors.yaml")
>>> fxstyle.set_default_theme("studio")
>>> fxstyle.apply_theme(fxstyle.load_saved_theme())

set_style ¶

set_style(widget: QWidget, style: str = None) -> FXProxyStyle

Set the style.

Parameters:

Name	Type	Description	Default
`widget` ¶	`QWidget`	The QWidget subclass to set the style to.	required
`style` ¶	`str`	The style to set. Defaults to None.	`None`

Returns:

Type	Description
`FXProxyStyle`	The custom style.

Note

You can retrieve the styles available on your system with QStyleFactory.keys(). Only those string values are accepted in the style argument.

fxstyle

fxstyle ¶

Theme Color Reference¶

Theme Font Reference¶

Classes¶

FXProxyStyle ¶

Methods:¶

set_icon_color ¶

standardIcon ¶

FXThemeAware ¶

Attributes¶

theme property ¶

Methods:¶

__apply_theme_style_attribute ¶

__handle_theme_change ¶

FXThemeColors ¶

colors_dict ¶

Methods:¶

FXThemeManager ¶

Attributes¶

current_theme property ¶

Methods:¶

notify_theme_changed ¶

Functions:¶

apply_theme ¶

theme ¶

widget ¶

build_stylesheet ¶

theme ¶

colors ¶

get_accent_colors ¶

get_available_themes ¶

get_colors ¶

get_contrast_text_color ¶

background_hex ¶

get_default_theme ¶

get_feedback_colors ¶

get_font_family ¶

role ¶

theme ¶

get_fonts ¶

theme ¶

get_icon_color ¶

get_icon_on_accent_primary ¶

get_icon_on_accent_secondary ¶

get_luminance ¶

hex_color ¶

get_theme ¶

get_theme_colors ¶

invalidate_standard_icon_map ¶

is_light_theme ¶

load_saved_theme ¶

load_stylesheet ¶

style_file ¶

extra ¶

theme ¶

mark_as_title ¶

widget ¶

is_title ¶

register_fonts ¶

paths ¶

register_themed_root ¶

root ¶

register_widget_style ¶

qss ¶

replace_colors ¶

stylesheet ¶

colors_dict ¶

prefix ¶

save_theme ¶

theme ¶

set_color_file ¶

color_file ¶

set_default_theme ¶

theme ¶

set_style ¶

widget ¶

style ¶

theme `property` ¶

`colors_dict` ¶

current_theme `property` ¶

`theme` ¶

`widget` ¶

`theme` ¶

`background_hex` ¶

`role` ¶

`theme` ¶

`theme` ¶

`hex_color` ¶

`style_file` ¶

`extra` ¶

`theme` ¶

`widget` ¶

`is_title` ¶

`paths` ¶

`root` ¶

`qss` ¶

`stylesheet` ¶

`colors_dict` ¶

`prefix` ¶

`theme` ¶

`color_file` ¶

`theme` ¶

`widget` ¶

`style` ¶