This is an article about how to theme Metacity. It is a work in progress, and I have had to dig deeply to find some answers; I may well have made mistakes and I welcome corrections and suggestions.

GNOME lets you theme a bunch of different things, but we're only talking about window border themes here, which some people call Metacity themes; Wikipedia begins a sentence with "Despite the incomplete state of Metacity theme development documentation", and though there is documentation in the source, apparently not many people find it, and it's written more for programmers than theme designers. Glynn Foster also wrote a very good introduction to Metacity themes ([de]) six years ago, but things have changed a little since then. Metacity themes can also be used by Compiz, and perhaps by other window managers for all I know.

So, a Metacity theme is a set of instructions about how to "decorate" (draw the borders around) a window. Presumably you don't want to style all windows identically, so the format lets you specify details for different kinds of window:


Every window must be in exactly one of these states: normal, dialog, modal dialog (i.e. a dialogue which means you can't interact with the rest of the program while it's up), menu (torn off from the main application, not that people do that much these days), utility (that is, palettes and toolboxes and things), and border. X also allows a window to explicitly ask to be undecorated, but of course we don't provide for those in a list of decoration instructions.


Every window is either the active window (which X people call "focused"), or it isn't.


Every window is either (fully) maximised (horizontal and vertical only don't count), or it isn't.


Every window is either rolled up to show just its titlebar (which techies call "shaded" for some reason I can't fathom), or it isn't.

  • If a window is not fully maximised and not shaded, it either allows horizontal resizing, or it doesn't.
  • If a window is not fully maximised and not shaded, it either allows vertical resizing, or it doesn't.