The eXperience engine

(More info may be found at http://benjamin.sipsolutions.net/Projects/eXperience)

The eXperience engine is an engine, that aims to be very flexible. Currently it only supports drawing pixmaps, but in the long term I would like to add features such as drawing SVG.

Features

First of all I would like you to give an overview, of what is possible with the eXperience engine. The engine is pixmap based, and can edit the pictures on the fly (the editing is cached, so don't worry for speed there). But unfortunately it is easy to create very slow themes with this engine, if you are not careful.

Well now to a list of features

Image editing:

• modify the colors to match GTK colors (ie. fg[NROMAL])
• rotate images
• mirror images
• change the opacity
• change the saturation
• change the brightness
• pixelate the images (checkerboard)

Groups can inherit from each other (more on groups later)

Groups can be changed in the same ways as images (except for pixelate). Changing the opacity is pretty slow though. (everything else has no speed penalty)

The engine is able to stack multiple images on top of each other, to create the final widget.

Groups

For every drawing operation done by gtk, one group will be selected by the engine (or if none is found, the default engine will be used).

A group groups together the different drawing operations. The following example defines a group named "button_normal".

   1 group "button_normal" {
   2         function        = BOX
   3 
   4         fill 10 { #fill the background
   5                 color                   = bg[NORMAL]
   6         }
   7 
   8         image 20 {
   9                 file                    = "button_border.png" #red image
  10                 recolor "#ff0000"       = bg[NORMAL]
  11                 brightness              = -0.5
  12                 border                  = { 2, 2, 2, 2 }
  13                 draw_components         = BORDER
  14         }
  15 }

In line one the group starts, and the name is given. In line two the engine is told, to draw this group only if the function used is BOX.

The rest of the group are definitions for drawing. Line 4 to 7 defines a fill, and line 8 to 15 an image. Note that the both the image and fill have a number. This number is used to sort them inside the group. They are also important for inheriting from other groups.

As you can see, a group consists of the following information:

• when the group may be drawn
• what has to be drawn
• and some changes that apply to the group as a whole (mirror, saturation).

Inheriting

It is possible for one group to inherit data from another. (Tip: Create some template styles, that you can reuse throughout the theme)

The above defines how to draw a normal button, but of course we also want a prelight.

   1 group "button_prelight" = "button_normal" {
   2         #function       = BOX not needed, because it is inherited
   3 
   4         state           = PRELIGHT
   5 
   6         # make the whole button a little lighter
   7         brightness      = 1.2
   8 }
   9 
  10 group "button_normal" {
  11         function        = BOX
  12 
  13         fill 10 { #fill the background
  14                 color                   = bg[NORMAL]
  15         }
  16 
  17         image 20 {
  18                 file                    = "button_border.png" #red image
  19                 recolor "#ff0000"       = bg[NORMAL]
  20                 brightness              = -0.5
  21                 border                  = { 2, 2, 2, 2 }
  22                 draw_components         = BORDER
  23         }
  24 }

As you can see we did not need to change a lot to create the prelight of our button. The only difference is that it is drawn a little brighter. The group "button_prelight" is defined before the "button_normal" group. This is because the engine uses the first matching group it finds. Group "button_normal" does not specify a state, so it will match any state. The group "button_prelight" will on the other hand only be drawn, if the state is PRELIGHT. So to prevent the engine from finding the "button_normal" group first, and drawing it, we define the "button_prelight" group earlier in the style.

Note that groups can inherit from other groups that are defined later in the theme.

This document is not yet done. For more information, please visit http://benjamin.sipsolutions.net/Projects/eXperience/HowTo. If you have questions you can also mail benjamin@sipsolutions.net or visit #gnome-art on irc.gnome.org and talk to benzea.

Oh, and if someone thinks that this needs to be completed, please feel free to hit^Wtell me ...