Utilities#

A small set of standalone helpers that don’t belong to any one widget: color conversion and contrast, high-DPI awareness and size scaling, and hooks that run your code when the theme changes. They live in ttkbootstrap.utils and are re-exported at the top level (ttkbootstrap.contrast_color, …).

Color#

Convert a color between models and derive readable pairings. A model is one of the strings "hex", "rgb", "hsl", or "name" (exposed as the constants HEX/RGB/HSL/NAME); RGB is (r, g, b) with each channel 0–255 and HSL is (hue, saturation, luminance).

color_to_hex(color, model='rgb')#

Convert color value to hex.

The color and model parameters represent the color to be converted. The value is expected to be a string for “name” and “hex” models and a Tuple or List for “rgb” and “hsl” models.

Parameters:

color (Any) – The color values for the model being converted.
model (str) – The color model being converted.

Returns:

str – The hexadecimal color value.

color_to_rgb(color, model='hex')#

Convert color value to rgb.

The color and model parameters represent the color to be converted. The value is expected to be a string for “name” and “hex” models and a Tuple or List for “rgb” and “hsl” models.

Parameters:

color (Any) – The color values for the model being converted.
model (str) – The color model being converted.

Returns:

tuple[int, int, int] – The rgb color values.

color_to_hsl(color, model='hex')#

Convert color value to hsl.

The color and model parameters represent the color to be converted. The value is expected to be a string for “name” and “hex” models and a Tuple or List for “rgb” and “hsl” models.

Parameters:

color (Any) – The color values for the model being converted.
model (str) – The color model being converted.

Returns:

tuple[int, int, int] – The hsl color values.

conform_color_model(color, model)#

Conform the color values to a string that can be interpreted by the PIL.ImageColor.getrgb method.

Parameters:

color (Union[tuple[int, int, int], str]) – The color value to conform.
model (str) – One of ‘hsl’, ‘rgb’, ‘hex’, or ‘name’.

Returns:

str – A color value string that can be used as a parameter in the PIL.ImageColor.getrgb method.

update_hsl_value(color, hue=None, sat=None, lum=None, inmodel='hsl', outmodel='hsl')#

Change hue, saturation, or lumenosity of the color based on the hue, sat, lum parameters provided.

Parameters:

color (Any) – The color
hue (int) – A number between 0 and 360.
sat (int) – A number between 0 and 100.
lum (int) – A number between 0 and 100.
inmodel (str) – The color model used by the color to be changed. One of hsl, rgb, hex, name.
outmodel (str) – The color value model to be returned when the color is changed. One of hsl, rgb, hex.

Returns:

Union[tuple[int, int, int], str] – The color value based on the selected color model.

contrast_color(color, model='rgb', darkcolor='#000', lightcolor='#fff')#

Returns the best matching contrasting light or dark color for the given color.

Parameters:

color (Any) – The color value to evaluate.
model (str) – The model of the color value to be evaluated. ‘rgb’ by default.
darkcolor (Any) – The color value to be returned when the constrasting color should be dark.
lightcolor (Any) – The color value to be returned when the constrasting color should be light.

Returns:

str – The matching color value.

High-DPI and scaling#

enable_high_dpi_awareness(root=None, scaling=None)#

Enable high dpi awareness.

Windows OS Call the method BEFORE creating the Tk object. No parameters required.

Linux OS Must provided the root and scaling parameters. Call the method AFTER creating the Tk object. A number between 1.6 and 2.0 is usually suffient to scale for high-dpi screen.

Warning

If the root argument is provided, then scaling must also be provided. Otherwise, there is no effect.

Parameters:

root (tk.Tk) – The root widget
scaling (float) –
Sets and queries the current scaling factor used by Tk to convert between physical units (for example, points, inches, or millimeters) and pixels. The number argument is a floating point number that specifies the number of pixels per point on window’s display. If the window argument is omitted, it defaults to the main window. If the number argument is omitted, the current value of the scaling factor is returned.

A “point” is a unit of measurement equal to 1/72 inch. A scaling factor of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard 72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, which is the setting for a 90 dpi monitor; setting the scaling factor to 1.25 on a 72 dpi monitor would cause everything in the application to be displayed 1.25 times as large as normal. The initial value for the scaling factor is set when the application starts, based on properties of the installed monitor, but it can be changed at any time. Measurements made after the scaling factor is changed will use the new scaling factor, but it is undefined whether existing widgets will resize themselves dynamically to accommodate the new scaling factor.

scale_size(widget, size)#

Scale the size based on the scaling factor of tkinter. This is used most frequently to adjust the assets for image-based widget layouts and pixel-valued geometry.

size is expressed in logical UI units. Conversion uses the scaling service attached to the widget’s root and rounds half away from zero.

Parameters:

widget (Widget) – The widget object.
size (int | float | list | tuple) – A number or sequence of numbers in logical UI units.

Returns:

int | list – An integer or list of integers representing the new size.

windowing_system(widget)#

Return the Tk windowing system for widget’s display.

One of 'win32' (Windows), 'aqua' (macOS), or 'x11' (Linux/Unix). Wraps widget.tk.call('tk', 'windowingsystem') so platform checks read the same everywhere instead of repeating the raw Tcl call.

Parameters:: widget (Misc) – Any widget (or the root) whose interpreter is queried.
Returns:: str – The windowing system identifier.

Reacting to theme changes#

A custom style built by hand is not rebuilt when the theme switches. Register a callback to re-run your build after every switch — or mark the builder with the theme_aware decorator, which registers it and runs it once.

on_theme_change(callback, *, call_now=True)#

Register callback(style) to run after every theme change.

Use it to keep a custom style in sync with the active theme – the callback re-runs on each theme_use / toggle_theme. Works before the root exists: if no App/Style has been created yet, the registration is queued and applied when the root comes up. See Style.on_theme_change for the full semantics. Returns callback, so it can be used as a decorator.

Parameters:: call_now (bool)

remove_theme_change_callback(callback)#

Unregister a callback previously passed to on_theme_change / theme_aware.

Removes it whether it is already live on the Style or still queued from a pre-root registration.

Return type:: None

theme_aware(callback)#

Decorator marking callback(style) as a theme-aware style builder.

Runs it once when a theme is active – immediately if the app already exists, otherwise at app creation – and again after every theme change, so the style tracks the theme:

@theme_aware
def build_styles(style):
    style.configure("Pill.TButton", background=style.colors.primary)

Defaults#

set_default_button(color)#

Set the fill for a bare (no-bootstyle) Button/Menubutton.

Before the app root exists the setting is queued and applied when the root is created – the intended use, at the top of a file.
If the root already exists it is set for buttons built after this call (existing buttons are not restyled) and a UserWarning is emitted, because default_button is consumed when a button’s base style is first built. Pass App(default_button=...) to style every bare button.

Read the current value from App().style.default_button.

Parameters:: color (str)
Return type:: None

Utilities#

Color#

High-DPI and scaling#

Reacting to theme changes#

Defaults#

See also#