What's in the file

The files must be called either

  • ~/.themes/N/metacity-1/metacity-theme-V.xml for a theme used only by you, or
  • /usr/share/themes/N/metacity-1/metacity-theme-V.xml for a theme installed for all users.

where N is the name of the theme and V is the version of the format. Version 2, introduced in October 2006, adds a few extra features, but it's rarely used. Version 1 is the original format. The formats are fixed once they're stable for both backwards and forwards compatibility; new features can't be added without introducing a new version number, which is why improvements come out rarely and in large clumps. metacity-1 in the names is a fossil and doesn't mean version 1 of anything.

The metacity-theme-V.xml files are GMarkup files, which are very similar to XML. For now, you actually have to write these in a text editor or something; you can either start with a blank page, or modify a theme someone else has made. (I am thinking of writing a general theme editor program, but that'll have to wait until I've reduced Metacity's open bug queue a little.) If you want to see a fully-fledged one, you can look at the current version of "Atlanta", one of the simplest themes, but even that is quite complicated-looking at first.

So, let's talk about what actually goes inside the files. As in any XML file, <!-- … > are comments. At its most basic, it would go:

<!-- Helper stuff: -->
<info …> <!-- to be explained -->
<constant …> <!-- maybe; to be explained -->

<draw_ops …> <!-- maybe; to be explained -->

<!-- Things we build the top level onto: -->
<frame_geometry …> <!-- to be explained -->

<frame_style …> <!-- to be explained -->
<frame_style_set …> <!-- to be explained -->

<!-- And the top level: -->

<window type="normal" style_set="…" />
<window type="dialog" style_set="…" />
<window type="modal_dialog" style_set="…" />

<window type="menu" style_set="…" />
<window type="utility" style_set="…" />
<window type="border" style_set="…" />