Making GTK3 themes – Part 1: Basics

I’m Satya. I’ll be writing some tutorials about making GTK3 themes here at World of Gnome. Thanks to woGue for giving me a chance to write here :)

In this post I’ll discuss some basic things about GTK3 themes. So let’s start…

The new trend is to use the web technologies everywhere, be it smartphone or desktop. Web technologies are generally easier, and that’s why they are so widespread.  So what it has to do about GTK3 themes? A lot, because GTK3 themes use CSS syntax, which is widely used in the web. CSS stands for Cascading Style Sheets. The CSS syntax is very easy to understand and and use. For example, if we want to set a blue background and white text color in a paragraph (represented as <p> in HTML), the CSS syntax will be,

p {
background-color: blue;
color: white;
}

We won’t go into details of CSS and assume you learnt it already. If not, w3schools is a quite good place to start. Let’s discuss about GTK3 themes instead. Also check developer.gnome.org, it has some good resources.

I believe that we cannot learn everything from tutorials. We learn as we do. So I shall not only write a tutorial here, but also guide you through creating a theme. But will do it from next part. Just basics for today :D

Directories and files

When a GTK3 app starts, it will load certain files. First it tries to load the file $XDG_CONFIG_HOME/gtk-3.0/gtk.css if it exists (usually ~/.config/gtk-3.0/gtk.css). Then, tries to load ~/.themes/name/gtk-3.0/gtk.css. And lastly, tries to $datadir/share/themes/name/gtk-3.0/gtk.css (usually /usr/share/themes/name/gtk-3.0/gtk.css), where “name” stands for the name of the current theme. What does it mean? It means if you place a theme in /usr/share/themes/ and a modified one in ~/.themes/, the one in ~/.themes is used. Note that if you place a theme in /usr/share/themes, then it will be available for all users, but if you place it in ~/.themes, then it will be only available to you.

So basically we have our theme in ~/.themes and the GTK3 part in ~/.themes/name/gtk-3.0.

Theme engine

The look of your theme may vary depending on what engine you use. Different theme engines may provide different features than the default engine. Additional features provided by an engine is generally registered with a prefix, similar to vendor prefixes in the Web (We’ll discuss it later). So choosing the right theme engine is necessary.

Currently, you have 3 options,

1. Use the default built-in engine
2. Use the Adwaita engine
3. Use the Unico engine

So which one should you choose? Let’s look at the advantages of different engines.

The default built-in engine

You can do a complete full featured theme with the default engine. the syntax is similar to pure CSS and there are no engine specific prefixes. It offers standard features like multiple inset box shadows, gradients etc.

With the default engine, you might also experience few quirks. Such as the scale slider doesn’t look so good. The focus border is a dotted line and seems that we cannot change or disable it.

Examples: Evolve, Albatross

The Adwaita engine

Adwaita offers some advantages over the default engine like customizable focus borders, border gradients etc. Also you won’t experience much quirks here.

Examples: Adwaita, Gnomish Gray etc.

The Unico engine

Unico offers many new features. For example customizable focus borders and focus fill, border gradients, inner strokes, outer strokes, glows etc. But seems that box shadow is not supported in Unico. So you will need to use lots of engine specific prefixes. And it can be more difficult for you to port to another engine. Also I hear that the Unico engine will be abandoned. So think twice before you decide to use Unico. As far as i can tell, you’ll only miss outer strokes.

Examples: Ambiance, Zukitwo, Elementary etc.

So I won’t make this post any longer. We’ll start making our dream theme on the next post. :D

Part 2 | Part 3 | Part 4