Style
ttkbootstrap.style.Style (Style)
A singleton class for creating and managing the application theme and widget styles.
This class is meant to be a drop-in replacement for ttk.Style
and
inherits all of it's methods and properties. However, in
ttkbootstrap, this class is implemented as a singleton. Subclassing
is not recommended and may have unintended consequences.
Examples:
# instantiate the style with default theme
style = Style()
# instantiate the style with another theme
style = Style(theme='superhero')
# check all available themes
for theme in style.theme_names():
print(theme)
See the Python documentation on this class for more details.
colors
property
readonly
An object that contains the colors used for the current theme.
Returns:
Type | Description |
---|---|
Colors |
The colors object for the current theme. |
__init__(self, theme='litera')
special
Parameters:
Name | Type | Description | Default |
---|---|---|---|
theme |
str |
The name of the theme to use when styling the widget. |
'litera' |
Source code in ttkbootstrap/style.py
def __init__(self, theme=DEFAULT_THEME):
"""
Parameters:
theme (str):
The name of the theme to use when styling the widget.
"""
if Style.instance is not None:
if theme != DEFAULT_THEME:
Style.instance.theme_use(theme)
return
self._theme_objects = {}
self._theme_definitions = {}
self._style_registry = set() # all styles used
self._theme_styles = {} # styles used in theme
self._theme_names = set()
self._load_themes()
super().__init__()
Style.instance = self
self.theme_use(theme)
# apply localization
from ttkbootstrap import localization
localization.initialize_localities()
configure(self, style, query_opt=None, **kw)
Query or sets the default value of the specified option(s) in style.
Each key in kw is an option and each value is either a string or a sequence identifying the value for that option.
Source code in ttkbootstrap/style.py
def configure(self, style, query_opt: Any = None, **kw):
if query_opt:
return super().configure(style, query_opt=query_opt, **kw)
if not self.style_exists_in_theme(style):
ttkstyle = Bootstyle.update_ttk_widget_style(None, style)
else:
ttkstyle = style
if ttkstyle == style:
# configure an existing ttkbootrap theme
return super().configure(style, query_opt=query_opt, **kw)
else:
# subclass a ttkbootstrap theme
result = super().configure(style, query_opt=query_opt, **kw)
self._register_ttkstyle(style)
return result
get_instance()
staticmethod
Returns and instance of the style class
Source code in ttkbootstrap/style.py
@staticmethod
def get_instance():
"""Returns and instance of the style class"""
return Style.instance
register_theme(self, definition)
Register a theme definition for use by the Style
object. This makes the definition and name available at
run-time so that the assets and styles can be created when
needed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
definition |
ThemeDefinition |
A |
required |
Source code in ttkbootstrap/style.py
def register_theme(self, definition):
"""Register a theme definition for use by the `Style`
object. This makes the definition and name available at
run-time so that the assets and styles can be created when
needed.
Parameters:
definition (ThemeDefinition):
A `ThemeDefinition` object.
"""
theme = definition.name
self._theme_names.add(theme)
self._theme_definitions[theme] = definition
self._theme_styles[theme] = set()
style_exists_in_theme(self, ttkstyle)
Check if a style exists in the current theme.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
ttkstyle |
str |
The ttk style to check. |
required |
Returns:
Type | Description |
---|---|
bool |
|
Source code in ttkbootstrap/style.py
def style_exists_in_theme(self, ttkstyle: str):
"""Check if a style exists in the current theme.
Parameters:
ttkstyle (str):
The ttk style to check.
Returns:
bool:
`True` if the style exists, otherwise `False`.
"""
theme_styles = self._theme_styles.get(self.theme.name)
exists_in_theme = ttkstyle in theme_styles
exists_in_registry = ttkstyle in self._style_registry
return exists_in_theme and exists_in_registry
theme_names(self)
Return a list of all ttkbootstrap themes.
Returns:
Type | Description |
---|---|
List[str, ...] |
A list of theme names. |
Source code in ttkbootstrap/style.py
def theme_names(self):
"""Return a list of all ttkbootstrap themes.
Returns:
List[str, ...]:
A list of theme names.
"""
return list(self._theme_definitions.keys())
theme_use(self, themename=None)
Changes the theme used in rendering the application widgets.
If themename is None, returns the theme in use, otherwise, set
the current theme to themename, refreshes all widgets and emits
a <<ThemeChanged>>
event.
Only use this method if you are changing the theme during runtime. Otherwise, pass the theme name into the Style constructor to instantiate the style with a theme.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
themename |
str |
The name of the theme to apply when creating new widgets |
None |
Returns:
Type | Description |
---|---|
Union[str, None] |
The name of the current theme if |
Source code in ttkbootstrap/style.py
def theme_use(self, themename=None):
"""Changes the theme used in rendering the application widgets.
If themename is None, returns the theme in use, otherwise, set
the current theme to themename, refreshes all widgets and emits
a ``<<ThemeChanged>>`` event.
Only use this method if you are changing the theme *during*
runtime. Otherwise, pass the theme name into the Style
constructor to instantiate the style with a theme.
Parameters:
themename (str):
The name of the theme to apply when creating new widgets
Returns:
Union[str, None]:
The name of the current theme if `themename` is None
otherwise, `None`.
"""
if not themename:
# return current theme
return super().theme_use()
# change to an existing theme
existing_themes = super().theme_names()
if themename in existing_themes:
self.theme = self._theme_definitions.get(themename)
super().theme_use(themename)
self._create_ttk_styles_on_theme_change()
Publisher.publish_message(Channel.STD)
# setup a new theme
elif themename in self._theme_names:
self.theme = self._theme_definitions.get(themename)
self._theme_objects[themename] = StyleBuilderTTK()
self._create_ttk_styles_on_theme_change()
Publisher.publish_message(Channel.STD)
else:
raise TclError(themename, "is not a valid theme.")