Theming System API

Professional theming system for ThreePaneWindows.

This module provides comprehensive theming capabilities including color schemes, typography, spacing, and platform-specific theme detection and management.

class threepanewindows.themes.ColorScheme(primary_bg='#ffffff', secondary_bg='#f5f5f5', accent_bg='#e3f2fd', primary_text='#212121', secondary_text='#757575', accent_text='#1976d2', border='#e0e0e0', separator='#bdbdbd', button_bg='#2196f3', button_fg='#ffffff', button_hover='#1976d2', button_active='#0d47a1', success='#4caf50', warning='#ff9800', error='#f44336', info='#2196f3', panel_header_bg='#fafafa', panel_header_fg='#424242', panel_content_bg='#ffffff', drag_indicator='#2196f3', drop_zone='#e3f2fd')[source]

Bases: object

Color scheme configuration for themes.

Parameters:

  • primary_bg (str)

  • secondary_bg (str)

  • accent_bg (str)

  • primary_text (str)

  • secondary_text (str)

  • accent_text (str)

  • border (str)

  • separator (str)

  • button_bg (str)

  • button_fg (str)

  • button_hover (str)

  • button_active (str)

  • success (str)

  • warning (str)

  • error (str)

  • info (str)

  • panel_header_bg (str)

  • panel_header_fg (str)

  • panel_content_bg (str)

  • drag_indicator (str)

  • drop_zone (str)

accent_bg: str = '#e3f2fd'
accent_text: str = '#1976d2'
border: str = '#e0e0e0'
button_active: str = '#0d47a1'
button_bg: str = '#2196f3'
button_fg: str = '#ffffff'
button_hover: str = '#1976d2'
drag_indicator: str = '#2196f3'
drop_zone: str = '#e3f2fd'
error: str = '#f44336'
info: str = '#2196f3'
panel_content_bg: str = '#ffffff'
panel_header_bg: str = '#fafafa'
panel_header_fg: str = '#424242'
primary_bg: str = '#ffffff'
primary_text: str = '#212121'
secondary_bg: str = '#f5f5f5'
secondary_text: str = '#757575'
separator: str = '#bdbdbd'
success: str = '#4caf50'
warning: str = '#ff9800'
class threepanewindows.themes.Spacing(padding_small=4, padding_normal=8, padding_large=16, margin_small=2, margin_normal=4, margin_large=8, border_width=1, separator_width=1)[source]

Bases: object

Spacing configuration for themes.

Parameters:

  • padding_small (int)

  • padding_normal (int)

  • padding_large (int)

  • margin_small (int)

  • margin_normal (int)

  • margin_large (int)

  • border_width (int)

  • separator_width (int)

border_width: int = 1
margin_large: int = 8
margin_normal: int = 4
margin_small: int = 2
padding_large: int = 16
padding_normal: int = 8
padding_small: int = 4
separator_width: int = 1
class threepanewindows.themes.Theme(name, colors=<factory>, typography=<factory>, spacing=<factory>, animation_duration=200, enable_animations=True, enable_shadows=True, enable_gradients=False, corner_radius=4)[source]

Bases: object

Complete theme configuration including colors, typography, and spacing.

Parameters:
animation_duration: int = 200
colors: ColorScheme
corner_radius: int = 4
enable_animations: bool = True
enable_gradients: bool = False
enable_shadows: bool = True
name: str
spacing: Spacing
typography: Typography
class threepanewindows.themes.ThemeManager(theme=None, custom_scheme=None)[source]

Bases: object

Manages theme application and platform-specific theme detection.

Initialize theme manager with optional theme and custom color scheme.

Parameters:
apply_theme_to_widget(widget, recursive=True)[source]

Apply current theme to a widget and optionally its children.

Parameters:

  • widget – The widget to theme

  • recursive (bool) – Whether to theme child widgets as well

Return type:

None

apply_theme_to_window(window)[source]

Apply current theme to an entire window and all its widgets.

Parameters:

window – The root window or toplevel to theme

Return type:

None

apply_ttk_theme(style)[source]

Apply current theme to ttk widgets.

Parameters:

style (Style)

Return type:

None

create_themed_scrollbar_auto(parent, orient='vertical', command=None, **kwargs)

Create a scrollbar with automatic platform-specific type selection.

Parameters:

  • parent (Widget) – Parent widget

  • orient (str) – Scrollbar orientation (“vertical” or “horizontal”)

  • command (Callable | None) – Scroll command callback

  • **kwargs (Any) – Additional arguments passed to scrollbar creation

Returns:

Scrollbar widget (custom or native based on platform)

Return type:

ThemedScrollbar | Scrollbar

property current_scheme: ColorScheme

Get the current color scheme (alias for current theme colors).

property current_theme: ThemeType

Get the current theme as a ThemeType enum.

get_available_theme_types()[source]

Get list of available theme types as enums.

Return type:

List[ThemeType]

get_available_themes()[source]

Get list of available theme names.

Return type:

List[str]

get_color(color_name)[source]

Get a color value from the current theme.

Parameters:

color_name (str)

Return type:

str | None

get_current_theme()[source]

Get the currently active theme.

Return type:

Theme

get_platform_info()[source]

Get platform information for display purposes.

Returns:

Dict containing platform name and recommended scrollbar type

Return type:

Dict[str, str]

get_style(component, state='normal')[source]

Get styling for a component in a specific state.

Parameters:
Return type:

Dict[str, Any]

get_theme(name)[source]

Get a theme by name or type.

Parameters:

name (str | ThemeType)

Return type:

Theme | None

get_tk_widget_style(widget_type, state='normal')[source]

Get styling for custom Tkinter widgets.

Parameters:

  • widget_type (str)

  • state (str)

Return type:

Dict[str, Any]

is_native_theme_available()[source]

Check if native themes are available on this platform.

Return type:

bool

list_themes()

Get dictionary of theme names and their display names.

Return type:

Dict[str, str]

refresh_system_theme()[source]

Refresh system and native themes to match current OS settings.

Returns:

True if themes were updated successfully

Return type:

bool

register_theme(theme)[source]

Register a new theme.

Parameters:

theme (Theme)

Return type:

None

set_theme(name, custom_scheme=None, window=None)[source]

Set the active theme by name or type.

Parameters:
Return type:

bool

should_use_custom_scrollbars()

Determine whether to use custom scrollbars based on platform.

Returns:

True if custom scrollbars should be used, False for native scrollbars

Return type:

bool

Platform-specific behavior: - Windows: Custom scrollbars (better theming support) - macOS/Linux: Native scrollbars (better system integration)

class threepanewindows.themes.ThemeType(value)[source]

Bases: Enum

Enumeration of available theme types.

BLUE = 'blue'
CUSTOM = 'custom'
DARK = 'dark'
GREEN = 'green'
LIGHT = 'light'
NATIVE = 'native'
NATIVE_DARK = 'native_dark'
NATIVE_LIGHT = 'native_light'
PURPLE = 'purple'
SYSTEM = 'system'
class threepanewindows.themes.Typography(font_family='Segoe UI', font_family_fallback='Arial', font_size_small=9, font_size_normal=10, font_size_large=12, font_size_title=14, font_weight_light='normal', font_weight_normal='normal', font_weight_medium='bold', font_weight_bold='bold')[source]

Bases: object

Typography configuration for themes.

Parameters:

  • font_family (str)

  • font_family_fallback (str)

  • font_size_small (int)

  • font_size_normal (int)

  • font_size_large (int)

  • font_size_title (int)

  • font_weight_light (str)

  • font_weight_normal (str)

  • font_weight_medium (str)

  • font_weight_bold (str)

font_family: str = 'Segoe UI'
font_family_fallback: str = 'Arial'
font_size_large: int = 12
font_size_normal: int = 10
font_size_small: int = 9
font_size_title: int = 14
font_weight_bold: str = 'bold'
font_weight_light: str = 'normal'
font_weight_medium: str = 'bold'
font_weight_normal: str = 'normal'
threepanewindows.themes.get_theme_manager()[source]

Get the global theme manager instance.

Return type:

ThemeManager

threepanewindows.themes.set_global_theme(theme, custom_scheme=None, window=None)[source]

Set the global theme for all ThreePaneWindows components.

Parameters:
Return type:

bool

ThemeManager

class threepanewindows.ThemeManager(theme=None, custom_scheme=None)[source]

Bases: object

Manages theme application and platform-specific theme detection.

Initialize theme manager with optional theme and custom color scheme.

Parameters:
apply_theme_to_widget(widget, recursive=True)[source]

Apply current theme to a widget and optionally its children.

Parameters:

  • widget – The widget to theme

  • recursive (bool) – Whether to theme child widgets as well

Return type:

None

apply_theme_to_window(window)[source]

Apply current theme to an entire window and all its widgets.

Parameters:

window – The root window or toplevel to theme

Return type:

None

apply_ttk_theme(style)[source]

Apply current theme to ttk widgets.

Parameters:

style (Style)

Return type:

None

create_themed_scrollbar_auto(parent, orient='vertical', command=None, **kwargs)

Create a scrollbar with automatic platform-specific type selection.

Parameters:

  • parent (Widget) – Parent widget

  • orient (str) – Scrollbar orientation (“vertical” or “horizontal”)

  • command (Callable | None) – Scroll command callback

  • **kwargs (Any) – Additional arguments passed to scrollbar creation

Returns:

Scrollbar widget (custom or native based on platform)

Return type:

ThemedScrollbar | Scrollbar

property current_scheme: ColorScheme

Get the current color scheme (alias for current theme colors).

property current_theme: ThemeType

Get the current theme as a ThemeType enum.

get_available_theme_types()[source]

Get list of available theme types as enums.

Return type:

List[ThemeType]

get_available_themes()[source]

Get list of available theme names.

Return type:

List[str]

get_color(color_name)[source]

Get a color value from the current theme.

Parameters:

color_name (str)

Return type:

str | None

get_current_theme()[source]

Get the currently active theme.

Return type:

Theme

get_platform_info()[source]

Get platform information for display purposes.

Returns:

Dict containing platform name and recommended scrollbar type

Return type:

Dict[str, str]

get_style(component, state='normal')[source]

Get styling for a component in a specific state.

Parameters:
Return type:

Dict[str, Any]

get_theme(name)[source]

Get a theme by name or type.

Parameters:

name (str | ThemeType)

Return type:

Theme | None

get_tk_widget_style(widget_type, state='normal')[source]

Get styling for custom Tkinter widgets.

Parameters:

  • widget_type (str)

  • state (str)

Return type:

Dict[str, Any]

is_native_theme_available()[source]

Check if native themes are available on this platform.

Return type:

bool

list_themes()

Get dictionary of theme names and their display names.

Return type:

Dict[str, str]

refresh_system_theme()[source]

Refresh system and native themes to match current OS settings.

Returns:

True if themes were updated successfully

Return type:

bool

register_theme(theme)[source]

Register a new theme.

Parameters:

theme (Theme)

Return type:

None

set_theme(name, custom_scheme=None, window=None)[source]

Set the active theme by name or type.

Parameters:
Return type:

bool

should_use_custom_scrollbars()

Determine whether to use custom scrollbars based on platform.

Returns:

True if custom scrollbars should be used, False for native scrollbars

Return type:

bool

Platform-specific behavior: - Windows: Custom scrollbars (better theming support) - macOS/Linux: Native scrollbars (better system integration)

Theme Classes

class threepanewindows.themes.Theme(name, colors=<factory>, typography=<factory>, spacing=<factory>, animation_duration=200, enable_animations=True, enable_shadows=True, enable_gradients=False, corner_radius=4)[source]

Bases: object

Complete theme configuration including colors, typography, and spacing.

Parameters:
animation_duration: int = 200
colors: ColorScheme
corner_radius: int = 4
enable_animations: bool = True
enable_gradients: bool = False
enable_shadows: bool = True
name: str
spacing: Spacing
typography: Typography
class threepanewindows.themes.ColorScheme(primary_bg='#ffffff', secondary_bg='#f5f5f5', accent_bg='#e3f2fd', primary_text='#212121', secondary_text='#757575', accent_text='#1976d2', border='#e0e0e0', separator='#bdbdbd', button_bg='#2196f3', button_fg='#ffffff', button_hover='#1976d2', button_active='#0d47a1', success='#4caf50', warning='#ff9800', error='#f44336', info='#2196f3', panel_header_bg='#fafafa', panel_header_fg='#424242', panel_content_bg='#ffffff', drag_indicator='#2196f3', drop_zone='#e3f2fd')[source]

Bases: object

Color scheme configuration for themes.

Parameters:

  • primary_bg (str)

  • secondary_bg (str)

  • accent_bg (str)

  • primary_text (str)

  • secondary_text (str)

  • accent_text (str)

  • border (str)

  • separator (str)

  • button_bg (str)

  • button_fg (str)

  • button_hover (str)

  • button_active (str)

  • success (str)

  • warning (str)

  • error (str)

  • info (str)

  • panel_header_bg (str)

  • panel_header_fg (str)

  • panel_content_bg (str)

  • drag_indicator (str)

  • drop_zone (str)

accent_bg: str = '#e3f2fd'
accent_text: str = '#1976d2'
border: str = '#e0e0e0'
button_active: str = '#0d47a1'
button_bg: str = '#2196f3'
button_fg: str = '#ffffff'
button_hover: str = '#1976d2'
drag_indicator: str = '#2196f3'
drop_zone: str = '#e3f2fd'
error: str = '#f44336'
info: str = '#2196f3'
panel_content_bg: str = '#ffffff'
panel_header_bg: str = '#fafafa'
panel_header_fg: str = '#424242'
primary_bg: str = '#ffffff'
primary_text: str = '#212121'
secondary_bg: str = '#f5f5f5'
secondary_text: str = '#757575'
separator: str = '#bdbdbd'
success: str = '#4caf50'
warning: str = '#ff9800'

Functions

threepanewindows.get_theme_manager()[source]

Get the global theme manager instance.

Return type:

ThemeManager

threepanewindows.set_global_theme(theme, custom_scheme=None, window=None)[source]

Set the global theme for all ThreePaneWindows components.

Parameters:
Return type:

bool