Theme Manager

morphui.theme.manager

Dynamic color management system for MorphUI

This module provides a dynamic color system that automatically updates all widget colors when switching between light and dark themes.

ThemeManager(**kwargs)

Bases: MorphDynamicColorPalette

Manage the theme and dynamic colors for the application.

This class handles the overall theme management, including switching between light and dark modes. It automatically updates colors for all widgets that have auto_theme enabled.

auto_theme = BooleanProperty(True) class-attribute instance-attribute

Enable automatic theme updates across all widgets.

When True, widgets automatically update their colors when the theme changes. When False, widgets retain their current colors until manually updated.

:attr:auto_theme is a :class:~kivy.properties.BooleanProperty and defaults to True.

seed_color = StringProperty('Blue') class-attribute instance-attribute

The seed color used to generate the dynamic color palette.

This property sets the source color from which all other theme colors are generated using the Material You color system. Changing this property will regenerate the entire color palette and automatically update all widgets that have auto_theme enabled.

:attr:seed_color is a :class:~kivy.properties.OptionProperty and defaults to 'Blue'.

color_scheme = OptionProperty('VIBRANT', options=(THEME.SCHEMES)) class-attribute instance-attribute

The color scheme used for generating dynamic colors.

This property determines the algorithm used to generate colors based on the primary color. Available shemes are defined in :obj:morphui.constants.THEME.SCHEMES.

:attr:color_scheme is a :class:~kivy.properties.OptionProperty and defaults to 'VIBRANT'.

color_scheme_contrast = BoundedNumericProperty(0.0, min=0.0, max=1.0, errorhandler=(lambda x: max(0.0, min(x, 1.0)))) class-attribute instance-attribute

Adjusts the contrast level of the selected color scheme.

This property modifies the contrast of the generated color scheme. A value of 0 means no adjustment, while 1 applies the maximum contrast enhancement.

:attr:color_scheme_contrast is a :class:~kivy.properties.BoundedNumericProperty and defaults to 0.

color_quality = BoundedNumericProperty(1, min=1, errorvalue=1) class-attribute instance-attribute

The quality level for color generation.

Must be an integer and higher or equal to 1. Where 1 is the maximum quality and higher numbers reduce the quality for performance.

:attr:color_quality is a :class:~kivy.properties.NumericProperty and defaults to 1.

theme_mode = OptionProperty(THEME.LIGHT, options=[THEME.LIGHT, THEME.DARK]) class-attribute instance-attribute

The overall theme mode, either 'Light' or 'Dark'.

This property determines the base colors for surfaces, text, and other UI elements. Changing this property will automatically update all widgets that have auto_theme enabled.

:attr:theme_mode is a :class:~kivy.properties.OptionProperty and defaults to THEME.LIGHT.

is_dark_mode = AliasProperty(lambda self: self.theme_mode == THEME.DARK, None, bind=['theme_mode']) class-attribute instance-attribute

Read-only property that indicates if the current theme mode is dark.

This property is automatically updated based on the value of theme_mode. It can be used in widget logic to conditionally adjust styles or behaviors based on whether the app is in light or dark mode.

:attr:is_dark_mode is an :class:~kivy.properties.AliasProperty and is read-only.

mode_animation = BooleanProperty(True) class-attribute instance-attribute

Enable smooth transitions when switching between theme modes.

When True, theme mode changes (light/dark) will be animated with smooth color transitions. When False, theme changes happen instantly.

:attr:mode_animation is a :class:~kivy.properties.BooleanProperty and defaults to True.

mode_animation_duration = BoundedNumericProperty(0.3, min=0.0) class-attribute instance-attribute

Duration of theme mode transition animations in seconds.

This property controls how long the transition animation takes when switching between light and dark modes. Only applies when :attr:mode_animation is True.

:attr:mode_animation_duration is a :class:~kivy.properties.BoundedNumericProperty and defaults to 0.15.

mode_animation_transition = StringProperty('out_sine') class-attribute instance-attribute

Transition type for theme mode animations.

This property defines the type of transition used for animating the switch between light and dark modes. Only applies when mode_animation is True. For a list of supported transitions, refer to the Kivy documentation

:attr:mode_animation_transition is a :class:~kivy.properties.StringProperty and defaults to 'out_sine'.

available_seed_colors = AliasProperty(lambda self: self._get_available_seed_colors(), bind=['hex_colormap', '_colormap_version'], cache=True) class-attribute instance-attribute

List of available seed colors (read-only).

:attr:available_seed_colors is an :class:~kivy.properties.AliasProperty.

hex_colormap = DictProperty(hex_colormap.copy()) class-attribute instance-attribute

Instance-level hex colormap for storing registered seed colors.

This property allows for dynamic registration of new seed colors at runtime. It is initialized with a copy of Kivy's default hex colormap. When a new seed color is registered using register_seed_color(), it is added to this dictionary.

:attr:hex_colormap is a :class:~kivy.properties.DictProperty and defaults to a copy of Kivy's default hex colormap.

colormap property

RGBA colormap derived from hex_colormap (read-only).

Returns a dictionary mapping color names to RGBA values.

inverse_mode property

Get the inverse theme mode (read-only).

Returns the opposite of the current theme_mode. If current mode is 'Light', returns 'Dark', and vice versa.

cached_theme property

Get the currently cached theme (read-only).

Returns the cached theme object containing both light and dark schemes, or None if no theme is cached. This is useful for debugging and understanding the internal state.

RETURNS	DESCRIPTION
Theme | None	The cached theme object or None if not cached.

light_scheme property

Get the light scheme from cached theme.

dark_scheme property

Get the dark scheme from cached theme.

current_scheme property

Get the current scheme based on theme mode.

toggle_theme_mode(*args)

Toggle between light and dark theme modes.

Switches the current theme_mode to its inverse. If currently 'Light', switches to 'Dark', and vice versa. The transition will be animated if mode_animation is enabled.

Examples:

# Simple toggle
theme_manager.toggle_theme_mode()

# Toggle with custom animation settings
theme_manager.mode_animation = True
theme_manager.mode_animation_duration = 0.5
theme_manager.toggle_theme_mode()

switch_to_light(*args)

Switch to light theme mode.

Sets the theme_mode to 'Light'. If already in light mode, this method has no effect. The transition will be animated if mode_animation is enabled.

switch_to_dark(*args)

Switch to dark theme mode.

Sets the theme_mode to 'Dark'. If already in dark mode, this method has no effect. The transition will be animated if mode_animation is enabled.

register_seed_color(color_name, hex_value)

Register a new seed color.

This method allows adding custom seed colors to the theme. The color name must be a valid hex color code (e.g. '#FF5733').

PARAMETER	DESCRIPTION
color_name	The name of the new seed color. TYPE: str
hex_value	The hex color code for the new seed color. TYPE: str

Examples:

theme_manager.register_seed_color('MyCyan', '#00F0D0')
theme_manager.seed_color = 'MyCyan'

on_seed_color(instance, seed_color)

Event handler for when the seed color changes.

This method is automatically called whenever the seed_color property is updated. It is bound to the on_theme_changed event which regenerates the color scheme and updates all dynamic colors accordingly.

PARAMETER	DESCRIPTION
instance	The instance that triggered the event (usually self). TYPE: Any
seed_color	The new seed color value. TYPE: str

refresh_theme_colors()

Manually refresh and apply the current theme colors.

This method can be called to force a refresh of all dynamic colors based on the current theme settings. It is useful when multiple properties have been changed and you want to apply the changes immediately.

Examples:

theme_manager.seed_color = 'Red'
theme_manager.color_scheme = 'VIBRANT'
theme_manager.refresh_theme_colors()  # Manual refresh

on_theme_changed(*args)

Handle theme changes and update all colors based on current settings.

This method is automatically called whenever theme properties change (seed_color, color_scheme, theme_mode, etc.) and forces an update of all dynamic colors. It can also be called manually when multiple properties have been changed and you want to apply the changes immediately.

Examples:

theme_manager.seed_color = 'Red'
theme_manager.color_scheme = 'VIBRANT'
theme_manager.on_theme_changed()  # Manual trigger if needed

on_colors_updated(*args)

Event fired after color properties have been applied.

This is a more specific event than on_theme_changed that fires specifically when color values have been calculated and set on the theme manager. Use this event when you only need to respond to color changes, not other potential theme changes.

Note: This event only fires when auto_theme is True.

Examples:

def update_widget_colors(self):
    self.surface_color = theme_manager.background_color
    self.content_color = theme_manager.content_background_color

theme_manager.bind(on_colors_updated=update_widget_colors)