--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/hugo/content/help/theming.md Mon Jun 08 05:47:02 2020 +0000
@@ -0,0 +1,210 @@
+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 +## Example 2: Getting Your Feet Wet +**Goal**: To change the appearance of all of your GTK applications (Pidgin, + Ekiga, The GIMP, etc.)\ +**Theming Experience**: Minimal\ +**Desire to dig through configuration files**: Minimal\ +**Time available**: 1 hr +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)