Theming¶

fxgui uses a YAML configuration file to define all theme colors. YAML supports anchors and aliases for theme inheritance, allowing you to create new themes that extend existing ones and override only specific colors.

Understanding the Theme Structure¶

The default style.yaml file contains several sections:

# DCC branding colors
dcc:
  houdini: "#ff6600"
  maya: "#38a6cc"
  nuke: "#fcb434"

# Theme definitions with inheritance
themes:
  dark: &dark  # Define anchor for inheritance
    accent_primary: "#2196F3"
    # ... all colors ...
    feedback:  # status colours: debug, info, success, warning, error
      error:
        foreground: "#ff4444"
        background: "#7b2323"

  dracula:
    <<: *dark  # Inherit from dark theme
    accent_primary: "#bd93f9"  # Override specific colors

Theme Color Roles - Complete Reference¶

Each theme defines semantic color roles. All names are designed to clearly indicate their purpose:

Accent Colors¶

Surface Colors (Backgrounds)¶

frame, well, pane_border and splitter_mark are computed when a theme leaves them out, and a theme that states one keeps its own value:

• frame is surface_sunken when that is darker than surface by a contrast of at least fxstyle.FRAME_MIN_CONTRAST (1.06). Otherwise it is surface darkened toward black until it is, which keeps the pane's own tint and never brings in the accent. In every bundled dark theme, and in github_light and catppuccin_latte, that is surface_sunken; light and solarized_light have a sunken surface as light as the pane, so they get a darkened one.
• A pane too dark to darken (pure black, as in an OLED theme) gets a frame lighter than itself instead.
• well is half-way from surface to frame, so a list inside a pane reads one step deeper than the pane and one step shallower than the frame. Where half-way differs from surface by less than fxstyle.WELL_MIN_CONTRAST (1.04), the well moves on toward the frame until it does; github_light is the one bundled theme where that happens.
• pane_border is border when that differs from frame by a contrast of at least fxstyle.PANE_BORDER_MIN_CONTRAST (1.3). Otherwise it is border pushed further from the frame (darker on a light frame, lighter on a dark one) until it does. light and catppuccin_latte get a darker one; every other bundled theme keeps its border.
• splitter_mark is border, else border_light, else border_light moved toward text, whichever first differs from frame by fxstyle.SPLITTER_MARK_MIN_CONTRAST (1.3). light and catppuccin_latte use border_light.

Border Colors¶

Text Colors¶

text and text_muted are held to 4.5:1 (fxstyle.TEXT_CONTRAST, WCAG AA) on every surface they sit on: surface, surface_sunken, surface_alt, well, frame, tooltip and state_hover, and text on state_pressed too. A theme's value that misses it is darkened or lightened until it reads, so fxstyle.colors().text can differ from the file. text then moves on until it stands 1.5:1 off text_muted (fxstyle.MUTED_STEP), so the two always read as two ranks; where text is already black or white, text_muted steps back toward the surface instead, as far as it still reads at 4.5:1.

An omitted text_on_accent_* is black or white, whichever reads better on the accent.

Interactive State Colors¶

Scrollbar Colors¶

Layout Colors¶

Shadow¶

Icon Color¶

Feedback Colors Reference¶

Each theme has a feedback: block; a theme without one takes dark's. Used by FXNotificationBanner, FXOutputLogWidget, and other status widgets. Each colour is a token, feedback_<level>_<part>: fxstyle.colors().feedback_error_foreground, or fxstyle.qcolor("feedback_error_foreground") for a QColor.

DCC Colors Reference¶

Used by DCC-specific widgets and branding elements:

Creating Your Custom Theme¶

1. Copy the default file as a starting point:

from pathlib import Path
from fxgui import fxstyle

# The default style.yaml location
default_file = fxstyle.DEFAULT_COLOR_FILE
print(f"Default file: {default_file}")

# Copy it to your preferred location
import shutil
custom_file = Path.home() / ".fxgui" / "my_theme.yaml"
custom_file.parent.mkdir(parents=True, exist_ok=True)
shutil.copy(default_file, custom_file)

1. Add your theme using YAML inheritance:

themes:
  # Base dark theme with anchor
  dark: &dark
    accent_primary: "#2196F3"
    surface: "#302f2f"
    # ... existing dark colors ...

  # Your custom theme inheriting from dark
  monokai:
    <<: *dark  # Inherit ALL colors from dark theme

    # Override only the colors you want to change
    accent_primary: "#A6E22E"
    accent_secondary: "#66D9EF"

    surface: "#272822"
    surface_alt: "#1e1f1c"
    surface_sunken: "#1a1a17"
    tooltip: "#3e3d32"

    border: "#49483e"
    border_light: "#75715e"
    border_strong: "#49483e"

    text: "#f8f8f2"
    text_muted: "#a59f85"
    text_disabled: "#75715e"

    state_hover: "#3e3d32"
    state_pressed: "#49483e"

    scrollbar_track: "#1e1f1c"
    scrollbar_thumb: "#49483e"
    scrollbar_thumb_hover: "#75715e"

    grid: "#49483e"

    icon: "#f8f8f2"

Using Your Custom Theme¶

from fxgui import fxstyle, fxwidgets

# Set your custom color file BEFORE creating any widgets
fxstyle.set_color_file("/path/to/my_theme.yaml")

# Check available themes (includes your custom ones)
print(fxstyle.get_available_themes())
# ['dark', 'light', 'dracula', 'one_dark_pro', 'github_dark', 'github_light',
#  'catppuccin_mocha', 'catppuccin_latte', 'nord', 'material_dark',
#  'solarized_light', 'monokai']

# Create your application
app = fxwidgets.FXApplication()
window = fxwidgets.FXMainWindow(title="Custom Theme Demo")
window.show()

# Apply your custom theme, everywhere
fxstyle.apply_theme("monokai")

app.exec()

A file that cannot be read raises OSError (FileNotFoundError for a wrong path), and one that is no YAML raises yaml.YAMLError, both from set_color_file itself. The colours already loaded stay in force.

Switching Themes at Runtime¶

from fxgui import fxstyle

fxstyle.apply_theme("dracula")

apply_theme(name) takes one theme name. It saves the choice, rebuilds the stylesheet, puts the theme's stylesheet, palette and font on every themed root, and emits theme_changed. A name that is not a theme raises ValueError; anything that is not a string raises TypeError.

What a Theme Puts on a Window¶

A themed root (see below) gets three things, and each has one job:

The base rule for every widget carries no fill and no font. So:

• label.setFont(...) keeps the size and family you gave it.
• A plain QLabel on a coloured card shows the card, not a box of its own.
• item.setBackground(...) on a list or tree item shows.
• Every list, tree and table scrolls by the pixel, in an app or inside a host. The sheet sets this each time it styles the view, so a setVerticalScrollMode call holds only until the next restyle. A view that wants to scroll by the row says so in a rule of its own, by objectName: QTreeView#shots { qproperty-verticalScrollMode: ScrollPerItem; }.

Reading Theme Colors¶

For custom drawing, read colours when you paint instead of keeping them.

from qtpy.QtGui import QColor, QPainter
from fxgui import fxstyle


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

fxstyle.colors() returns the current theme as a namespace of colour names. It is cached per theme, so reading it in every paintEvent costs one attribute lookup. It is the one way to read a colour; for a name held in a variable, getattr(fxstyle.colors(), name). An unknown name raises AttributeError listing the names that exist.

Registering Themed Roots¶

fxstyle.register_themed_root(root) makes a widget, or the QApplication itself, a themed root. It gets the current stylesheet, palette and font at once, and again on every later apply_theme(). Qt passes the stylesheet down to every child, so you register the top-level widget once.

from qtpy.QtWidgets import QApplication
from fxgui import fxstyle

application = QApplication([])
fxstyle.register_themed_root(application)

Most applications never call it:

While the QApplication is a themed root, register_themed_root(widget) does nothing. The application's sheet already reaches every widget, and a window that wore a sheet of its own as well would get the old theme's palette back on the next switch: its edges and its tab area would stay in the old colours.

A registered widget carries the fxThemedRoot property (fxstyle.ROOT_PROPERTY), which a stylesheet may select on.

Reacting to Theme Changes¶

fxstyle.theme_changed is a signal emitted after a switch, with the new theme's name. It is for side effects only: a cached pixmap to redraw, a highlighter to run again.

from fxgui import fxstyle


def _on_theme_changed(theme_name: str):
    print(f"Theme switched to {theme_name}")


fxstyle.theme_changed.connect(_on_theme_changed)

Connect a widget's own method, not a lambda. Qt drops a connection to a method of a widget when the widget is deleted; a lambda has no widget for Qt to drop it with, so it outlives the widget and runs on a dead one.

Nothing about looks needs this signal. The stylesheet, the palette, the colours read in paintEvent and the icons all take the new theme by themselves.

The Control Language¶

Every fxgui control is built from the same few parts. A new control reuses them, so it looks like it belongs.

Size and shape¶

No rule names a 2, 4 or 8 px radius in pixels. Two shapes do keep pixels: a pill (a slider groove, a scroll thumb, a progress bar) rounds at half its thickness, and a part set inside a 1 px border rounds 1 px less than its frame.

Two sizes set every height, so controls side by side share one centre line:

A mark is smaller than the row and centres in it: an FXToggleSwitch is control_height tall, its 18 px track in the middle, so it lines up with the button beside it. A slider handle (14 px) and a status dot do the same. A control that sizes itself returns these from sizeHint(). A plain icon QToolButton in a toolbar sizes to its icon. The Buttons page of the gallery shows one row of every control.

A spin box reaches a line edit's height by its padding, which differs by Qt version: PySide6 6.5 sizes a spin box 3 px shorter than later Qt for the same padding, so fxstyle picks the padding when it builds the sheet.

Fills and edges by state¶

One rule under every row of the table: the accent marks keyboard focus, a selection, the current item and the primary action. Hover is never the accent. Hover is a neutral fill, so a hovered control never looks like the focused one.

A primary button (FXPrimaryButton) is filled @primary_button, hovers @primary_button_hover and presses @primary_button_pressed; its focus edge is @text, and disabled it is @surface_alt with @text_disabled. Text edits and views do not change on hover. A menu is the one place the pointer moves the current item, so there alone hover is the accent.

Focus never draws a box around a control. It recolours the edge the control already has, so nothing moves. Qt's own focus rectangle is off: FXProxyStyle (which FXApplication installs) never draws it, and inside a host each list, tree and table of a themed window gets its own FXProxyStyle when it first shows, so a focused current cell keeps its BackgroundRole on PySide6 6.5 as well.

Focus shows only after the keyboard¶

A control wears its focus look only when focus came by keyboard: Tab, Shift+Tab, or a shortcut. A click still gives the control focus, but it looks as it does at rest once the pointer leaves. This is a browser's :focus-visible.

fxgui sets the fxFocusVisible property (fxstyle.FOCUS_VISIBLE_PROPERTY) on the focused widget, true only for keyboard focus, and clears it when focus leaves. A themed root turns this on for every widget under it, including widgets made later and widgets inside a host. For your own rules, select on the property, not on :focus alone:

MyWidget[fxFocusVisible="true"]:focus { border-color: @accent_primary; }

A widget that paints its own focus look asks fxstyle.focus_visible(widget) instead of hasFocus(). The first call starts the focus watch, so ask once before the widget can take focus: in paintEvent, or once when it is built.

A colour of your own can be a token name or a colour string: fxstyle.qcolor(value) returns the QColor for either, read from the theme in force, and an invalid QColor for anything else.

Inside a host, the property reaches the host's own widgets too, but only fxgui's widgets are restyled when it changes.

Parts that must be seen¶

The bundled @border tokens sit close to the surface (about 1.2:1). That is fine for a button, whose text says what it is. A control whose shape is the only thing you see (a switch, a slider handle) needs more.

A slider's groove and span both read at 3:1 on @surface, so they cannot also read at 3:1 on each other: the bundled accents reach only 3.4:1 to 7.8:1 on their surface. The span's hue and the handle at its end tell the two apart.

3:1 is the WCAG minimum for the parts of a control (fxstyle.CONTROL_CONTRAST). fxstyle.readable_ink(background, ink, 3.0) pushes any colour of your own to it.

Accent, text and icons¶

• The accent marks the one thing to look at: the main action, a selection, the current item, a filled span, a keyboard-focused edge.
• Text is @text. Secondary text and placeholders are @text_muted. Text on an accent fill is @text_on_accent_primary.
• Icons take color="icon"; on an accent fill, icon_on_accent_primary.
• A popup (a menu, a combo box's list, a completer's list, FXCommandPalette) and a tooltip are @surface with a 1 px @border at @card_radius, their rows inset 4 px. A menu, combo or completer row is its text plus 4 px above and below, 24 px at the 12 px body font, and a separator runs the menu's full width. A hovered menu item, combo row or completer row is @accent_primary with @text_on_accent_primary text. No state moves a row's text.
• A menu bar item keeps one box, at the button radius, in every state. At rest it is bare; hovered, @state_hover; with its menu open, @state_pressed with @text.
• A table or tree header is flat @text_muted text over one 1 px @border rule, with no box around a section. It sits flush with the view's frame: a view with a header has no inner padding. A list or a tree with its header hidden keeps a 4 px inset at the top only, and a tree follows its header hidden or shown at any time. Rows run to the frame's sides, and a scroll bar's thumb sits centred between the rows and the frame.
• A splitter handle and the gap between dock widgets show nothing until the pointer finds them, then fill with @accent_primary. A splitter marked with mark_as_frame keeps its painted dots.
• A progress bar is a 4 px pill: a @control_edge track and an @accent_primary chunk, no text unless you turn it on with setTextVisible(True). It is the slider's groove.
• A tab widget's page is a pane card (@surface, a 1 px @pane_border), as a dock pane is. A QToolBox section is a flat 28 px header with a chevron, a hover fill and the open one at weight 600. A plain QDockWidget title is flat @surface with @text.
• A tab bar too full for its tabs scrolls. Its two scroll buttons are opaque in the strip's colour, with a 4 px gap off the last tab's cut text.

Popups, cards and shadows¶

A shadow reads its colour and blur from the theme each time it draws, so it follows a switch with no call.

FXCommandPalette opens centred across its window. position puts it at "top" (under the menu bar and the command rows), "center" (the default) or "bottom" (over the status bar). It stays inside a window too small for it. Anything else raises ValueError.

Sliders and switches¶

The switch's fills are pushed to 3:1 on @surface when a theme's own accent misses it.

Every QSlider gets these rules from the base sheet.

Cards in item views¶

FXThumbnailDelegate draws a row as a card when the row has a Qt.BackgroundRole. The fill is that colour. Give it a token name, and the card follows every theme switch:

from qtpy.QtCore import Qt
from qtpy.QtWidgets import QTreeWidgetItem

item = QTreeWidgetItem(["sh010"])
item.setData(0, Qt.BackgroundRole, "surface")

The card's edge is @border_light. A selected card is filled and edged with @accent_primary. A row with no background has no card.

A hovered row is filled with @state_hover and keeps its own text colour, as in a plain list. On a card whose shade comes within 1.2:1 of @state_hover, as a deep row's does, the hover is the card itself made 1.2:1 lighter (darker on a light theme). Call FXThumbnailDelegate.apply_transparent_selection(view) on the view so Qt's own highlight does not show under the delegate's.

Registering Your Own Widget Styles¶

fxstyle.register_widget_style(qss) adds a QSS fragment to the theme stylesheet. Call it once, when your module is imported, with your class name as the selector. The fragment may use any @token.

from fxgui import fxstyle

fxstyle.register_widget_style("""
    MyWidget {
        background: @surface;
        border: 1px solid @border;
        border-radius: 4px;
    }
""")

An image in a rule names an icon and a token: image: ~icon(expand_more, icon); draws the icon library's expand_more in the theme's @icon colour. Every arrow and chevron of the base sheet is drawn this way. The icon is written as a PNG at 16 px, and at 2x and 3x for scaled screens; give the size the rule draws it at as a third value, ~icon(expand_more, icon, 12), or Qt shrinks the 16 px picture and blurs it. A PNG, unlike an SVG, needs no Qt plugin, which some DCCs fail to load.

Fragments come after the base stylesheet and are resolved again on every switch. Registering after themed roots exist re-applies the sheet to them at once, so import order does not matter.

To style a window inside a DCC, register it with fxstyle.register_themed_root(window): it gets the sheet, the rules a window inside a host needs, the palette and the font, and again on every switch. fxstyle.resolve(qss) resolves the tokens of a sheet of your own.

Repolishing After a Property Change¶

If your QSS uses a dynamic property in a selector, for example MyBanner[level="error"] { ... }, Qt does not look at the rule again when you call setProperty(). Call fxutils.repolish() after it:

from qtpy.QtWidgets import QLabel
from fxgui import fxutils

banner = QLabel("Disk full")
banner.setProperty("level", "error")
fxutils.repolish(banner)

The Custom Widget Contract¶

A custom widget follows the theme with no base class and no signal when it does one of these:

Connect to fxstyle.theme_changed only for a side effect a switch has beyond looks.

from qtpy.QtCore import Qt
from qtpy.QtGui import QColor, QPainter
from qtpy.QtWidgets import QWidget
from fxgui import fxstyle

fxstyle.register_widget_style("""
    MyStatusChip {
        border: 1px solid @border;
        border-radius: 10px;
    }
""")


class MyStatusChip(QWidget):
    """A chip that takes the theme's colours when painted."""

    def paintEvent(self, event):
        painter = QPainter(self)
        painter.fillRect(self.rect(), QColor(fxstyle.colors().surface))
        painter.setPen(QColor(fxstyle.colors().text))
        painter.drawText(self.rect(), Qt.AlignCenter, "Ready")

Available Color Tokens¶

Every role in the tables at the top of this page is a token: @surface in QSS, fxstyle.colors().surface in code. So are the computed ones: @text_on_accent_primary, @icon_on_accent_primary, @primary_button, @control_edge, @card_radius, @shadow, @shadow_blur, the flattened feedback colours (@feedback_error_foreground, @feedback_info_background, ...), @button_radius and the font roles (@font_body, @font_title, @font_mono).