pythonnative/src/pythonnative/appearance.py at main · pythonnative/pythonnative · GitHub

History

127 lines (98 loc) · 3.89 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

"""System color-scheme (light / dark mode) tracking.

The platform screen host publishes the operating system's current

appearance here (Android: ``Configuration.uiMode``; iOS:

``UITraitCollection.userInterfaceStyle``), and components read it back

through [`use_color_scheme`][pythonnative.use_color_scheme] or

[`use_theme`][pythonnative.use_theme], both of which re-render when

the scheme changes.

Apps can also *override* the scheme (e.g. an in-app appearance

setting) with [`set_color_scheme`][pythonnative.appearance.set_color_scheme];

the override wins over the system value until cleared with ``None``.

Example:

>>> from pythonnative import appearance

>>> appearance.get_color_scheme()

'light'

>>> appearance.set_color_scheme("dark") # app-level override

>>> appearance.get_color_scheme()

'dark'

>>> appearance.set_color_scheme(None) # follow the system again

"""

from __future__ import annotations

import threading

from typing import Callable, List, Literal, Optional

ColorScheme = Literal["light", "dark"]

"""The two supported appearance values."""

_system_scheme: str = "light"

_override_scheme: Optional[str] = None

_subscribers: List[Callable[[], None]] = []

_subscribers_lock = threading.Lock()

def _notify_subscribers() -> None:

"""Invoke every registered subscriber, swallowing exceptions."""

with _subscribers_lock:

callbacks = list(_subscribers)

for cb in callbacks:

try:

cb()

except Exception:

pass

def subscribe(callback: Callable[[], None]) -> Callable[[], None]:

"""Register ``callback`` to fire whenever the effective scheme changes.

Returns an unsubscribe function. Threadsafe.

"""

with _subscribers_lock:

_subscribers.append(callback)

def _unsub() -> None:

with _subscribers_lock:

try:

_subscribers.remove(callback)

except ValueError:

pass

return _unsub

def _coerce(scheme: object) -> Optional[str]:

if scheme in ("light", "dark"):

return str(scheme)

return None

def set_system_color_scheme(scheme: str) -> None:

"""Publish the operating system's current scheme.

Called by the platform screen host on create/resume and whenever

the system reports an appearance change. Invalid values are

ignored. Subscribers are only notified when the *effective* scheme

(after any app override) actually changes.

"""

global _system_scheme

coerced = _coerce(scheme)

if coerced is None or coerced == _system_scheme:

return

effective_before = get_color_scheme()

_system_scheme = coerced

if get_color_scheme() != effective_before:

_notify_subscribers()

def set_color_scheme(scheme: Optional[str]) -> None:

"""Set (or clear) the app-level scheme override.

Args:

scheme: ``"light"`` or ``"dark"`` to force that appearance

regardless of the system setting, or ``None`` to follow

the system again.

"""

global _override_scheme

coerced = _coerce(scheme) if scheme is not None else None

if scheme is not None and coerced is None:

return

effective_before = get_color_scheme()

_override_scheme = coerced

if get_color_scheme() != effective_before:

_notify_subscribers()

def get_color_scheme() -> str:

"""Return the effective scheme: the app override if set, else the system value."""

return _override_scheme if _override_scheme is not None else _system_scheme

def get_system_color_scheme() -> str:

"""Return the system-reported scheme, ignoring any app override."""

return _system_scheme

def reset_color_scheme() -> None:

"""Reset to system ``"light"`` with no override. Intended for tests."""

global _system_scheme, _override_scheme

changed = get_color_scheme() != "light"

_system_scheme = "light"

_override_scheme = None

if changed:

_notify_subscribers()

pythonnative/src/pythonnative/appearance.py at main · pythonnative/pythonnative · GitHub

Expand file tree

Breadcrumbs

appearance.py

Latest commit

History

Breadcrumbs

appearance.py

File metadata and controls