Theming HOWTO

This document describes how to write themes for dockbarx.

A dockbarx theme resides in a tar.gz file. The extension is important since dockbarx finds it's themes by checking ~/.dockbarx/themes and /usr/share/dockbarx/themes for file with the extension tar.gz. 

The .tar.gz file should consists of a config file, which informs dockbarx how the theme should look, and (optionally) a folder "/pixmap" consisting of the images (pixmaps) that the theme uses.


*** Observe the changes done to <alpha_mask> in verion x.0.30! ***

The config file
===============

The config file should be written in XML-form. That means that every element must have a beginning and a end, eg. <example></example> or have an slash at the end, eg. <example />. Attribute values should always be in quotation even numbers, eg. <example question="The meaning of life" answer="42">.


This is the basic structure of the file:

<theme name = "NAME">
<pixmaps>
</pixmaps>
<colors>
</colors>
<button_pixmap>
</button_pixmap>
</theme>

Nothing should be written outside of <theme></theme>. The name attribute is used in dockbarx to recognize the theme and has to be unique. You can't have two themes in dockbarx with the same name.



PIXMAPS
Between the <pixmaps></pixmaps> all the pixmaps used in the theme should be mentioned like this:

<pixmaps>
	<pixmap_from_file name="launcher_button" file="launcher_icon.png" />
</pixmaps>

<pixmap_from_file> is the command to use for registering the pixmaps that are packed in the theme. The name attribute is what you should use later when referring to the pixmap and the file attribute points to the file that should be loaded. In the example above the file launcher_icon.png in folder pixmaps in the theme (.tar.gz) file should be loaded. Don't forget the slash (/) in the end of the command!



COLORS
Between <colors></colors> you can decide the user customizable colors. There are eight user customizable colors (<color1 /> to <color8 />) that are available to the user from dockbarx's preference dialog. The theme control the name of the color (which will be displayed in preference dialog), the default color and the default opacity (or decide that no opacity should be available at all).

This is an example of what a <colors></colors> section could look like:

<colors>
	<color5 name="Attention color" default="#FF0000" opacity="30" />
	<color6 name="Mouse over color" default="#FFFFFF" opacity="20" />
</colors>

<color{NUMBER} [name="NAME"] [color="COLOR"] [opacity="OPACITY"] > sets the values for the color. {NUMBER} should be replaced by a number ranging from 1 to 8, depending on which user customizable color you want edit. 
- The name attribute sets the name of the color. That name is displayed in the preference dialog of dockbarx.  
- The default attribute sets the default value for the color. It should be a six-digit hex number. eg. "#FF0000" for red. 
- The opacity attribute decides the default value for the opacity of the color. It can be a value between "0" (completely transparent) to "100" (completely opaque). The opacity attribute can also be set to "no" which means that there will be no option to set opacity for that color. 

If any of the attributes are missing from a <color{NUMBER} /> command the dockbarx's default will be used for that color, eg <color5 default="#FFFFFF" /> will set the default value of color5 but use the default name and the default opacity for color5 from dockbarx. If a color isn't specified within <colors></colors>, dockbarx's default will be used for that color as well. In the example section above all colors but color5 and color6 will be set to their default.

Here is a <colors></colors> section containing all the default values used by dockbarx.

<colors>
	<color1 name="Popup background" default="#333333" opacity="80" />
	<color2 name="Normal text" default="#FFFFFF" opacity="no" />
	<color3 name="Active window text" default="#FFFF75" opacity="no" />
	<color4 name="Minimized window text" default="#9C9C9C" opacity="no" />
	<color5 name="Active color" default="#FFFF75" opacity="63" />
	<color6 name="Not used" default="#000000" opacity="no" />
	<color7 name="Not used" default="#000000" opacity="no" />
	<color8 name="Not used" default="#000000" opacity="no" />
</colors>

NOTE! For now color1 to color4 has uses decided by dockbarx, no matter what you call them. Color 1 is used for the background color of dockbarx's windows list, color2 is used for the text in that list, color3 for the text of the active window in that list and color4 for the the text of minimized windows in that list. Color5 to color8 are only used if the theme decides to use them. (color5 has default values anyways to for backward compability with old themes.) Please consider this when naming and deciding defaults for color1 to color4. (And DON'T set opacity to "no" for color1!)



BUTTON_PIXMAP 
<button_pixmap [gap="0"] [aspect_ratio="1"] [windows_cnt="1"]></button_pixmap>
Between <button_pixmap> and </button_pixmap> the instructions for the group button design should be put. 
- The gap attribute sets the gap between the buttons. Default gap is "0".
- The aspect_ratio attribute sets the aspect ratio for the buttons. It should either be a fraction "4/3" or a float "1.33". Default aspect ratio is "1". 
- The windows_cnt attribute has to be used if the theme should be able to give visual feedback on the numbers of open windows. If windows_cnt is set to "3", the theme engine will get information if there are one, two, or three windows of an program is open. If four or more windows are open, the theme engine will still believe that three windows are open. This attribute exists to save memory. Don't set windows_cnt higher than you need. For example, if you intend to use <if windows="1"></if> and <if windows="2:"> in your theme, then set windows_cnt="2". (More information on the <if></if> block can be found below.) Default windows_cnt is "1", which only should be used if you don't intend to have any visual feedback on the numbers of windows.

Things between <button_pixmap> and </button_pixmap> is read like a programming language, top-to-bottom. First line is executed first, then the second and so on. Here is an example from (an old version of) the default theme:

EXAMPLE
<button_pixmap gap="0">
	<get_icon size="-2" />
	<if type="all_minimized">
		<transp_sat opacity="74" saturation="14" />
	</if>
	<if type="mouse_over">
		<bright strength="13" />
	</if>
	<if type="launcher">
		<shrink percent="20" />
		<composite bg="self" fg="launcher_button" opacity="100"/>
	</if>
	<correct_size />
	<if type="active">
		<glow color="active_color" opacity="active_opacity" />
	</if>
	<if type="some_minimized">
		<pixmap_from_self name="greyed">
			<transp_sat opacity="74" saturation="14" />
		</pixmap_from_self>
		<combine degrees="90" pix1="self" pix2="greyed" />
	</if>
	<if type="needs_attention">
		<pixmap name="red">
			<fill color="#FF0000" opacity="50" />
		</pixmap>
		<composite bg="red" fg="self" />
	</if>
</button_pixmap>

SIZE ZERO
Before we look at the different commands used here, let's talk a bit about sizes. Dockbarx needs pixmaps of an certain size (or more exactly, a certain height when used in horizontal panels and a certain width when used in vertical) to work. In the config file this size is called size zero. When working on pixmaps it's not always convenient to use that size. You can specify a smaller size in get_icon (see below) by using a negative number. All sizes in the config file are relative. It's up to you to remember how far under size zero you are. An button_pixmap should always be of size zero when it's done - otherwise dockbarx tries to correct the size by adding transparent borders around the pixmap or by shrinking it. I hope this makes sense to you, if it doesn't, just ignore it and simply use trial and error. ;)


BUTTON_PIXMAP COMMANDS
<get_icon [size="0"] /> is the command loads the icon for the program that the group button is for, eg. the Firefox icon for Firefox. 
- The size attribute tells which size the icon should be. Default is "0". Size zero means that the icon is as big as the group button. A negative number means that the icon is as many pixels smaller as the number. size should never be a positive number! In the example code above the icon size is two pixels smaller than the group button size. Don't forget the slash (/) in the end of the command!

<if [type="TYPE"] [windows="WINDOWS"] [size="SIZE"]></if> is the command for conditional code. If the type and/or the number of windows argument is/are satisfied, the code between <if> and </if> will be executed.
- The type argument can be one of the following:
	"all_minimized"
	Code within <if type="all_minimized"></if> blocks will be executed if the icon 
	that is drawn is for a program with all windows minimized (including programs
	with only one minimized window).

	"some_minimized"
	Code within <if type="some_minimized"></if> blocks will be executed if the icon 
	that is drawn is for a program that has some unminimized and some minimized
	windows.
	
	"mouse_over"
	Code within <if type="mouse_over"></if> blocks will be executed if the mouse cursor 
	is over the group button for which the icon is drawn.

	"launcher"
	Code within <if type="launcher></if> blocks will be executed if the group button for 
	which the icon is drawn is a launcher without any open windows.

	"active"
	Code within <if type="active"></if> blocks will be executed if the icon 
	that is drawn is for a program that has the active (focused) window.

	"needs_attention"
	Code within <if type="needs_attention"></if> blocks will be executed if the icon 
	that is drawn is for a program that has a window that needs attention and dockbarx
	is set to use the static antention.

	"blink"
	This one is identical to "needs_attention" except it is for the blinking attention.

	"launching"
	Code within <if type="launching"></if> blocks will be executed if the program is
	launched from dockbarx and the window hasn't shown yet. Use it to make a launching
	effect. ;p

If a "!" is set before the type it means all but that type. For exmaple the code within a <if type="!mouse_over"></if> will be executed if the mouse cursor is over the group button for which the icon is drawn.


The windows argument tells the number of windows that the program should have for the code to be executed. It can either be just a number, e.g. <if windows="3"></if>. In this case the code will be executed only if the program has exactly three windows. You can also have code executed for a range of windows. Eg. if you want code executed when two to four windows are open, the command looks like this: <if windows="2:4"></if>. If you want code that are executed for two or more windows just leave out the later number (<if windows="2:"></if>) or the first number if you want code for two or less windows (<if windows=":2"></if>. You can also use a "!" before a number or range, which means "anything but", eg. "!2" means the code will be executed if the numbers of windows is anything but 2 and "!3:4" means the code will be executed if the numbers of windows are less than three or more than 4. Note! Remember to set the windows_cnt attribute of <button_pixmap> high enough. If you have a <if windows="3:"></if> and windows_cnt="2", the code within that block will never be executed, since three windows will be reported as being only two windows when windows_cnt is "2". In this case you need to set the windows_cnt to "3" or more.

The size argument lets you write code that will be exeuted only if the panel size is within a certain range. The syntax is the same as for the windows attribute, eg. <if size="20:25"></if> would only be executed if the panel was between at least 20 pixels high and at most 25 pixels high.

<pixmap name="NAME"></pixmap> 
Sometimes you want to make a new pixmap to use for compositions or combinations. You can use the <pixmap name="NAME"></pixmap> for making a new empty pixmap. 
- The name attribute sets the name for your pixmap so that you can refer to it when you want to use it later. The size of the new pixmap is the same as them pixmap you currently are working on.

<pixmap_from_self name="NAME"></pixmap_from_self> is the same as <pixmap></pixmap> except that pixmap_from_self makes a copy of the pixmap that you are already making (usually <button_pixmap>) instead of making an empty pixmap. In the example above, pixmap_from_self is used to make a slightly transparent and desaturated copy of the current pixmap, that later will be combined with the original icon to make the half greyed out icon that is used for when some windows are minimized.

<fill color="COLOR" [opacity="100"] /> fills the entire pixmap with a color. 
- The color should be a # and a six-digit hex number eg. "#FFFFFF" for white, or a user customizable color ("color1" to "color8"). 
- The opacity should be a number between "0" and "100" (default is "100") or the opacity from a user cutomizable color ("color1" to "color8").

<bright strength="STRENGTH" /> is pretty self-explanatory. Brightens the pixmap. Strength goes from 0 to 100.

<shrink [percent="0"] [pixels="0"] /> shrinks the pixmap as many percent and/or pixels as are given. NOTE! This will blur the pixmap. In some cases it's better to import the icon in a smaller size instead.

<transp_sat [opacity="100"] [saturation="100"] /> sets transparency and/or saturation for the pixmap. 
- Opacity="100" means that no transparency is added while opacity="0" means a fully transparent pixmap. 
- Likewise, saturation="100" means that no desaturation is taking place while saturation="0" gives a fully desaturated pixmap.

<glow color="COLOR" [opacity="100"] /> adds a glow around the pixmap. The color attribute should be a six-digit hex (eg. "#FFFFFF") or a user customizable color ("color1" to "color8"). The opacity attribute goes from 0 to 100 or the opacity from a user cutomizable color ("color1" to "color8").

<correct_size /> adds transparent borders around an pixmap that is smaller than size zero. In other words, the pixmap will be of size zero afterwards.

<composite bg="PIXMAP1" fg="PIXMAP2" [opacity="100"] [xoffset="0"] [yoffset="0"] /> puts the foreground pixmap (fg) on top of background pixmap (bg). A pixmap can either be a previously made pixmap (made with <pixmap></pixmap> or <pixmap_from_self></pixmap_from_self>), one of the previously loaded pixmaps (<pixmap_from_file />) or the current pixmap (simply referred to as "self"). Note: The background pixmap must NOT be smaller in size than the foreground pixmap! 
- The opacity attribute sets the opacity of the foreground pixmap ("0" - "100"). Default is "100". 
- The xoffset and yoffset attribute offsets the foreground pixmap with the number of pixels specified. xoffset works horizontally and yoffset works vertically. Both positive and negative numbers are allowed. Default is "0" on both. 

<combine [degrees="90"] pix1="PIXMAP1" pix2="PIXMAP2" /> blends two pixmaps together half-by-half. 
- A pixmap can either be a previously made pixmap (made with <pixmap></pixmap> or <pixmap_from_self></pixmap_from_self>), one of the previously loaded pixmaps (<pixmap_from_file />) or the current pixmap (simply referred to as "self"). 
- Degrees option is not yet implemented and the value will be ignored.

<alpha_mask mask="NAME" /> is used to add an alpha mask to a pixmap. It applies the alpha channel from the mask onto the pixmap. (Beware! Versions older than x.0.30 used the color channels instead of the alpha channel.)
- The mask can either be a previously made pixmap (made with <pixmap></pixmap> or <pixmap_from_self></pixmap_from_self>) or one of the previously loaded pixmaps (<pixmap_from_file />). 

<colorize color="COLOR" /> makes the pixmap one colored. In difference to <fill color="COLOR"/>, it doesn't change the alpha value of the pixmap. This is useful for making one colored silhouettes of icons.  
- The color should be a # and a six-digit hex number eg. "#FFFFFF" for white, or a user customizable color ("color1" to "color8").



SPEED UPS?
You can speed up the theme a bit by doing some things (beware that I have not actually tested this to know if the speed improvements are big enough to be noticeable):
1) Put your <pixmap></pixmap> within <if></if>
If you have a pixmap that will be used only for, eg. type="mouse_over" it's unnecessary to make it every time the button_pixmap is redrawn. By putting the pixmap within a <if type="mouse_over></if> it will only be made when it's actually used.

2) I haven't tested this but I would guess that <combine /> and <alpha_mask /> are the slowest commands. Using alpha masks on a pixmap you import can sometimes be avoided by applying the alpha mask directly in gimp before you add the picture to the theme.

3) Keep your pixmaps reasonably small. You don't need a pixmap that is 200x100 pixels large. Who wants a panel that is 100 pixels high? It uses more memory and more shrinking only makes your pixmap look blurrier (and if you want more blur apply it in gimp or something instead of having dockbarx do the resizing). Don't overdo it, of course, up-sized pixmaps always looks worse than down-sized, but think about what the largest size your theme is meant to be used in should be and don't make your pixmaps larger than that.

3) KISS! Keep It Simple Stupid! Dockbarx is meant to be used every day. That fancy stuff you add might look cool for a while but in the long run subtle effect might be less irritating. And less extra code also means less used cpu cycles.