Xfwm4 theme how-to

Xfwm4, Xfce4's native window manager uses a simple yet flexible pixmap based theme engine using images in .xpm format. Xfwm4 also uses a text file for other configuration options (see themerc section). Further to this you can also make a theme pick up gtk theme colours which will be covered in the gtk color pickup section of the document.

Figure 1 - A sample window

Themes locations

In Xfwm4 version 4.0, the themes are searched in the following directories:

User's home dir /.themes/xfwm4/theme_name (e.g.: "/home/joe/.themes/xfwm4/b5")
System's shared data directory /xfwm4/theme_name (e.g.: "/usr/share/xfwm4/themes/b5")

In Xfwm version 4.2, the theme location is in line with the standard, searched in the following directories:

User's home dir /.themes/theme_name/xfwm4 (e.g.: "/home/joe/.themes/b5/xfwm4")
System's shared data directory /themes/theme_name/xfwm4 (e.g.: "/usr/share/themes/b5/xfwm4")

Titlebar decorations

As windows can be in either active(focused) or inactive(unfocused) states for which xfwm4 use pixmaps named accordingly e.g. title-1-active.xpm and title-1-inactive.xpm.

For title bar decorations, xfwm4 uses 5 pixmaps named title-1-active.xpm to title-5-active.xpm with top-left-active.xpm and top-right-active.xpm making up the corners on each end as per figure 1 below.

Figure 2 - The pixmaps that compose the whole window

The same naming convention is true for unfocused windows with the word inactive substituted.e.g. title-1-inactive.xpm

Title text colour and shadow options, alignment etc are set in the themerc file (detailed in the themerc section).

Window Sidebars and bottom

Each side of a window is made up of two pixmaps. The pixmaps on the left side are named left-active.xpm and bottom-left-active.xpm. with the right side (of course) being made up of right-active.xpm and bottom-right.active.xpm.

The Window bottom grab bar is made up of bottom-active.xpm and bottom-inactive.xpm pixmaps which will be repeated to fit as the window is resized.

N.B These pixmaps also make up the mouse grab handles so keep that in mind when deciding how many pixels wide they should be (particularly the bottom-left and bottom right pixmaps which make up the main resize handles on the windows).

Xfwm4 Buttons

Xfwm4 can use up to six action buttons - stick (sticky windows), menu, shade, hide, maximize and close.

Buttons have active (focused), inactive (unfocused) and pressed states. as per figures 3 below:

Figure 3 - Xfwm4 button states

Xfwm4 can also used "toggled" buttons to indicated whether buttons are toggled on or off - figure 4.

Figure 4 - Stick buttons with extra toggled buttons

Themerc file

To set features such as title text colors, "button_spacing" and "button_offset" etc. xfwm4 uses an text file called "themerc" kept in the theme folder that contains the pixmaps.

Button layout

It is also possible to "fix" button layouts for themes that use a particular button layout. - though it should be mentioned that forcing a special button layout or a title alignment in the theme, and thus reducing user's options, should be avoided (unless the theme really requires that, such as b5 theme mentioned below)

# button_layout :
#    O = Option menu
#    T = Stick
#    H = hide
#    S = shade
#    M = maximize
#    C = close
#    | = title
button_layout=OTS|HMC

A working example of this is the "B5" theme which only uses the close button. i.e. the entry "button_layout=C|" in the themerc file.

Title width

Another setting that needs to be set from the "themerc" file is the "title_full_width" parameter. This boolean value determines how the pixmap are arranged in the title bar.

When set to "true", the center pixmap is repeated so that it fills the entire window width :

When set to "false", the center pixmap is repeated just enough so that the title fits :

Text shadow

A shadow can be added to the title text by setting the boolean value "title_shadow_active" for the focused window, and "title_shadow_inactive" for the other unfocused windows.

Title offset

The title text position can be adjusted to fit the theme design by using the offset values. The horizontal and vertical values can be adjusted by using the following settings:

title_horizontal_offset
title_vertical_offset_active
title_vertical_offset_inactive

Button offset and spacing

Simlilarily, the buttons can be shifted horizontally by using the "button offset" setting. It's worth noting that the value is relative to the corresponding application window border, not the frame border.

The "button_spacing" value gives the number of pixels between each button.

Gtk Color pickup

As you have no doubt noticed when using Xfwm4's default theme it is possible to make themes "pick-up" gtk theme colours. It's not just running the gimp and draw the buttons. Most themes use a color symbol table. That means the xpm file must be opened and edited by hand.

The color symbols are as follow :

active_text_color	Text color on title for active window
inactive_text_color	Text color on title for inactive window
active_border_color	Very rarely used usually set to black
inactive_border_color	Idem
active_color_1	Background color for active title
active_hilight_1	Lighter color for active title for 3D look
active_shadow_1	Darker color for active title for 3D look
active_mid_1	Slightly darker color for active title
active_color_2	Background color for active window
active_hilight_2	Lighter color for active window
active_shadow_2	Darker color for active window
active_mid_2	Slightly darker color for active window
inactive_color_1	Background color for inactive title
inactive_hilight_1	Lighter color for inactive title for 3D look
inactive_shadow_1	Darker color for inactive title for 3D look
inactive_mid_1	Slightly darker color for inactive title
inactive_color_2	ackground color for inactive window
inactive_hilight_2	Lighter color for inactive window
inactive_shadow_2	Darker color for inactive window
inactive_mid_2	Slightly darker color for inactive window

The symbols get replaced by the actual color values at runtime so that the window borders inherits GTK theme colors automatically.

Xpm file format used natively by xfwm4 is no more than a plain text file that can be edited with your favorite text editor.

From Wikipedia, the free encyclopedia.

XPM (X PixMap) is an ASCII image format used by the X Window System. It was created in 1989 by Daniel Dardailler and Colas Nahaboo working in Inria Laboratories, France, and was later enhanced by Arnaud Le Hors. It is intended primarily for creating icons, and supports transparent color. It has a simple structure, deriving from the earlier XBM syntax. It can be created and manipulated using any text editor and can be included in a C language file.

Therefore, if you open an xpm file with your favorite text editor, you'll see something like this:

/* XPM */
static char * title_2_active_xpm[] = {
"5 21 10 1",
"       c None",
".      c #000000",
"+      c #FFFFFF s active_hilight_2",
"@      c #D5D6D5 s active_color_2",
"#      c #4B58A2 s active_shadow_1",
"$      c #525FAB s active_color_1",
"%      c #848FD6 s active_mid_1",
"&      c #B4BAB4 s active_mid_2",
"*      c #949594 s active_shadow_2",
"=      c #FFFFFF s active_hilight_1",
".....",
"++++#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@#",
"@@@@@",
"@@@@@"};

Not going too deep into the details of the XPM format, an XPM image is made of different sections, the values that describe the format of the image, the colors that compose the image, the pixels (and there is also the extensions, but it's safe to ignore them for now)

A character is assigned to each color of the image (if the image has more colors than available charaters, then more than a single character can be assiged to a colors). If a color symbol is specified, the given color will be ignored and replaced by the corresponding color in the color symbol table.

To get the gtk colors applied to your theme, you need to edit the XPM files and add the proper color symbols to the color definition table.

"       c None",
".      c #000000",
"+      c #FFFFFF",
"@      c #D5D6D5",
"#      c #4B58A2",
"$      c #525FAB",
"%      c #848FD6",
"&      c #B4BAB4",
"*      c #949594",
"=      c #FFFFFF",

must be changed to

"       c None",
".      c #000000",
"+      c #FFFFFF s active_hilight_2",
"@      c #D5D6D5 s active_color_2",
"#      c #4B58A2 s active_shadow_1",
"$      c #525FAB s active_color_1",
"%      c #848FD6 s active_mid_1",
"&      c #B4BAB4 s active_mid_2",
"*      c #949594 s active_shadow_2",
"=      c #FFFFFF s active_hilight_1",

As a matter of fact, "thinking" of the gtk colors as early as drawing the theme can save a lot of time in this phase. If you use the exact same color across all the pixmaps, you can use the Search/Replace functionnality of the text editor to add the color symbols. You could even use a tool such as "sed" to perform mass changes in all the XPM files of the theme.

Xfwm 4.2 new functionality

As simple as it is, the color symbol replacement table of the XPM format is not powerfull enough to achive the nice color gradients seen in most recent themes.

Xfwm 4.2 includes yet another functionality that gives real nice result while being still compatible with the previous theme format: It composes the final image from the XPM file and it colors replacement table, and another PNG file with transparency, if present.

Figure 5 - PNG transparent images get layered on top of the XPM image

The names of the PNG files are identical to the names of the corresponding XPM files, with the ".png" file extension (ie title-1-active.png, top-right-inactive.png, etc.). The PNG file is by no mean required, if it's not present, xfwm4 won't complain, but if there is a PNG image of the same name as the XPM image, and if that PNG has an alpha channel (ie, it has semi-transparent pixels) then the PNG image will be automatically layered on top of the XPM image to produce the final image.

This technique has several advantages:

It's fairly simple from a theme designer point of view, most people are working with similar techniques when compising themes with tools such as The GIMP.
It's backward compatible with xfwm4 from Xfce 4.0, the PNG files are just ignored by xfwm4 4.0.

Conclusion

I hope this small "how-to" for creating themes for xfwm4 will help you design your own themes. It would be great if you could share your themes with others on www.themedepot.org (which is the prefered site for xfce related themes) or from themes.freshmeat.net.

This how-to has been started by Drewbian (drewbian at tsn dot cc) and later modifed by Olivier Fourdan (fourdan at xfce dot org).