pidgin/nest

Merged in rekkanoryo/theming-page-migration (pull request #94)

Migrate the ThemingPidgin wiki page to nest.

Approved-by: Elliott Sales de Andrade
Approved-by: Gary Kramlich
--- /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 @@
+---
+title: "Theming Pidgin"
+date: 2020-06-01T22:17:45-04:00
+weight: 19
+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
+systems as well.
+
+## 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)
+
+### Installation
+ 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`
+ folder.
+ 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.
+
+### Theme Switching
+ 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
+ 1. Start Pidgin
+
+
+## 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
+and simpler).
+
+_**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.
+
+### Installation
+ 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
+ GTK Installation.
+ * 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`
+ subfolder.
+
+
+## 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,
+ Pidgin included.\
+**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. OS - dark theme
+ 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.)
+
+### Theme.xml
+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
+Pidgin.
+
+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
+more important to you).
+
+### 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`
+ 1. Restart Pidgin
+ * 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
+bellow the buddy list.
+
+To hide this final problem, we have to use both a dark GTK theme and a dark
+theme.xml.
+ 1. Using the theme selector tool choose a dark background (for example:
+ Xcl-clarius-dark)
+ 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.
+
+
+## Example 4: Going Pro
+**Goal**: To attain complete control of GUI of your GTK dependent apps like
+Pidgin.\
+**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)