Tutorial: Transform the icons on the Xfce panel

Online documentation for transforming icons (and other objects) on the Xfce panel is a bit hard to find. In this post, I’ll demonstrate an approach to this task with an example: We’ll transform the power manager (“battery”) icon in the system tray. The end result won’t be pretty, but we’ll have explored some of the GTK+ transforms available to us.

First, let’s quit the panel and restart it in GTK interactive debug mode:

xfce4-panel -q && GTK_DEBUG=interactive xfce4-panel

(Ignore any errors and warnings in the terminal, which may be due to problems with our current theme.)

Several windows open: a wrapper-2.0 window for each of the objects on the panel. We can discover which wrapper-2.0 window corresponds to the “battery” icon in a couple of ways:

  • Click the WrapperPlug object (or any other object) in the Object tree and the corresponding object will flash briefly in the panel.
  • Expand the WrapperPlug object in the Object tree and look for a PowerMangerButton.

Having found the window we need, we can close all of the other wrapper-2.0 windows.

Expand the Object tree completely and we see at the innermost level a GtkImage which is a descendant of the PowerMangerButton:

This GtkImage is our “battery” icon.

Notice that some of the Objects in the hierarchy have Names, which allow us to reference these objects (and their descendants) with CSS selectors. For example, this CSS selector references our “battery” icon:

#xfce4-power-manager-plugin image

Here is a comprehensive (perhaps overwhelming) list of the CSS properties we can modify for objects belonging to each of the many GTK+ base classes:


Of particular interest to us are the Icon Properties, listed in a table nearly halfway down the page:


Most useful to us is the -gtk-icon-transform property. Possible transforms are listed below the Icon Properties table. These transforms are a subset of the transforms provided by standard CSS functions:


Transforms can be combined with each other and grouped with other GTK+/CSS properties within CSS rules.

The CSS tab of the wrapper-2.0 window provides a convenient way to experiment with CSS rules for the objects in our current hierarchy of GTK+ objects. For example, let’s copy the code below into the CSS tab:

You can type here any CSS rule recognized by GTK+.
You can temporarily disable this custom CSS by clicking on the “Pause” button above.

Changes are applied instantly and globally, for the whole application.

#xfce4-power-manager-plugin image {
	-gtk-icon-theme: 'Adwaita';
	-gtk-icon-transform: scale(0.75) rotate(90deg) translateY(-1px);
	color: red;
	background-color: yellow;

Our new rule begins by selecting the “battery” icon. It then provides these instructions:

  • Substitute the “battery” icon from the Adwaita icon theme for the “battery” icon from our system’s current icon theme. (All other panel icons continue to use the current icon theme.)
  • Scale the icon to 75% of its normal size.
  • Rotate the icon clockwise by 90 degrees.
  • Center the icon by nudging it to the right by 1 pixel. (Explanation: When we rotated the image clockwise, we also rotated the coordinate system clockwise. Whereas the positive y axis originally pointed downward, it now points to the left. So a nudge to the right is now a nudge along the y axis in the negative direction.)
  • Set the icon’s color to red.
  • Set the icon’s background color to yellow.

We immediately see the (ugly) end result in the panel:


The CSS tab of the wrapper-2.0 window provides a Download button for saving our experimental rules to a file. Ultimately, though, we’ll copy our new CSS rules to this file, which makes them permanent:


Unfortunately, I don’t know of a clean way to end the GTK debug session. Pressing Ctrl+C in the terminal does the trick, but causes the panel to disappear. However, we can log out and log in again to restore the panel, which will now be drawn according to any rules we have saved in gtk.css.