Alto
latest

alto.ui.theme

The colour theme: follow the system, force light or dark, or use a theme with colours of its own.

A theme with colours of its own is a CustomTheme: a fixed palette that is light or dark whatever the desktop is set to.

Examples

>>> [key for key, label in THEMES][:4]
['system', 'light', 'dark', 'studio']

CustomTheme

CustomTheme(
    key: str,
    family: str,
    label: str,
    note: str,
    dark: bool,
    window: str,
    panel: str,
    ink: str,
    muted: str,
    line: str,
    accent: str,
    track: str,
)

A theme with colours of its own.

Attributes

  • key (str): What it is saved as.
  • family (str): The key of the light version of the theme, which its dark version shares.
  • label (str): What the settings call it.
  • note (str): A short line about it, shown under its picture.
  • dark (bool): True if it is a dark theme, so that Qt draws its own parts (such as the title bar) to match.
  • window (str): The colour of the window.
  • panel (str): The colour of lists, boxes and buttons.
  • ink (str): The colour of text.
  • muted (str): The colour of quiet text.
  • line (str): The colour of outlines.
  • accent (str): The colour of what is chosen, and of links.
  • track (str): The colour of the track behind a switch or a slider, a little off the window’s own.

Examples

>>> CUSTOM_THEMES[0].key, CUSTOM_THEMES[0].dark, len(CUSTOM_THEMES)
('studio', False, 50)

hsl_hex

def hsl_hex(
    hue: float,
    *,
    saturation: float,
    lightness: float,
) -> str

Turn a colour given as hue, saturation and lightness into “#rrggbb”.

Parameters

  • hue (float): The hue, in degrees.
  • saturation (float): The saturation, from 0 to 100. Keyword-only.
  • lightness (float): The lightness, from 0 to 100. Keyword-only.

Returns

  • str: The colour in hexadecimal.

Examples

>>> hsl_hex(0, saturation=100, lightness=50), hsl_hex(210, saturation=0, lightness=100)
('#ff0000', '#ffffff')

seeded_themes

def seeded_themes(seed: tuple[str, str, str, float, float, float, float]) -> tuple[CustomTheme, CustomTheme]

Make the light and the dark theme of a seed: neutrals tinted by one hue, and an accent of another.

Parameters

  • seed (tuple): The key, name and note, then the neutral hue and saturation and the accent hue and saturation.

Returns

  • tuple of (CustomTheme, CustomTheme): The light theme and the dark theme.

Examples

>>> pale, deep = seeded_themes(SEEDS[0])
>>> pale.key, deep.key, pale.dark, deep.dark
('parchment', 'parchment_dark', False, True)

family_of

def family_of(key: str) -> tuple[str, str]

Split a theme’s key into its family and which version of it that is.

Parameters

  • key (str): The key of any theme.

Returns

  • tuple of (str, str): The family’s key and “light”, “dark” or “system”. “system”, “light” and “dark” belong to the family “default”.

Examples

>>> family_of("sage_dark"), family_of("sage"), family_of("sage_auto"), family_of("dark"), family_of("system")
(('sage', 'dark'), ('sage', 'light'), ('sage', 'system'), ('default', 'dark'), ('default', 'system'))

variant_key

def variant_key(
    family: str,
    *,
    version: str,
) -> str

Give the key of one version of a family.

Parameters

  • family (str): The family’s key.
  • version (str): “light”, “dark” or “system”. Keyword-only.

Returns

  • str: The key.

Examples

>>> variant_key("sage", version="dark"), variant_key("sage", version="system"), variant_key("default", version="dark")
('sage_dark', 'sage_auto', 'dark')

ThemeRecord

class ThemeRecord(TypedDict)

A theme the user made, as it is saved: its key, its name, and the colours of its light and dark versions.

Examples

>>> ThemeRecord(id="my_1", name="Mine", light={}, dark={})["name"]
'Mine'

user_records

def user_records() -> list[ThemeRecord]

Read the themes the user has made, as they are saved.

Returns

  • list of ThemeRecord: One record for each theme: its “id”, its “name”, and its “light” and “dark” colours. A saved list that cannot be read, or has something else in it, gives only the records that can be used.

Examples

>>> store().remove("ui/userThemes")
>>> user_records()
[]

save_user_records

def save_user_records(records: list[ThemeRecord]) -> None

Save the themes the user has made.

Parameters

  • records (list of ThemeRecord): The records, as user_records gives them.

Examples

>>> save_user_records([])
>>> user_records()
[]

new_family_id

def new_family_id() -> str

Make the key for a new theme of the user’s.

Returns

  • str: A key that starts with “my_” and is not one that is in use.

Examples

>>> new_family_id().startswith("my_")
True

upsert_user_theme

def upsert_user_theme(record: ThemeRecord) -> None

Save a theme the user made, replacing the one with the same key if there is one.

Parameters

  • record (ThemeRecord): The theme.

Examples

>>> store().remove("ui/userThemes")
>>> colours = {part: "#112233" for part in PARTS}
>>> upsert_user_theme(ThemeRecord(id="my_a", name="Mine", light=colours, dark=colours))
>>> upsert_user_theme(ThemeRecord(id="my_a", name="Renamed", light=colours, dark=colours))
>>> [(r["id"], r["name"]) for r in user_records()]
[('my_a', 'Renamed')]
>>> store().remove("ui/userThemes")

delete_user_theme

def delete_user_theme(family: str) -> None

Remove a theme the user made.

Parameters

  • family (str): The theme’s key.

Examples

>>> store().remove("ui/userThemes")
>>> colours = {part: "#112233" for part in PARTS}
>>> upsert_user_theme(ThemeRecord(id="my_a", name="Mine", light=colours, dark=colours))
>>> delete_user_theme("my_a")
>>> user_records()
[]

user_themes

def user_themes() -> tuple[CustomTheme, ...]

Give the themes the user has made, light and dark versions of each.

Returns

  • tuple of CustomTheme: The light theme and then the dark theme of each record.

Examples

>>> store().remove("ui/userThemes")
>>> user_themes()
()

families

def families() -> tuple[tuple[str, str, str], ...]

List every theme there is to choose, the user’s own first.

Returns

  • tuple of tuple of (str, str, str): The key of each theme’s family, its name and a line about it.

Examples

>>> store().remove("ui/userThemes")
>>> families() == FAMILIES
True

custom_theme

def custom_theme(key: str) -> CustomTheme | None

Find a theme with colours of its own, one of the built-in ones or one the user made.

Parameters

  • key (str): The theme’s key.

Returns

  • CustomTheme or None: The theme, or None for “system”, “light”, “dark” or anything that is not one.

Examples

>>> custom_theme("studio_dark") is CUSTOM_THEMES[1], custom_theme("dark")
(True, None)

scheme_of

def scheme_of(key: str) -> Qt.ColorScheme | None

Say which colour scheme a theme uses: light, dark, or the desktop’s own.

Parameters

  • key (str): The theme’s key.

Returns

  • Qt.ColorScheme or None: The scheme; None if there is no theme with that key.

Examples

>>> scheme_of("dark") == Qt.ColorScheme.Dark, scheme_of("sage_auto") == Qt.ColorScheme.Unknown, scheme_of("nonsense")
(True, True, None)

preview_colours

def preview_colours(theme: CustomTheme) -> dict[str, str]

Pick the colours for the small picture of a theme in the settings.

Parameters

  • theme (CustomTheme): The theme.

Returns

  • dict of str to str: The window, panel, outline, text, faint and chosen colours, and a tint for the chosen row.

Examples

>>> preview_colours(CUSTOM_THEMES[0])["window"], sorted(preview_colours(CUSTOM_THEMES[0]))[:3]
('#eceef1', ['accent', 'faint', 'ink'])

theme_palette

def theme_palette(theme: CustomTheme) -> QPalette

Build the Qt palette of a theme with colours of its own.

Parameters

  • theme (CustomTheme): The theme.

Returns

  • QPalette: The palette: the window, lists and buttons, text, the chosen row and links in the theme’s colours, with quiet text for what is switched off.

Examples

>>> colours = theme_palette(CUSTOM_THEMES[0])
>>> colours.color(QPalette.ColorRole.Window).name(), colours.color(QPalette.ColorRole.Highlight).name()
('#eceef1', '#2f7fc1')

saved_theme

def saved_theme() -> str

Return the theme the user chose.

Returns

  • str: The key of the theme: “system”, “light”, “dark” or one of the themes with colours of its own; “system” if nothing valid is saved.

Examples

>>> save_theme("dark")
>>> saved_theme()
'dark'
>>> save_theme("system")

save_theme

def save_theme(key: str) -> None

Remember the theme the user chose.

Parameters

  • key (str): “system”, “light”, “dark” or the key of a theme with colours of its own.

Examples

>>> save_theme("light")
>>> saved_theme()
'light'
>>> save_theme("system")

system_is_dark

def system_is_dark() -> bool

Say whether the desktop is set to dark, as long as the app is not forcing a colour scheme of its own.

A theme that follows the desktop does not force one, so this is what it asks.

Returns

  • bool: True if the colour scheme in use is dark.

Examples

>>> system_is_dark() in {True, False}
True

apply_theme

def apply_theme(key: str) -> None

Switch the application’s colour scheme and rebuild the stylesheet from the new palette.

Parameters

  • key (str): “system” to follow the desktop, “light” or “dark”, or the key of a theme with colours of its own. Anything else follows the system.

Examples

>>> apply_theme("system")
>>> # noinspection PyUnresolvedReferences
>>> app.styleSheet() != ""
True
>>> apply_theme("studio")
>>> QApplication.palette().color(QPalette.ColorRole.Window).name()
'#eceef1'
>>> apply_theme("system")
>>> QApplication.palette().color(QPalette.ColorRole.Window).name() != "#eceef1"
True