date: 2020-06-01T22:17:45-04:00
replaces: [https://developer.pidgin.im/wiki/ThemingPidgin] Pidgin's appearance is dictated by the interaction of three types of theme files
working simultaneously at different levels:
1. Operating System theme - affecting all applications
1. GTK theme - that GTK applications use to define their GUI elements
1. Pidgin's specific theme files.
In any particular case, the level at which theming efforts should focus depends
on one's goal, knowledge of theming of each of the above file types, the
availability of time and desire to sort through numerous setting parameters and
the state of bugginess of software at that time.
Please note that this content was adapted from documentation written by a Pidgin
user in late 2012 or early 2013. References to things such as Windows XP may be
outdated, however the overall content is still relevant. Additionally, this
content focuses primarily on Windows, however, much of it will apply to other
## Example 1: Novice Proof **Goal**: To give only Pidgin a facelift for variety's sake.\
**Theming Experience**: Zero\
**Desire to dig through configuration files**: Zero\
**Time available**: 15 min
By far, the simplest "off the shelf" solution is to download the GTK+ theme
installer package which includes a large number of ready GTK themes (engines and
corresponding configuration files) as well as a theme switching preference tool.
_**Note**_: all package names that follow are for a Windows system and can be
downloaded [
here](
https://gtk-win.sourceforge.io/home/index.php/Main/Downloads)
1. Download the package: gtk2-themes-2009-09-07-ash.exe
1. If Pidgin was installed in the currently standard way, GTK will be
installed within it. Thus, direct the Installation to that
`Pidgin\GTK` 1. After Installation, move
`gtk2_prefs.exe` from
`Pidgin\GTK` to
`Pidgin\GTK\bin` subfolder. This is the preference tool (theme selector)
file that the installer puts in the wrong place. If this isn't done, the
preference tool will not see the new themes loaded.
1. Go to
`Pidgin\GTK\bin` 1. Start
`gtk2_prefs.exe` 1. Using the Preference Tool's GUI as a demo display, pick a theme you like
* **Note** the
`Darklooks` theme appears to be broken at this time.
1. Make sure to ***NOT*** check
`Apply for all users` as this will cause the
1. Click the
`OK` button and accept the prompt.
1. Start or restart Pidgin and enjoy your new theme!
## Example 2: Getting Your Feet Wet **Goal**: To change the appearance of all of your GTK applications (Pidgin,
**Theming Experience**: Minimal\
**Desire to dig through configuration files**: Minimal\
If you have some time on your hands, understand the basics of GTK themes, just
want a few themes you know by name and like to keep your system lean and mean
(keep out anything unnecessary), you may want to get the GTK theme zip package
and hand pick the elements you need. Just be aware that theme engines and
configuration files are packaged in separate directories, engine names are not
always identical to the config file names, one doesn't work without the other
and so you may end up having to experiment (which is why the installer is faster
_**Note**_: Due to current bugs, there may not be binary compatibility on
Windows between compile-time and runtime GTK versions, i.e.: different
applications may be impossible to satisfy with a single install of GTK. In a
perfect world, the following could work.
1. Download the theme selector:
`gtk2_prefs-0.4.1.bin-gtk2.10-win32.zip` 1. Download the theme package:
`gtk2-themes-2009-09-07-win32_bin.zip` 1. If Pidgin was not installed in the currently standard way (GTK was
installed not with Pidgin, but for all GTK applications system wide):
* Move relevant components from packages to corresponding folders in that
* Unzip themes and pick the ones you want. Configuration files are in
`share` and engines in
`lib` directories. Thus, for a theme "Aurora",
the folder
`Aurora` would need to be moved from the package's
`share\themes` to
`GTK2-Runtime\share\themes` and the file
`libaurora.dll` from the package's
`lib\gtk-2.0\2.10.0\engines` to
`GTK2-Runtime\lib\gtk-2.0\2.10.0\engines`.
1. Continue as above for each theme desired.
1. Unzip the theme selector and move
`gtk2_prefs.exe` to
`Pidgin\GTK\bin` ## Example 3: The Comedy of Errors **Goal**: You spend countless hours in front of a monitor and want to reduce eye
strain. To accomplish this, you need to create a dark theme (light
text on a dark background) for your entire system - all applications,
**Theming Experience**: Little\
**Desire to dig through configuration files**: Present within reason\
**Time available**: Potentially significant
If you thirst for knowledge, are not satisfied with off the shelf solutions,
and/or require maximum control over the appearance of your applications, buckle
up and hold onto your hat! For the author of this passage, to learn how to
theme Windows XP, Thunderbird, Firefox and Pidgin took exactly one month with
Pidgin being by far the most time consuming. Why is this the case? Let's go
back to the levels at which theming is applied.
After you will have created your ultimate dark OS theme file, you will have the
pleasure of seeing that many apps automatically will just have fallen into
place, i.e.: without any additional theming efforts - not Pidgin! If your new OS
theme produces white text on a black background, after a default Pidgin install,
you will have the following settings and interaction of the three theme files.
1. GTK - default theme - "MS-Windows"
1. Pidgin - Buddy List Theme - "Default"
In this case, the OS produces the dark theme; GTK's "MS-Windows" theme acts as a
"transparent" layer showing what Win OS dictates and Pidgin's default theme
similarly allows to show through what GTK is delivering. The end result is
reassuring - dark windows in both buddy and chat windows with buddy group names
appearing white on black. But, due to a known bug in GTK and/or the GTK
MS-Windows theme, some of the OS's theme information isn't properly interpreted,
resulting in buddies within groups appearing black on black - ie: invisible!
(Everything looks fine with a typical "Black on White" theme without the need
for any further action but that was not our goal.)
To give users more control, Pidgin allows further customization through its own
theme.xml files. Pidgin's Buddy List theme.xml file offers exact control of
text and background colour elements in the buddy list window. BUT, as luck
would have it, GTK's "MS-Windows" constrains what can be overridden (the only
GTK theme to do so). Thus, theme.xml cannot work properly with it. The end
result is, to make use of the fine grain control of Pidgin's
`theme.xml`, one
must not use the GTK's MS-Windows theme. Which is particularly problematic
since it is the only GTK theme that can pass through the Windows OS appearance -
all other GTK themes take over and mask it. This, regrettably, means that all
the effort you've invested in making a beautiful OS theme cannot be seen in
Pidgin. It also means that since you cannot rely on GUI information coming from
the OS, you now MUST install a GTK theme pack with a theme selector tool (as
discussed above) in order to circumvent the only GTK theme that comes with
After downloading a theme pack, you get access to a large number of GTK themes
the manifestation of which you can indirectly affect with theme.xml. Details of
theme.xml file syntax, explanation of controls available as well as some sample
files can be found [
here](
https://developer.pidgin.im/wiki/BuddyListThemes)
### Creating a theme.xml file The quickest way to make your own custom theme.xml file is to download a ready
made theme from the above link and edit it to suit your needs with your
favourite text editor (like Vim). Alternatively, you can write one from scratch
by following instructions on the wiki. If creating your own colour scheme, a
convenient resource of hex colour codes can be found
[
here](
http://www.colour-hex.com/popular-colours.php) If you like to experiment
with colours, you can use the colour wheel present in Windows for selecting your
desktop colour. Once you come up with a colour you like, resulting RGB numbers
can be plugged into a RGB to Hex colour converter which can be found
[
here](
https://www.javascripter.net/faq/rgbtohex.htm). Finally, if making a
theme to be used with a transparency plugin, remember that dark colours are less
transparent than light ones. With monitor brightness set to minimum, dark
backgrounds will simply look black. Thus, for the best transparency effect,
have to use a light colour palette (which unfortunately is the opposite of what
you want if the aim is to create a dark background; therefore, decide what's
### Installing a theme.xml file 1. When the file is ready, keep one copy (in backup) under the theme name.
1. Make a copy of it and rename the copy to
`theme.xml` 1. Start Pidgin and go to:
_Tools_ >
_Preferences_ >
_Themes_ 1. Drag and drop
`theme.xml` onto the field of the Buddy List Theme
* Pidgin will create the necessary subdirectory structure placing the file
in:
`.purple\themes\temp\sub_folder` 1. Move theme.xml from there to:
`.purple\themes\ThemeName\purple\blist` * The new theme will now be present in the list.
### Putting it All Together Now all the components are in place but there is still one more bug we have to
overcome. In Pidgin's theme.xml file, "blist" - the 'colour' attribute that
sets the background colour of the entire buddy list - doesn't work. So if the
GTK theme is light, the background colour behind buddy text is dark and the
buddy list is short or groups are collapsed - the light background will show
To hide this final problem, we have to use both a dark GTK theme and a dark
1. Using the theme selector tool choose a dark background (for example:
1. Start Pidgin and go to:
_Tools_ >
_Preferences_ >
_Themes_ 1. Choose your dark theme from the Buddy Theme List
1. Enjoy the fruits of your labor.
**Goal**: To attain complete control of GUI of your GTK dependent apps like
**Theming Experience**: Moderate - Advanced\
**Desire to dig through configuration files**: It's your cup of tea! \
**Time available**: You love it so who's counting?
If you found this journey exhilarating, are looking for a new hobby or are
thinking of going pro in the field of GTK GUI development you will have to
master editing GTK Theme configuration files (gtkrc's) directly. This is beyond
the scope of this discussion; however, a good starting point for that can be
found [
here](
https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes)
