Skip to content

fxstyle

Themes for fxgui: the stylesheet, palette, font and colours of each.

A themed root (see register_themed_root) wears the theme's stylesheet (shapes, borders, states, each widget's look), palette (default fills) and font (body family, FONT_SIZE). apply_theme(name) puts the new theme on every root and emits theme_changed. Custom painting reads colors(); icons name their colours by token (see fxicons). Every colour role is listed at the top of style.yaml; font roles (title, body, mono) come from its fonts: block.

Examples:

>>> from fxgui import fxstyle
>>> fxstyle.apply_theme("one_dark_pro")
>>> fxstyle.register_themed_root(window)  # a window inside a host
>>> surface = fxstyle.colors().surface

Classes:

Name Description
FXProxyStyle

Give Qt's standard icons (dialogs, message boxes) fxgui's themed icons.

FXThemeColors

A theme's resolved colours, one attribute per role; colors returns it.

Functions:

Name Description
apply_column_lines

Rule every column of tables and trees, or only the first; re-paint.

apply_row_size

Make every list and tree row size tall, save it when chosen, re-lay.

apply_theme

Apply a theme to every themed root and emit theme_changed.

arrive

Make what widget shows next arrive as the web look's content does.

colors

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

column_lines

Return whether tables and trees rule every column, the saved choice.

control_height

Return the height a push button comes to in widget's font.

depth_shade

Return a tree row's base colour tinted for its depth.

draw_column_rule

Draw a cell's column rule at its right edge, if it has one.

drawn_weight

Return the weight Qt draws for a CSS weight in theme.

ease_out

Return the curve every fade and slide eases out on.

ease_spring

Return the curve anything that travels rides: a spring settling.

focus_visible

Return whether widget has focus that came by keyboard.

font

Build a role's font: its installed family, weight and hinting.

font_rank

Return a text rank's pixel size and the weight Qt draws it at.

get_available_themes

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

get_colors

Return the loaded colour file as written, before any token is derived.

get_contrast_ratio

Return the WCAG contrast ratio between two colors, 1.0 to 21.0.

get_default_theme

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

get_luminance

Calculate the relative luminance of a color.

get_theme

Get the current theme name.

ink

Write a widget's text in one theme colour, through the stylesheet.

ink_section

Write one header section's label in one theme colour.

is_light_theme

Return whether the current theme is light, judged by its surface.

load_saved_theme

Load the saved theme from persistent storage.

mark_as_frame

Paint a widget in the theme's frame color, as window chrome.

mark_as_nav

Draw an item view as a navigation list, as a sidebar's.

mark_as_segmented

Draw a tab bar as a segmented switch, as for Table | Gantt views.

mark_as_thin_scroll

Draw a scroll area as part of the card it sits on.

mark_as_title

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

mark_compact

Make a button or a combo box the compact size: COMPACT_HEIGHT tall.

mark_dense

Make a view's rows one row size under the one in force.

mark_flush

Draw a view that fills its pane with no frame of its own.

mix

Return the hex colour amount (0 to 1) of the way from one to two.

mix_oklab

Return the hex colour amount of the way from one to two, in OKLab.

motion

Whether animations play: not under REDUCED_MOTION_VAR.

overlay_color_file

Merge a colour file onto the loaded one, then re-apply the theme.

palette

Build a QPalette from a theme's resolved colours.

qcolor

Return a QColor for a theme token name, a colour or a QColor, now.

readable_ink

Return an ink that reads on background at floor:1 or better.

register_fonts

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

register_themed_root

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

register_widget_style

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

resolve

Replace every @token and ~icons placeholder in a stylesheet.

row_height

Return the height, in pixels, of a list or tree row.

row_size

Return the ROW_SIZES name in force, the saved one on first access.

save_theme

Save the current theme to persistent storage.

set_color_file

Replace the whole colour file, then re-apply the theme everywhere.

set_default_theme

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

set_style

Give widget (or the application) FXProxyStyle over a Qt style.

set_tab_count

Show a count after a tab's label, as a small ringed badge.

state_contrast

Return the least contrast a theme holds its hover and pressed fills to.

step_toward

Return the first hex colour from start to toward that is done.

unregister_themed_root

Forget root: later theme switches no longer restyle it.

Classes

FXProxyStyle

Bases: QProxyStyle

Give Qt's standard icons (dialogs, message boxes) fxgui's themed icons.

Examples:

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

Methods:

Name Description
drawControl

Draw element; a header section's label in its own ink.

drawItemPixmap

Draw pixmap in rect; a tool button's icon centred at any size.

drawPrimitive

Draw element, except Qt's focus rectangle; rule a view's rows.

pixelMetric

Return metric; layouts space one pane gap, list and toolbar icons

polish

Lay an item view's rows out again once the sheet has styled them.

sizeFromContents

Return a size; a tree's or list's row is the row size in force.

standardIcon

Return an icon for the given standardIcon.

styleHint

Return hint; a tooltip keeps the next one quick for 300 ms.

subElementRect

Return element's rect; a header's sort arrow follows its label.

Methods:

drawControl
drawControl(element, option, painter, widget=None)

Draw element; a header section's label in its own ink.

A section given one by ink_section wears it, a sorted one the strong ink. No sheet pseudo-state tells either, so the label is recoloured here, under the sheet's own colour for the section.

drawItemPixmap
drawItemPixmap(painter, rect, alignment, pixmap)

Draw pixmap in rect; a tool button's icon centred at any size.

The sheet draws a tool button's icon through here, with no widget: the painter's device is the button.

drawPrimitive
drawPrimitive(element, option, painter, widget=None)

Draw element, except Qt's focus rectangle; rule a view's rows.

PySide6 6.5's Fusion and Windows 11 draw it on an item view's current cell whatever the sheet's outline says, tinting its BackgroundRole; every fxgui control shows focus in its own edge. A table, tree or list cell gets Lumen's hairline under it here, over its own BackgroundRole: a sheet ::item border would hide that colour.

pixelMetric
pixelMetric(metric, option=None, widget=None)

Return metric; layouts space one pane gap, list and toolbar icons 16 px, a tree's levels 22 px.

A themed tab's close button widens to the left by the room its glyph needs to stand as far in from the pill's edge as the text does.

polish
polish(widget)

Lay an item view's rows out again once the sheet has styled them.

sizeFromContents
sizeFromContents(kind, option, size, widget=None)

Return a size; a tree's or list's row is the row size in force.

Read each time a row is measured, so apply_row_size is a relayout. A sheet rule that sets a row's own height (a popup's, a navigation list's) still wins; a word-wrapping list's rows grow with their text.

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.

styleHint
styleHint(hint, option=None, widget=None, returnData=None)

Return hint; a tooltip keeps the next one quick for 300 ms.

Qt's window is 2 s from the moment a tip shows: within it, the next target's tip shows at once instead of after the 700 ms wait.

subElementRect
subElementRect(element, option, widget=None)

Return element's rect; a header's sort arrow follows its label.

A cell's text, icon and check box take the sheet's rects: Qt 6.8 and older paint a resting row natively, here, without the item's padding, and a highlighted one through the sheet, with it.

FXThemeColors

FXThemeColors(colors_dict: dict)

A theme's resolved colours, one attribute per role; colors returns it.

Examples:

>>> fxstyle.colors().surface  # "#302f2f"

Hold each role of colors_dict as an attribute.

Methods:

Functions:

apply_column_lines

apply_column_lines(on: bool, *, save: Optional[bool] = None) -> bool

Rule every column of tables and trees, or only the first; re-paint.

Item views and summary rows repaint and column_lines_changed is emitted; nothing is restyled and theme_changed stays quiet.

Parameters:

Name Type Description Default

on

bool

True rules every column; False only the first.

required

save

Optional[bool]

Whether to save it as the person's choice. None (the default) saves unless Qt runs headless, as apply_row_size.

None

Examples:

>>> fxstyle.apply_column_lines(True)

apply_row_size

apply_row_size(size: str, *, save: Optional[bool] = None) -> str

Make every list and tree row size tall, save it when chosen, re-lay.

Item views lay their rows out again and row_size_changed is emitted; nothing is restyled and theme_changed stays quiet.

Parameters:

Name Type Description Default

size

str

A ROW_SIZES name.

required

save

Optional[bool]

Whether to save the row size as the person's choice. None (the default) saves unless Qt runs headless (the "offscreen" or "minimal" platform), so a script or a test never overwrites it.

None

Raises:

Type Description
ValueError

If size is not a ROW_SIZES name.

Examples:

>>> fxstyle.apply_row_size("small")

apply_theme

apply_theme(theme: str, *, save: Optional[bool] = None) -> str

Apply a theme to every themed root and emit theme_changed.

Parameters:

Name Type Description Default

theme

str

The theme name to apply (e.g., "dark", "light").

required

save

Optional[bool]

Whether to save the theme as the person's choice. None (the default) saves unless Qt runs headless (the "offscreen" or "minimal" platform), so a script or a test never overwrites it.

None

Returns:

Type Description
str

The theme that was applied.

Raises:

Type Description
ValueError

If the theme does not exist.

TypeError

If theme is not a theme name.

Examples:

>>> fxstyle.apply_theme("dracula")

arrive

arrive(widget: QWidget, *, side: bool = False) -> _Arrival

Make what widget shows next arrive as the web look's content does.

The new content fades in from the ground as it rises 4 px into place over MOTION_BASE on ease_out; with side, it slides 24 px in from the right on ease_spring over MOTION_SPRING, as a side panel. Used as a context manager around the change, what widget showed before leaves over MOTION_INSTANT as the new arrives; called after the change, the new arrives from the ground. One overlay paints two snapshots with a painter's opacity, so a big live tree costs two renders, never a graphics effect; the widget lays out and takes input underneath as ever. Nothing moves under reduced motion (REDUCED_MOTION_VAR), on a hidden widget, or while its window fades in. A second arrival takes over from the first where it stands.

Parameters:

Name Type Description Default

widget

QWidget

What shows the content: a block, a pane, or a view's viewport (view.viewport(), so the header stays).

required

side

bool

Slide in from the right, as a side panel opening.

False

Returns:

Type Description
_Arrival

A context manager; called alone, it is already under way.

Examples:

>>> with fxstyle.arrive(detail_block):
...     detail_block.fill(data)
>>> panel.show()
>>> fxstyle.arrive(panel, side=True)

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))

column_lines

column_lines() -> bool

Return whether tables and trees rule every column, the saved choice.

Off unless chosen (apply_column_lines): the first column is ruled either way, as the web look's pinned name column.

control_height

control_height(widget: QWidget) -> int

Return the height a push button comes to in widget's font.

depth_shade

depth_shade(base: Union[str, QColor], depth: int) -> str

Return a tree row's base colour tinted for its depth.

Each level steps DEPTH_STEP toward the theme's border_light, its mid-tone rather than its text, which washes a dark blue to grey. The step is held back where the text would fall under 4.5:1.

Parameters:

Name Type Description Default

base

Union[str, QColor]

The row's colour at depth 0, anything QColor reads.

required

depth

int

How many rows sit above it; 0 is a top-level row.

required

Examples:

>>> fxstyle.depth_shade(fxstyle.colors().surface, 2)

draw_column_rule

draw_column_rule(
    painter: QPainter, rect: QRect, view: Optional[QWidget], column: int
) -> None

Draw a cell's column rule at its right edge, if it has one.

For an item delegate that paints its own cells; fxgui's own views and FXThumbnailDelegate draw it already.

Parameters:

Name Type Description Default

painter

QPainter

The painter on the view's viewport.

required

rect

QRect

The cell's rect.

required

view

Optional[QWidget]

The view the cell is in.

required

column

int

The cell's logical column.

required

drawn_weight

drawn_weight(weight: int, theme: Optional[str] = None) -> int

Return the weight Qt draws for a CSS weight in theme.

Chromium draws light text on a dark ground darker than Qt does (Qt blends DirectWrite's coverage with the system's ClearType gamma and no contrast boost): measured on Windows, Inter at 13 px in a dark theme needs one step more in Qt to lay down the ink a browser does. Dark text on a light ground draws alike in both, so it keeps its weight.

Parameters:

Name Type Description Default

weight

int

A weight on the CSS scale, such as EMPHASIS_WEIGHT.

required

theme

Optional[str]

Theme name. Defaults to the current theme.

None

Returns:

Type Description
int

The weight to give a QFont or a sheet, at most 900.

Raises:

Type Description
ValueError

If weight is not a multiple of 100 from 100 to 900.

Examples:

>>> font.setWeight(QFont.Weight(fxstyle.drawn_weight(fxstyle.EMPHASIS_WEIGHT)))

ease_out

ease_out() -> QEasingCurve

Return the curve every fade and slide eases out on.

Fast off the mark, long and gentle into place: the cubic bezier (0.2, 0) (0, 1).

Returns:

Type Description
QEasingCurve

A new QEasingCurve.

Examples:

>>> animation.setEasingCurve(fxstyle.ease_out())

ease_spring

ease_spring() -> QEasingCurve

Return the curve anything that travels rides: a spring settling.

Run it over MOTION_SPRING. The spring's closed form, sampled with its slope at _SPRING_SEGMENTS points, as a bezier spline: Qt keeps no Python easing function safely once it copies the curve.

Returns:

Type Description
QEasingCurve

A new QEasingCurve.

Examples:

>>> animation.setDuration(fxstyle.MOTION_SPRING)
>>> animation.setEasingCurve(fxstyle.ease_spring())

focus_visible

focus_visible(widget: QWidget) -> bool

Return whether widget has focus that came by keyboard.

The first call starts the focus watch, so a widget that draws its own focus look asks once before its first focus: when it is built or paints.

font

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

Build a role's font: its installed family, weight and hinting.

The body role is the root font, set on every themed root with the palette; a child's own setFont wins over it, which a sheet font rule would not allow. Another role is for code that takes a QFont, such as a QGraphicsTextItem. A role that falls to the generic monospace names the platform's fixed-pitch family.

Parameters:

Name Type Description Default

theme

Optional[str]

Theme name. Defaults to the current theme.

None

role

str

A role of the fonts: block. Defaults to "body".

'body'

Raises:

Type Description
ValueError

If the role names a weight or hinting fxgui lacks.

Examples:

>>> item.setFont(fxstyle.font(role="mono"))

font_rank

font_rank(name: str, theme: Optional[str] = None) -> Tuple[int, int]

Return a text rank's pixel size and the weight Qt draws it at.

The weight is drawn_weight of the rank's CSS weight, so a QFont built from it matches the sheet's own text in that theme.

"body" is the root font's; a title rank ("section", "card", or one the color file's fonts: ranks: adds) is what mark_as_title(widget, rank=name) sets.

Parameters:

Name Type Description Default

name

str

"body" or a title rank.

required

theme

Optional[str]

Theme name. Defaults to the current theme.

None

Returns:

Type Description
int

The size in pixels and the weight, e.g. (15, 600) for

int

"section" in a dark theme, (15, 500) in a light one.

Raises:

Type Description
ValueError

If name is not "body" nor a rank of the theme.

Examples:

>>> size, weight = fxstyle.font_rank("section")

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

Return the loaded colour file as written, before any token is derived.

For the file's own sections (dcc, fonts, each theme's raw values); a theme's resolved colours are colors.

Examples:

>>> fxstyle.get_colors()["dcc"]["houdini"]
'#ff6600'

get_contrast_ratio

get_contrast_ratio(one_hex: str, two_hex: str) -> float

Return the WCAG contrast ratio between two colors, 1.0 to 21.0.

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_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

Any colour QColor reads ("#007ACC", "white"), or hex without its "#" ("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").

ink

ink(widget: QWidget, token: Optional[str]) -> None

Write a widget's text in one theme colour, through the stylesheet.

The rule is the theme's, so the colour follows every theme switch. An inked label also loses its own fill, so it shows what it sits on.

Parameters:

Name Type Description Default

widget

QWidget

The widget whose text to ink.

required

token

Optional[str]

One of INKS, e.g. "text_muted"; None returns the widget to its default ink.

required

Raises:

Type Description
ValueError

If token is not one of INKS.

Examples:

>>> fxstyle.ink(hint_label, "text_muted")
>>> fxstyle.ink(hint_label, None)

ink_section

ink_section(header: QHeaderView, section: int, token: Optional[str]) -> None

Write one header section's label in one theme colour.

Over the sheet's muted header ink and a sorted section's strong one: a weekend's day dimmed, today's in the accent.

Parameters:

Name Type Description Default

header

QHeaderView

The header view.

required

section

int

The logical section.

required

token

Optional[str]

One of INKS, e.g. "text_dimmed" or "accent_primary"; None gives the section the header's own ink back.

required

Raises:

Type Description
ValueError

If token is not one of INKS.

Examples:

>>> fxstyle.ink_section(table.horizontalHeader(), 5, "text_dimmed")

is_light_theme

is_light_theme() -> bool

Return whether the current theme is light, judged by its surface.

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

mark_as_frame

mark_as_frame(widget: QWidget, is_frame: bool = True) -> None

Paint a widget in the theme's frame color, as window chrome.

Labels, check boxes, radio buttons and disabled tool buttons placed directly in it lose their own fill, so they sit on the frame. A QSplitter so marked draws its handles as frame-colored gaps, blank until the pointer finds one: then a 1 px accent line lights down its middle. Its width stays whatever setHandleWidth says.

Parameters:

Name Type Description Default

widget

QWidget

The band, bar or splitter that is part of the frame.

required

is_frame

bool

False removes the mark. Defaults to True.

True

Examples:

>>> fxstyle.mark_as_frame(project_bar)
>>> splitter.setHandleWidth(6)
>>> fxstyle.mark_as_frame(splitter)

mark_as_nav

mark_as_nav(view: QAbstractItemView, is_nav: bool = True) -> None

Draw an item view as a navigation list, as a sidebar's.

Rows are 28 px chips at the small radius; the current one is a neutral chip with its text in the accent, so it reads as a place, not a selection.

Parameters:

Name Type Description Default

view

QAbstractItemView

The list or tree of places to go to.

required

is_nav

bool

False gives it the theme's own look back. Defaults to True.

True

Examples:

>>> fxstyle.mark_as_nav(pages)

mark_as_segmented

mark_as_segmented(
    tabs: Union[QTabBar, QTabWidget], is_segmented: bool = True
) -> None

Draw a tab bar as a segmented switch, as for Table | Gantt views.

The tabs sit side by side on a state_pressed track; the picked one is a raised chip in the page colour with a 1 px border ring, its text in text_strong. The chip slides to a newly picked tab on the spring over MOTION_SPRING, or jumps under reduced motion. Keyboard and signals are the tab bar's own.

Parameters:

Name Type Description Default

tabs

Union[QTabBar, QTabWidget]

The QTabBar, or the QTabWidget whose bar to mark.

required

is_segmented

bool

False gives the bar the plain tab look back. Defaults to True.

True

Examples:

>>> views = QTabBar()
>>> views.addTab("Table")
>>> views.addTab("Gantt")
>>> fxstyle.mark_as_segmented(views)

mark_as_thin_scroll

mark_as_thin_scroll(area: QAbstractScrollArea, is_thin: bool = True) -> None

Draw a scroll area as part of the card it sits on.

No fill and no border of its own.

Parameters:

Name Type Description Default

area

QAbstractScrollArea

The scroll area, or any QAbstractScrollArea.

required

is_thin

bool

False gives it the theme's own look back. Defaults to True.

True

Examples:

>>> fxstyle.mark_as_thin_scroll(runs_area)

mark_as_title

mark_as_title(
    widget: QWidget, is_title: bool = True, rank: Optional[str] = None
) -> None

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

Without a rank only the family changes. A rank ("section", "card", or one the color file's fonts: ranks: adds) also sets the size and weight, from the stylesheet, so it holds inside a host too, where a font set in code loses to the host rules.

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

rank

Optional[str]

The heading's rank. Defaults to None, the family alone.

None

Raises:

Type Description
ValueError

If rank is not a rank of the current theme.

Examples:

>>> fxstyle.mark_as_title(heading, rank="section")

mark_compact

mark_compact(widget: QWidget, compact: bool = True) -> None

Make a button or a combo box the compact size: COMPACT_HEIGHT tall.

For a control in a row or a panel, as the web look's extra-small one: 24 px, small text, a 16 px icon. A push button, a tool button (a split one keeps its arrow's segment square) and a combo box, which then hugs its contents and draws a 16 px chevron, line up side by side. A round FXIconButton takes its own size argument instead.

Parameters:

Name Type Description Default

widget

QWidget

The QPushButton, QToolButton or QComboBox.

required

compact

bool

False gives it the control height back. Defaults to True.

True

Examples:

>>> fxstyle.mark_compact(reply_button)
>>> fxstyle.mark_compact(status_combo)

mark_dense

mark_dense(view: QWidget, dense: bool = True) -> None

Make a view's rows one row size under the one in force.

Small rows while the person's row height is normal, normal ones when it is big, and 24 px, a compact control's height, when it is small: each choice still reads as different.

Parameters:

Name Type Description Default

view

QWidget

A tree or list view.

required

dense

bool

False gives it the row height in force back.

True

Examples:

>>> fxstyle.mark_dense(browse_tree)

mark_flush

mark_flush(view: QWidget, flush: bool = True) -> None

Draw a view that fills its pane with no frame of its own.

The pane's edge is its frame, as the web look's tables and trees sit flush in their card; a small table inside a section keeps its frame. FXDockArea marks a pane whose body is a view itself. In an FXDockArea pane, a flush list, tree or table also runs to the pane's border on each side it reaches (its rows, header, column rules and summary row with it), while the pane's other content keeps its gap.

Parameters:

Name Type Description Default

view

QWidget

A list, tree, table or other scroll area.

required

flush

bool

False gives it its frame back.

True

Examples:

>>> fxstyle.mark_flush(browse_tree)

mix

mix(one_hex, two_hex, amount: float) -> str

Return the hex colour amount (0 to 1) of the way from one to two.

Either colour may be anything QColor reads, a QColor included.

mix_oklab

mix_oklab(one_hex, two_hex, amount: float) -> str

Return the hex colour amount of the way from one to two, in OKLab.

As CSS color-mix(in oklab, ...) mixes: even in lightness, so a little white in a dark grey lightens it as little as the eye expects.

Examples:

>>> fxstyle.mix_oklab("#101113", "#f7f8f8", 0.1)
'#222325'

motion

motion() -> bool

Whether animations play: not under REDUCED_MOTION_VAR.

overlay_color_file

overlay_color_file(color_file: str) -> None

Merge a colour file onto the loaded one, then re-apply the theme.

Nested mappings (themes, each theme, fonts) merge key by key, so the file needs only the keys it changes. A new theme takes every key it omits from the dark theme.

Parameters:

Name Type Description Default

color_file

str

Path to the YAML file holding the keys to change.

required

Examples:

>>> fxstyle.overlay_color_file("studio_colors.yaml")

palette

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

Build a QPalette from a theme's resolved colours.

Roles a binding lacks (Accent before Qt 6.6) are skipped.

Parameters:

Name Type Description Default

theme

Optional[str]

Theme name. Defaults to the current theme.

None

Returns:

Type Description
QPalette

The palette every themed root wears alongside the sheet.

qcolor

qcolor(value) -> QColor

Return a QColor for a theme token name, a colour or a QColor, now.

A token is read from the current theme, so a caller that keeps the name follows every switch. Anything QColor cannot read is an invalid QColor, which a paint can skip rather than raise.

Examples:

>>> fxstyle.qcolor("accent_primary")
>>> fxstyle.qcolor("#ff5722")

readable_ink

readable_ink(
    background: Union[str, QColor],
    preferred: Union[str, QColor, None] = None,
    floor: float = 4.5,
) -> str

Return an ink that reads on background at floor:1 or better.

Parameters:

Name Type Description Default

background

Union[str, QColor]

The color the ink is drawn on, anything QColor reads.

required

preferred

Union[str, QColor, None]

The ink to keep if it reads. Defaults to white.

None

floor

float

The minimum WCAG contrast ratio.

4.5

Returns:

Type Description
str

preferred when it reads, else the first color from it toward

str

black or white, whichever stands further from background, that

str

does. The pole itself when none does.

register_fonts

register_fonts(
    paths: Union[str, PathLike, Iterable[Union[str, PathLike]]],
) -> 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

Union[str, PathLike, Iterable[Union[str, PathLike]]]

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.

A widget is not registered while the QApplication is a root: the application's sheet already reaches it, and the next switch of that sheet would hand the widget back the palette of the theme before. It is still marked as a themed window, so it fades in as it shows, as in a host.

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; }
... ''')

resolve

resolve(qss: str, theme: Optional[str] = None) -> str

Replace every @token and ~icons placeholder in a stylesheet.

Parameters:

Name Type Description Default

qss

str

Stylesheet text containing placeholders.

required

theme

Optional[str]

Theme whose values to substitute. Defaults to the current.

None

Returns:

Type Description
str

The stylesheet with every known placeholder replaced.

Examples:

>>> fxstyle.resolve("QFrame { border-radius: @button_radius; }")

row_height

row_height(view: Optional[QWidget] = None) -> int

Return the height, in pixels, of a list or tree row.

Parameters:

Name Type Description Default

view

Optional[QWidget]

The view the row is in. A view marked dense (mark_dense) takes one row size under the one in force.

None

row_size

row_size() -> str

Return the ROW_SIZES name in force, the saved one on first access.

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

Replace the whole colour file, then re-apply the theme everywhere.

A file setting only a few keys belongs in overlay_color_file.

Parameters:

Name Type Description Default

color_file

str

Path to the YAML color configuration file.

required

Raises:

Type Description
OSError

If the file cannot be read; the loaded one stays.

YAMLError

If it is no YAML; the loaded one stays.

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(), save=False)

set_menu_badge

set_menu_badge(action: QAction, text: str) -> None

Show text as a pill at the right of action's menu item.

The pill stands in the key-hint column, so the item shows no shortcut text; the action keeps its shortcut.

Examples:

>>> fxstyle.set_menu_badge(delete_action, "Admin")

set_style

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

Give widget (or the application) FXProxyStyle over a Qt 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.

set_tab_count

set_tab_count(
    tabs: Union[QTabBar, QTabWidget], index: int, count: Optional[int]
) -> None

Show a count after a tab's label, as a small ringed badge.

Works on a plain or a segmented bar. A screen reader reads the tab as "Label, N". On a closable bar whose close buttons stand on the right, the count stands before the label. Call it again after renaming the tab, so the name read follows.

Parameters:

Name Type Description Default

tabs

Union[QTabBar, QTabWidget]

The QTabBar, or the QTabWidget whose bar to count on.

required

index

int

The tab's index.

required

count

Optional[int]

The number to show; None removes the badge.

required

Raises:

Type Description
IndexError

If the bar has no tab index.

Examples:

>>> fxstyle.set_tab_count(views, 0, 26)
>>> fxstyle.set_tab_count(views, 0, None)

state_contrast

state_contrast(theme_name: Optional[str] = None) -> float

Return the least contrast a theme holds its hover and pressed fills to.

STATE_MIN_CONTRAST unless the theme's state_contrast says less, as a brand's own fills may.

step_toward

step_toward(start: str, toward: str, done: Callable[[str], bool]) -> str

Return the first hex colour from start to toward that is done.

Parameters:

Name Type Description Default

start

str

The colour to begin at, tried first.

required

toward

str

The colour to move to, in 40 steps.

required

done

Callable[[str], bool]

Takes a hex colour; True stops the walk there.

required

Returns:

Type Description
str

The first colour done accepts, else toward itself.

Examples:

>>> fxstyle.step_toward("#202020", "#ffffff",
...     lambda c: fxstyle.get_contrast_ratio(c, "#202020") >= 4.5)

unregister_themed_root

unregister_themed_root(root: QObject) -> None

Forget root: later theme switches no longer restyle it.

Restores nothing: root keeps the sheet, palette and font it wears until you set others. Forgetting a root never registered does nothing.

Parameters:

Name Type Description Default

root

QObject

A widget or QApplication given to register_themed_root.

required