ttkthemes documentation

A group of themes for the ttk extenstions for Tkinter gathered together by RedFantom and created by various authors.

Authors

The ttkthemes package contains many different themes created by many different authors. Some themes are even derived from other software, like GTK-themes.

GNU GPLv3 Themes

• arc: Copyright (c) 2015 Sergei Golovan
• equilux: Copyright (C) 2018 RedFantom
• itft1: Copyright (C) 2005 Jelco Huijser
• ubuntu: Copyright (C) Regents of the University of California, Sun Microsystems, Inc., Scriptics Corporation, and other parties. Copyright (C) 2018 RedFantom
• yaru: Copyright (c) 2020 RedFantom, 2015 Sergei Golovan, the yaru_authors.

Tcl-License Themes

• aquativo: Copyright (C) 2004 Pat Thoyts
• black: Copyright (c) 2007-2008 Mats Bengtsson
• blue: Copyright (C) 2004 Pat Thoyts
• clearlooks: Copyright Regents of the University of California, Sun Microsystems, Inc., Scriptics Corporation, and other parties
• elegance: Copyright Regents of the University of California, Sun Microsystems, Inc., Scriptics Corporation, and other parties
• keramik and keramik_alt: Copyright (C) 2004 Pat Thoyts
• kroc: Copyright (C) 2004 David Zolli
• plastik: Copyright (C) 2004 Pat Thoyts
• radiance: Copyright Regents of the University of California, Sun Microsystems, Inc., Scriptics Corporation, and other parties
• scid and all its derivatives: Copyright (C) 2018 Uwe Klimmek
• smog: Copyright (C) 2005 Jelco Huijser
• winxpblue: Copyright (C) 2004 Pat Thoyts

Reference

Example

Using ttkthemes is easiest through the usage of ThemedTk. The following example is written for Python 3.

from tkinter import ttk  # Normal Tkinter.* widgets are not themed!
from ttkthemes import ThemedTk

window = ThemedTk(theme="arc")
ttk.Button(window, text="Quit", command=window.destroy).pack()
window.mainloop()

Themes

ttkthemes includes a wide variety of different themes, and there is always room for more themes, no matter how ugly or obscure! Even though some themes may not be used in practice, the original goal of the project has not been forgotten: To gather and preserve all themes.

Adapta

Aquativo

An Apple-style like theme by Pat Thoyts, created in 2004. The original site is listed to be http://www.fewt.com, but you will only be able to view this site using the Internet archive’s Wayback machine. It appears the theme is related to the Ubuntu-based Linux distribution _Fuduntu.

Arc

The newest theme of the bunch. Being created by Sergei Golovan in 2015 this theme requires Tk 8.6.0 in order to load. This is because the theme uses PNG images with transparency, making for a blue-tinted modern look and feel.

Black

A simple yet quite popular theme, as it is very consistent in its use of dark colors in all widgets. Created by Mats Bengtsson in 2007.

Blue

A theme that does live up to its name. This theme will burn your eyes out being so bright. Everything is blue, though in some widgets there is a nice color gradient. This theme was also created by Pat Thoyts in 2004.

Breeze

Clearlooks

This theme was created by the Tcl/Tk developers team as a demo for what bitmap themes can do. The light tints move toward peach colors, giving this theme a feminine look. It still looks sleek and modern, and wouldn’t be a bad choice. Just as with all themes though, the corners are rounded.

Elegance

A theme that appears to be created by the Tcl/Tk developers team. While attempts to tracing its exact origin have been unsuccessful so far, this theme was probably created around 2008. The theme can be found here, but no author is listed.

Equilux

Originally equilux is a GTK3 theme.

ITFT1

Keramik

These two themes use a single file keramik.tcl and the differences between them are fairly limited. Originally developed by Pat Thoyts in 2004. These themes look the opposite of modern. They are futuristic, but in a bit of a wrong way. Keramic_alt uses a different color scrollbar element, namely silver instead of dark blue.

Kroc

This orange theme by David Zolli is busy on the eyes and has a wood-like grain in the Button widgets. Not a recommended choice for modern UI development.

Plastik

A nice looking theme created by Pat Thoyts in 2005. While not bolstering the most distinctive features, it looks quite modern. Performance suffers heavily though, this is resolved by commenting out line 193 of the plastik.tcl file. The theme changes only slightly because of this change, but native performance is restored.

Radiance (Ubuntu)

A theme that was developed by the Tcl/Tk developers team. This theme, as the name suggests, boasts the native look of Ubuntu’s radiance theme, making for a good choice when targeting this platform. Large Progressbar widgets (namely in height) may look a bit mutated, so try sticking to the normal Progressbar height.

Theme ubuntu is equal to radiance, except it uses transparent elements in place of some white areas. Therefore, it looks a bit better when PNG-themes are available.

Scid themes

The scid themes form a group of themes that all share the same basic look but with differently colored accents.

Smog

winxpblue

A theme that tries to imitate the Windows XP look and feel created by Pat Thoyts in 2004. Not recommended, even for Windows XP applications.

yaru

Theme derived from the new Ubuntu 20.04 default theme and theme ‘arc’.

Theming

ttkthemes supports the creation of custom themes based upon static themes during runtime. This is called dynamic theming. The functions to create dynamic themes are implemented in the ThemedWidget class. PNG-based theme support is required to apply a dynamic theme.

Choosing a theme

In order to use dynamic theming, you must first choose a theme to base your new theme on. The supported themes for dynamic themes are all pixmap themes that use files (and not a packed archive with files) directly to load pixmaps. An up-to-date list of supported pixmap themes may be found in the pixmap_themes class attribute of any ThemedWidget instance (such as ThemedTk or ThemedStyle). At the time of writing, the following list is available:

pixmap_themes = [
   "arc",
   "blue",
   "clearlooks",
   "elegance",
   "kroc",
   "plastik",
   "radiance",
   "winxpblue"
]

It is recommended to choose a theme with noticeable colors for the best results. radiance and blue have proven to be quite suitable for this purpose. In order to use blue, it is recommended to also modify the background colors of all widgets you plan to use, as the theme colors are not changed during the operations.

Note that while being a pixmap theme, equilux is not included because using dynamic theming with that theme results in severe conversion artifacts.

Modifying a theme

In order to load an advanced theme, the following function is provided within any ThemedWidget:

def set_theme_advanced(
    self, theme_name, brightness=1.0, saturation=1.0, hue=1.0,
    preserve_transparency=True, output_dir=None, advanced_name="advanced"
)

As you might be able to deduce from the function definition, various parameters can be used to modify the pixmaps of the theme you choose:

• theme_name: The name of a valid pixmap theme to use for modification
• brightness: A modifier that is passed on to a PIL.ImageEnhance.Brightness enhancer. Values between 0.0 and 2.0 are expected.
• saturation: A modifier that is passed on to a PIL.ImageEnhance.Color enhancer. Values between 0.0 and 2.0 are expected.
• hue: A modifier that is used for the ttkthemes._utils.shift_hue function. Shifts the hue of an image by a certain amount. Note that the hue is the hue shift. Values between 0.0 and 2.0 are expected.
• preserve_transparency: When set to True, all resulting black pixels will be set to transparent. This is only required when modifying the hue of an image. During the conversion from RGBA to HSV image format, transparency is lost to black pixels, resulting in ugly black patches in images if not reversed.
• output_dir: Directory (to which write access is available) in which the new theme files should be placed. By default, a temporary directory is used provided by tempfile. Note that on most systems, this directory is cleared upon reboot.
• advanced_name: Name of the theme to generate. You can combine this with an output_dir parameter to actually create a custom theme that you can install on other machines as well. NOTE THAT IT IS REQUIRED TO USE A DIFFERENT NAME EACH TIME IF YOU SET THE ADVANCED THEME FOR A SINGLE TK INTERPRETER INSTANCE MULTIPLE TIMES.

Examples

Some examples of what you can create using this function:

A modified radiance theme. The hue is changed so all originally orange features are a bright green.

A modified arc theme. The hue is changed as well as the brightness, though the latter only very slightly.

Notes

Note that the theme is generated during runtime, when the function set_theme_advanced is called. When the function is called, rather resource-expensive operations upon tens of images are performed, as well as disk I/O and loading all images into memory may cause a spike in memory usage, even though it is not all that much on most modern PCs.

Licenses

The themes included in the ttkthemes package have been released under various different licenses, including the BSD-2-clause-like Tcl License, GNU GPLv2+ and GNU GPLv3. Note that the only license under which all themes are available together is GNU GPLv3. Most of the code is available under GNU GPLv3 only. If code is available under any other license, it is indicated in the specific files and folders.

Installation

The installation of ttkthemes is very simple. There are a few ways to install ttkthemes.

PyPI

Installation from PyPI is easiest. Simply use pip to fetch the package and install it:

There is a single installation option available for ttkthemes. In order to use the high-quality PNG-themes instead of the GIF-themes, an extension is required under Python 2 and some earlier distributions of Python 3. Simply install the extension with pip as well.

This option installs the separate package tkimg, for which more information is available from here.

In some cases, it is required to update setuptools in order to install ttkthemes. It is not known which version of setuptools is exactly required at this time.

Source

Installation from git is also possible:

python3 -m pip install git+https://github.com/RedFantom/ttkthemes

Theme Loading

Tkinter for Python runs a Tcl-interpreter with the Tk package. The actual UI is drawn and controlled by this Tcl-interpreter. In order to load themes into Tkinter, it must be done through this Tcl-interpreter. This page describes how this is done, and what the limitations per Python version are.

Loading

Each theme is a Tcl-package in itself. In order to load the theme, the package has to be loaded. Usually, stand-alone packages come with a pkgIndex.tcl file, which checks the dependencies of the package and then provides a package ifneeded {name} {version} line.

Then, in order to execute the code that creates the package, a package require {name} {version} is executed. Subsequently, the code provided after the package ifneeded is executed, and thus the files for the package are executed.

The code files that are executed to create the package then provide a package provide {name} {version} line, which creates the package. Then loading the package is complete, and the theme is available.

In the case of ttkthemes, there is a big difference. The themes are split into PNG-themes (which also have a GIF-version) and GIF-only themes. The appropriate pkgIndex.tcl files in the right folders are evaluated depending on whether the PNG-dependencies have been met. Instead of using package ifneeded with a pkgIndex.tcl file for each theme, ttkthemes loads all the themes instantly upon evaluation of the pkgIndex.tcl file of the whole folder of themes.

This is done so as to limit the amount of Tcl-code in the ttkthemes package. While the ttkthemes package could still be used with Tcl directly, it is intended for use within Python, and Tkinter’s error reporting facilities are extremely limited (no full tracebacks are available), and thus the amount of Tcl-code is best minimized. All work that can be performed in Python is performed in Python.

For more information on packages and loading them, check the tcl-lang wiki website.

Limitations

All themes are available on all platforms that support Tk 8.4 or higher. Tk 8.4 is available with all Python distributions of 2.7 or higher. Python-distributions may be created with higher versions of Tk as well. In order to load the higher quality PNG version of themes for which it is available, either Tk 8.6 is required, or TkImg. Tk 8.6 is available with Python 3.6 in most Python binary distributions, including the Windows binaries and the Ubuntu PPA-version. However, it may be possible that there are binary distributions compiled with a different version of Tk out in the wild. In order to use the PNG version of themes on older Python versions, including Python 2.7, TkImg is required. While formerly provided with ttkthemes, the Tk-extension TkImg is now available for Python in a separate package: tkimg.

Tcl-loading

The ttkthemes themes can be loaded from a Tcl-interpreter directly. In fact, this is what the _Widget-class does for the ttkthemes Python-package. In this section, from this point onwards, ttkthemes will refer to the Tcl-package instead.

The themes provided are divided into two categories: themes with a PNG and GIF version and themes with only a GIF version. The GIF-only themes are provided in the folder /ttkthemes/themes. The pkgIndex.tcl file in this folder loads all themes in the folder when executed and provides the ttkthemes package.

For the other category of themes, only the GIF or PNG version can be loaded, as loading a second package with a name which is already used by another package is not possible.

Depending on whether the PNG or GIF version of themes should be loaded, the pkgIndex.tcl in the ttkthemes/gif or ttkthemes/png can be evaluated. The PNG themes can only be loaded if Tk is version 8.6 or TkImg is available.

package require Tk 8.6
source ttkthemes/themes/pkgIndex.tcl
source ttkthemes/png/pkgIndex.tcl
package require ttkthemes 1.0
ttk::setTheme plastik

License

ttkthemes: A group of themes for the ttk extensions of Tcl

• Copyright (C) 2017-2018 RedFantom
• Copyright (C) 2017-2018 Akuli
• Copyright (C) 2004 Pat Thoyts
• Copyright (C) 2004 David Zolli
• Copyright (C) 2007-2008 Mats Bengsston
• Copyright (C) 2015-2018 The materia and equilux authors
• Copyright (C) 2005 Jelco Huijser
• Copyright (C) Regents of the University of California, Sun Microsystems, Inc., Scriptics Corporation, and other parties.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Please note that while you can use some themes only under GPLv3 and that my code is also available only under GPLv3, some themes, of which the files have a header explicitly stating this, are also available under the BSD-like 2-clause Tcl license.

Recommendations

The themes plastik, clearlooks and elegance are recommended to make your UI look nicer on all platforms when using Tkinter and the ttk extensions in Python. When you are targeting Ubuntu, consider using the great radiance theme.