1. The engine

The pixmap (or pixbuf engine) engine allows relatively low level theming of the different widgets. Unlike engines like Clearlooks , Redmond, etc. pretty much every aspect of the interface can be modified from the theme. At the same time the burden is pretty high as creating a consistent theme can be a lot of work.

There are some limitations as some hacks are not possible, and information is not always accessible to the theme. An example of this are right to left languages, which result in swapped spinbuttons. Another limitation is that all widgets have a fixed color as they are drawn using pixmaps.

1.1. Overview over the theming

More complex GTKRCs may be needed to be able to create complete themes. Reading ../../GtkThemes is advised, as a it is neccessary to understand how styles, merging and matching works. (Some example to merging would be good on this page.)

1.2. GTK+ drawing primitives and the pixmap engine

The pixmap engine usually just exposes the GTK+ drawing primitives directly. There are only a couple of exceptions to this. GTK+ abstracts all drawing into a number of drawing functions. There are some common arguments like state or detail, and others that only exist for some functions. Some functions also need additional information like the orientation of the widgets.

The following functions exist in the pixmap engine:

The different arguments and their possible values:

This is a placeholder until I know more about this.

style "NAME-scrollbar" {
    engine "pixmap" {
        image {
            function = SLIDER
            orientation = HORIZONTAL
            recolorable = TRUE # what does that mean? it's not implemented!
            file = "nf_slider-h.png"
            border = { 10, 10, 0, 0 } # = {Left, Right, Top, Bottom} 
            stretch = TRUE # this stretches the image
            overlay_file = "thumb-h-scrollbar.png"
            overlay_stretch = FALSE
        }
        ...
    }
}
class "GtkScrollbar" style "NAME-Scrollbar"

This applies the PixmapEngine to the style above.

This is a lot of stuff that isn't obvious from looking at the resource file API so here's what I know. The 'engine "pixmap"' bit says to use the theme engine named "pixmap" to draw widgets of this style. An engine is a kind of module that Gnome can load to do theme drawing. The only one I've seen so far is pixmap and it is a tad slow so don't go overboard here.

• The 'function' line tells the engine what part of the engine you're specifying parameters for. In our example we're describing a horizontal scrollbar slider.
• The 'orientation' specifies direction horizontal/vertical

• The 'recolorable' line means uh... umm... nothing, it is ignored -- -- BenjaminBerg 2005-06-05 12:21:55

• The 'file' line specifies an image to use.
• The 'border' line defines the border widths in this manner {Left, Right, Top, Bottom} (described in detail below).
• The 'stretch' line says to stretch the image to fit the widget.
• The 'overlay_file' line defines another image to lay on top of the other one.
• The 'overlay_stretch' line says whether to stretch the overlay image.

(to be continued...)

Complete GtkVScrollbar theming sample:

style "my-vscrollbar" {
    engine "pixmap"
    {
        image
        {
                function = SLIDER
                orientation = VERTICAL
                file = "scrollbar_slider.png"
                border = { 0, 0, 10, 10 } # = {Left, Right, Top, Bottom} 
                stretch = TRUE # this stretches the image
        }
        image
        {
                function = BOX
                orientation = VERTICAL
                file = "scrollbar_background.png"
                border = { 0, 0, 32, 32} # = {Left, Right, Top, Bottom} 
                stretch = TRUE # this stretches the image
        }
        image
        {
                function = BOX
                detail = "vscrollbar"
        }
        image
        {
                function = ARROW
                # override all states
                # consider adding per state image block
                # state = NORMAL
                # state = INSENSITIVE
                overlay_file = "scrollbar_arrow_up.png"
                overlay_stretch = FALSE
                arrow_direction = UP
        }
        image
        {
                function = ARROW
                # override all states
                # consider adding per state image block
                # state = NORMAL
                # state = INSENSITIVE
                overlay_file = "scrollbar_arrow_down.png"
                overlay_stretch = FALSE
                arrow_direction = DOWN
        }
    }
}
class "GtkScrollbar" style "my-vscrollbar"

How to theme GtkWindow with a background image:

style "my-background"
{
   engine "pixmap"
   {
        image
        {
                function = FLAT_BOX
                file = "background.png"
                border = {10, 10, 10, 10}
                detail = "base"
        }
   }
}

class "GtkWindow" style "my-background"

Or if you have an enclosing GtkFrame, and want only theming the outer of the window:

(02:45:04 PM) benzea: which one could consider a good thing, because scaling is relatively slow

style "my-background"
{
   engine "pixmap"
   {
        image
        {
                function = SHADOW
                file = "background.png"
                border = {10, 10, 10, 10}
        }
   }
}

class "GtkFrame" style "my-background"

How to theme a GtkPaned with images:

style "my-paned"
{
  GtkPaned       ::handle_size = 15

  engine "pixmap"
  {
          image
          {
                function = HANDLE
                overlay_file = "handle.png"
                overlay_border = {0, 0, 0, 0}
                overlay_stretch = FALSE
                orientation = HORIZONTAL
                file = "handle_background.png"
                border = {0, 0, 0, 0}
                stretch = TRUE
          }
  }
}

class "GtkPaned" style "my-paned"

How to theme a GtkHSeparator with an image:

style "my-hseparator"
{
  engine "pixmap"
  {
        image
        {
                function = BOX
                file = "hseparator.png"
                border = {0, 0, 0, 0}
                stretch = TRUE
        }
  }
  GtkHSeparator:: wide-separators = 1
  GtkHSeparator:: separator-height = 10
}

class "GtkHSeparator" style "my-hseparator"