Colours are terribly important part of creating an attractive theme, but I’ve never seen a list of what syntax Metacity understands, let alone an explanation. here’s what I’ve learned.
Metacity accepts X11 hex RGB colours, much like HTML does. Thus, #FFFFFF is white, #ffff80 is a pale yellow, #484 is a darkish grey-green, etc.
Metacity accepts colour names defined in the standard X11 rgb.txt file, again much like HTML does. Thus, you can use colours like YellowGreen and DarkSlateBlue. You’ll want to checkout the Wikipedia article for details.
These are colours set by the user’s currently-active GTK theme. They are all of the form:
gtk:part[STATE]
part must be one of the following values:
fg: The foreground of the contents of controls accepting input - text in a text-entry, items in a list, etc. With the SELECTED state, returns the foreground colour of selected items.bg: The background of the contents of controls accepting input. With the SELECTED state, returns the background, accent colour of selected items.text: The foreground of controls not accepting input - for example, text on buttons, labels, pop-up lists, etc. Usually used with the NORMAL, PRELIGHT, and INSENSITIVE states.text_aa: The only documentation I can find says “halfway between text and base”.base: The background of controls not accepting input. light: A lighter shade of the base colour, used for drawing the 3D effect on buttonsmid: A medium shade of the base colour, similar but not identical to the originaldark: A darker shade of the base colour, used for drawing the 3D affect on buttonsSTATE must be one of the following values:
NORMAL: The normal state of controls.PRELIGHT: When the mouse pointer is moved over a control, it “lights up” to highlight exactly which control would be affected by a click. Much like the :hover selector in CSS.ACTIVE: While a button is actually being held down, it takes on a darker appearance. Much like the :active selector in CSS.SELECTED: Things that have been explictly selected by the user, like text in a text-box, file icons in a file-manager or cells in a spreadsheet. I’m not sure how an ordinary button or frame control might possibly become SELECTED; fg and bg are the only really useful parts that can be used with this state.INSENSITIVE: Controls that cannot be activated or edited - usually called “disabled”. Often a paler, less saturated set of the NORMAL colours.All combinations of part and state are allowed, but not all combinations are visually distinct in all themes - for example, some themes only change the text colour of INSENSITIVE controls, so colours based on the other parts of the INSENSITIVE state would wind up looking exactly like the same parts of the NORMAL state. The parts and states are defined in terms of the default “Raleigh” theme; you’ll want to check it out to get a better idea of how the various parts and states interact.
More potentially useful information: These colours are all stored in the GTK+ “Style” object, you might be able to find out more information by looking for that.
Metacity can calculate new colour values from existing colour values at runtime. This is mostly useful for generating colours based on GTK+ theme colours, but it works with any of the colour syntaxes mentioned above. There are two composite colour operations Metacity understands:
blend/background/foreground/alpha
…where both background and foreground should be colours, and alpha should be a number between 0 and 1. The resulting colour is partway between the background and foreground colours - for example, blend/black/white/0.75 produces the colour #BFBFBF.
shade/base/factor
…where the base argument should be a colour, and the factor argument should be a number - numbers less than 0 make the result black, numbers between 0 and 1 make the colour darker, 1 leaves the colour alone and numbers greater than 1 make the colour lighter (there’s no specific maximum number; exactly how much you can lighten a particular colour depends on how light it was to begin with).
A technical note: the shade operation seems to be implemented with gtk_style_shade(), which isn’t described in any GTK+ documentation I can find, and is listed in the “private API” section of gtk/gtkstyle.h.