Themes are in a simple XML-subset format. There are multiple versions

of the theme format, and a given theme can support more than one format.

Version 1:     THEMEDIR/metacity-1/metacity-theme-1.xml

  (original metacity format)

Version 2:     THEMEDIR/metacity-1/metacity-theme-2.xml

Version 3:     THEMEDIR/metacity-1/metacity-theme-3.xml

The subdirectory name is "metacity-1" in all versions.

As you might expect, older versions of metacity will not understand

newer theme formats. However, newer versions will use old themes.

Metacity will always use the newest theme format it understands that

the X server supports. Some format versions are only supported if you

have the right X server features.

Each format *requires* the corresponding filename. If you put version

2 format features in the metacity-1/metacity-theme-1.xml file, then

metacity will get angry.

This document has separate sections for each format version. You may

want to read the document in reverse order, since the base features

are discussed under version 1.

New Features in Theme Format Version 3.5

========================================

Add support for app-menu button in window decorations. This was only

used by Mutter and here is only to support this Theme Format Version.

New Features in Theme Format Version 3.4

========================================

An additional color type is added to pick up custom colors defined

in the GTK+ theme's CSS:

  gtk:custom(name,fallback)

where <name> refers to a custom color defined with @define-color in

the GTK+ theme, and <fallback> provides an alternative color definition

in case the color referenced by <name> is not found.

New Features in Theme Format Version 3.3

========================================

Add two additional button background functions - left_single_background and

right_single_background - for button groups with just a single button.

There are now additional frame states to style left/right tiled windows

differently ("tiled_left", "tiled_right", "tiled_left_and_shaded",

"tiled_right_and_shaded")

New Features in Theme Format Version 3.2

========================================

A new window type 'attached' is added for modal dialogs which are

attached to their parent window. (When the attach_modal_dialogs preference

is turned on.) If no style is defined for the 'attached' window type,

the 'border' window type will be used instead.

New Features in Theme Format Version 3.1

========================================

Additional predefined variables are added for positioning expressions:

  frame_x_center: the X center of the entire frame, with respect to the

      piece currently being drawn.

  frame_y_center: the Y center of the entire frame, with respect to the

      piece currently being drawn.

The <title/> element now supports an "ellipsize_width" attribute. When

specified, this gives a width at which to ellipsize the title. If not

specified, the title will simply be clipped to the title area.

New Features in Theme Format Version 3

======================================

Format version 3 has exactly one new feature; any element in the file

can now have a version attribute:

  version="[<|<=|=>|>] MAJOR.MINOR"

(< and > should be to be entity escaped as < and >). If this

version check is not met, then the element and its children will be

ignored. This allows having alternate sections of the theme file for

older and newer version of the Metacity theme format.

When placed on the toplevel <metacity_theme> element, an unsatisfied

version check will not just cause the contents of the file to be

ignored, it will also cause the lookup of a theme file to proceed on

and look for an older format 2 or format 1 file. This allows making a

metacity-theme-3.xml file that is only used the format version 3.2 or

newer is supported, and using metacity-theme-1.xml for older window

managers.

New Features in Theme Format Version 2

======================================

The optional attributes rounded_top_left, rounded_top_right,

rounded_bottom_left and rounded_bottom_right on <frame_geometry>

should now be the radius of the corner in pixels. You may still use

the values "false" for 0 and "true" for 5, which means v1 values will

still work just fine.

<frame_geometry> has a new optional attribute, hide_buttons. If this

is true, no buttons will be displayed on the titlebar.

Anywhere you can use a positive integer, you can use an integer constant.

As well as constant integers and reals, you may define constant colours,

thus:

  <constant name="RevoltingPink" value="#FF00FF"/>

  <constant name="Background" value="gtk:bg[NORMAL]"/>

<frame_style> has two new optional attributes, background and alpha.

If you specify alpha, you must specify background. background is a

colour used for the background of the frame. alpha is the transparency

as a real between 0.0 and 1.0. If the current X server does not support

alpha channels, the value is ignored.

The filename attribute of <image> may begin with "theme:". If so, the

rest of the string is the name of a theme icon. The 64x64 version of the

icon is used, except for fallback mini_icons, which use the 16x16 version.

This does not affect ordinary resizing. For example:

  <button function="close" state="normal">

    <draw_ops>

      <include name="active_button"/>

          width="width-4" height="height-4"/>

    </draw_ops>

  </button>

<menu_icon>s are parsed but ignored.

Fallback icons can be specified using <fallback>. There are two

optional arguments, icon and mini_icon. The values of these arguments

are identical to that of the filename attribute of <image>. Fallback

icons are used when a window does not supply its own icon. If a fallback

icon is not specified with <fallback>, Metacity will use a built-in

icon, as in metacity-theme-1.

The <arc> element, as well as the original start_angle and end_angle

attributes, may be given from and to attributes. The values of these

attributes are given in degrees clockwise, with 0 being straight up.

For example:

      x="0" y="5" width="15" height="15"/>

<frame state="shaded"> may now take an optional resize attribute, with

the same interpretation as the resize attribute on <frame state="normal">.

If this attribute is omitted for state="shaded", it defaults to "both".

(If it is omitted for state="normal", it remains an error.)

In addition to the four <button> functions which are required in

metacity-theme-1, there are six new functions in metacity-theme-2:

shade, unshade, above, unabove, stick and unstick.

Overview of Theme Format Version 1

==================================

<metacity_theme>

<info>

  <name>Foo</name>

  <author>Foo P. Bar</author>

  <copyright>whoever, 2002</copyright>

  <date>Jan 31 2005</date>

  <description>A sentence about the theme.</description>

</info>

     determines whether the title text height is included in the 

     height calculation. if not specified, defaults to true.

     It also has an optional text_size="medium" attribute

     (same sizes as with Pango markup, xx-small thru medium thru

     xx-large) 

     Finally it has optional args rounded_top_left=true, 

     rounded_top_right=true, rounded_bottom_left=true,

     rounded_bottom_right=true.

     -->

<frame_geometry name="normal" has_title="true" title_scale="medium">

  <distance name="left_width" value="6"/>

  <distance name="right_width" value="6"/>

  <distance name="bottom_height" value="7"/>

  <distance name="left_titlebar_edge" value="6"/>

  <distance name="right_titlebar_edge" value="6"/>

  <distance name="button_width" value="17"/>

  <distance name="button_height" value="17"/>

  <aspect_ratio name="button" value="1.0"/>

  <distance name="title_vertical_pad" value="4"/>

  <border name="title_border" left="3" right="12" top="4" bottom="3"/>

  <border name="button_border" left="0" right="0" top="1" bottom="1"/>

</frame_geometry>

<frame_geometry name="borderless" parent="normal">

  <distance name="left_width" value="0"/>

  <distance name="right_width" value="0"/>

  <distance name="bottom_height" value="0"/>

  <distance name="left_titlebar_edge" value="0"/>

  <distance name="right_titlebar_edge" value="0"/>

</frame_geometry>

     constant names must start with a capital letter.

  -->

<constant name="LineOffset" value="3"/>

     these draw-op lists can also be placed inline. 

     Positions/lengths are given as expressions.

     Operators are: +,-,*,/,%,`max`,`min`

     All operators are infix including `max` and `min`, 

      i.e. "2 `max` 5"

     Some variables are predefined, and constants can also 

     be used. Variables are:

       width - width of target area

       height - height of target area

       object_width - natural width of object being drawn

       object_height - natural height of object being drawn

       left_width - distance from left of frame to client window

       right_width - distance from right of frame to client window

       top_height - distance from top of frame to client window

       bottom_height - distance from bottom of frame to client window

       mini_icon_width - width of mini icon for window

       mini_icon_height - height of mini icon

       icon_width - width of large icon

       icon_height - height of large icon

       title_width - width of title text

       title_height - height of title text

    All these are always defined, except object_width/object_height 

    which only exists for <image> right now.

  -->

<draw_ops name="demo_all_ops">

  <line color="#00FF00" x1="LineOffset" y1="0" x2="0" y2="height"/>

        x1="width - 1" y1="0" x2="width - 1" y2="height" 

        width="3" dash_on_length="2" dash_off_length="3"/>

             x="0" y="0" width="width - 1" height="height - 1" filled="true"/>

       filled="false" start_angle="30" extent_angle="180"/>

  <tint color="orange" alpha="0.5" x="0" y="0" width="width" height="height"/>

            x="10" y="30" width="width / 3" height="height / 4">

         a color name like "blue" (look at gcolorsel), a hex color

         as in HTML (#FFBB99), or a color from the gtk theme 

         given as "gtk:base[NORMAL]", "gtk:fg[ACTIVE]", etc.

       -->

    <color value="gtk:fg[SELECTED]"/>

    <color value="blend/gtk:bg[SELECTED]/gtk:fg[SELECTED]/0.5"/>

  </gradient>

       image a certain color -->

         x="10" y="30" width="width / 3" height="height / 4"/>

             filled="true"

             x="2" y="2" width="width - 4" height="height - 4"/>

           x="2" y="2" width="width - 4" height="height - 4"/>

  <gtk_vline state="normal" x="2" y1="0" y2="height"/>

        x="10" y="30" width="width / 3" height="height / 4"/>

  <title color="gtk:text[NORMAL]" x="20" y="30"/>

  <include name="some_other_draw_ops"/>

       x/y/width/height/tile_xoffset/tile_yoffset -->

  <tile name="some_other_draw_ops" tile_width="10" tile_height="10"/>

</draw_ops>

<frame_style name="normal" geometry="normal">

       For each piece, a draw_ops can be given inline or referenced 

       by name. If a piece is omitted, then nothing will be drawn 

       for that piece.

       For each piece, the "width" and "height" variables in 

       coordinate expressions refers to the dimensions of the piece, 

       the origin is at the top left of the piece.

       So <rectangle x="0" y="0" width="width-1" height="height-1"/>

       will outline a piece.

    -->

  <piece position="entire_background" draw_ops="demo_all_ops"/>

  <piece position="left_titlebar_edge">

    <draw_ops>

      <line color="#00FF00" x1="0" y1="0" x2="0" y2="height"/>

    </draw_ops>

  </piece>

       entire_background: whole frame

       titlebar: entire area above the app's window 

       titlebar_middle: area of titlebar_background not considered

                        part of an edge

       left_titlebar_edge: left side of titlebar background

       right_titlebar_edge: right side of titlebar background

       top_titlebar_edge: top side of titlebar background

       bottom_titlebar_edge: bottom side of titlebar background 

       title: the title area (doesn't include buttons)

       left_edge: left edge of the frame

       right_edge: right edge of the frame

       bottom_edge: bottom edge of the frame

       overlay: same area as entire_background, but drawn after 

                drawing all sub-pieces instead of before

   -->

       each of three states: 

          normal, pressed, prelight

       and the button function or position must be provided:

          close, maximize, minimize, menu, 

          left_left_background, left_middle_background,

          left_right_background, right_left_background, 

          right_middle_background, right_right_background

       So a working theme needs 3*4 = 12 button declarations

       and a theme may have up to 3*10 = 30 button declarations

       in order to handle button-rearrangement preferences.

       (The name "function" for the attribute is from before the 

        background values existed.)

    -->

  <button function="close" state="normal" draw_ops="previously_named"/>

  <button function="menu" state="normal">

    <draw_ops>

            x="0" y="0" width="object_width" height="object_height"/>

    </draw_ops>

  </button>

</frame_style>

     In a subclass anything can be re-specified to override 

     the parent style. -->

<frame_style name="focused" parent="normal">

  <piece position="title">

    <draw_ops>

                 x="0" y="0" width="width-1" height="height-1"/>

                                      y="(height - title_height) / 2"/>

    </draw_ops>

  </piece>

</frame_style>

     Focus: yes (focused), no (not focused)

     Window states: normal, maximized, shaded, maximized_and_shaded

     Window resizability: none, vertical, horizontal, both

     Everything unspecified just does the same as

     unfocused/normal/both.

     only state="normal" needs a resize="" attribute.

 -->

<frame_style_set name="normal">

<frame focus="yes" state="normal" resize="both" style="focused"/>

<frame focus="no" state="normal" resize="both" style="normal"/>

</frame_style_set>

     Types: normal, dialog, modal_dialog, menu, utility, border

  -->

<window type="normal" style_set="normal"/>

     four types as the buttons, and GTK states

     (insensitive,prelight,normal,etc.)

  -->

<menu_icon function="close" state="normal" draw_ops="previously_named"/>

</metacity_theme>