Justifying window titles

It was said that Metacity doesn’t let you decide whether titles of windows are left-justified (as in modern versions of MS Windows) or centre-justified (as on the Mac). But actually, it’s a theme issue to decide how a title is drawn. Here’s how to change your theme from centre-justified to left-justified.

First, find out what theme you’re using. We’ll use gconftool to do this, because it’s the easiest to demonstrate.

$ gconftool -g /apps/metacity/general/theme
Human

Okay, so we’re using Ubuntu’s Human theme here (you may well be using something else, of course; substitute its name for Human in what follows). Presumably you don’t want to work on the main system version of the theme, so take a personal copy and tell Metacity to use it:

$ cp -R /usr/share/themes/Human ~/.themes/LeftHuman
$ gconftool --type=string -s /apps/metacity/general/theme LeftHuman

It will switch to the new theme, but obviously it will look identical at present.

Unfortunately, as I mentioned the other day, there’s no fancy editor for Metacity theme files: you’ll have to edit the file by hand. But it only needs to be done once. So, open ~/.themes/LeftHuman/metacity-1/metacity-theme-1.xml in your favourite editor and search for <title (“title” preceded by a less-than sign, i.e. the opening of a “title” tag in XML). You will see that any of these you find have a formula for their x attribute that involves taking widths and halving them, which screams about centring. All you have to do is change this formula to zero for all the title tags in the file.

However, in the Ubuntu Human theme they obtain a shadow effect on the letters by printing the title multiple times at different tiny offsets. For cases like these, you need to keep the offsets in order to keep the shadow effect. So you’d change
<title color="shade/gtk:bg[SELECTED]/0.75"
x="(3 `max` (width-title_width)) / 2 + 1"
y="(((height - title_height) / 2) `max` 0) + 2"/>
<title color="shade/gtk:bg[SELECTED]/0.7"
x="(3 `max` (width-title_width)) / 2 + 2"
y="(((height - title_height) / 2) `max` 0) + 2"/>
<title color="shade/gtk:bg[SELECTED]/0.4"
x="(3 `max` (width-title_width)) / 2 + 1"
y="(((height - title_height) / 2) `max` 0) + 1"/>
<title color="#ffffff"
x="(3 `max` (width-title_width)) / 2"
y="(((height - title_height) / 2) `max` 0)"/>

to:

<title color="shade/gtk:bg[SELECTED]/0.75"
x="1"
y="(((height - title_height) / 2) `max` 0) + 2"/>
<title color="shade/gtk:bg[SELECTED]/0.7"
x="2"
y="(((height - title_height) / 2) `max` 0) + 2"/>
<title color="shade/gtk:bg[SELECTED]/0.4"
x="1"
y="(((height - title_height) / 2) `max` 0) + 1"/>
<title color="#ffffff"
x="0"
y="(((height - title_height) / 2) `max` 0)"/>

and so on throughout the file.

When you’re done:

$ metacity-message reload-theme

and presto!

You might say that this is a lot of work compared to just selecting a “left justify” button somewhere, and it is, but assuming your original theme file was free software, you can distribute derivatives of it. So you should feel free to give your new left-justified version to your friends or stick it up on the web somewhere. Don’t forget to add your name and copyright in the <info> section first.

Understanding Metacity themes

cleaning windowsThis 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:

  • state: 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.
  • focused: Every window is either the active window (which X people call “focused”), or it isn’t.
  • maximized: Every window is either (fully) maximised (horizontal and vertical only don’t count), or it isn’t.
  • shaded: 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.

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:

<metacity_theme>
<!-- 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="..." />
</metacity_theme>

Matching windows

window: You see that at the top level we have a list of <window> tags, one for each window state we discussed above. The style_set argument of each of these gives the name of a frame_style_set.

frame_style_set: …tells Metacity how to draw windows according to whether they’re focused or not, maximised or not, shaded or not, and allowing resizing vertically, horizontally, both, or neither. It looks like this:


<frame_style_set>
<frame focus="F" state="S" resize="R" style="N"/>
<frame... />
...
</frame_style_set>

where:
F is yes for focused, no for unfocused
S combines the shaded and maximized flags: normal, maximized, shaded, or maximized_and_shaded
R represents resize permissions that the window gives us: none, vertical, horizontal, or both. Frame settings for maximised windows, which can’t be resized, don’t have this attribute.
N is the name of a frame_style to apply to a window which has these attributes.

A frame_style_set tag may also have a “parent” tag, which should be the name of another frame_style_set. This means that if Metacity wants to know about a kind of window which that frame_style_set doesn’t describe, it should look in the parent. Most of the more complicated tags in Metacity theme files also have a “parent” attribute which work the same way. This is particularly useful because, taken together, all the frame_style_sets in a theme file must be capable of matching every possible kind of window; if a window turns up that they can’t match, there will be an error at runtime.

Let’s recap what we’ve seen so far. The combination of a window, which matches a window’s state (normal, dialog, and so forth), with an entry in the corresponding frame_style_set, which matches its focus, shadedness, maximisedness, and resize permissions where relevant, will allow you to make a list of rules to match any window against. The next piece of this puzzle lets you specify what Metacity should do with such windows once it’s matched them.

Actually drawing stuff

frame_style: This is probably the most complicated part of the whole system. A frame_style is a series of pieces and buttons. It looks like this:

<frame_style name="..." geometry="G">
<piece position="P">
<draw_ops>
</draw_ops>
</piece>
...
<button function="F" state="S" draw_ops="D"/>
<draw_ops>
</draw_ops>
</button>
...
</frame_style>

The pieces are pieces of the window frame. When Metacity draws a window frame, it renders its various pieces always in the same order. The bolded parts are all the possible values of P:

  • the entire_background, covering the whole frame
  • the titlebar, covering the entire background of the titlebar
  • the titlebar_middle, the part of the titlebar that doesn’t touch its edges
  • the left_titlebar_edge, right_titlebar_edge, top_titlebar_edge, and bottom_titlebar_edge
  • the title, just exactly that area which is covered by the text on the titlebar
  • the left_edge, right_edge, and bottom_edge of the frame (yes, there is no top_edge: it’s identical to top_titlebar_edge, isn’t it?)
  • the overlay, which covers everything– the same as entire_background, but done last instead of first.

What Metacity draws in these pieces is decided by the theme. If a frame_style or its parents don’t specify a particular piece, nothing will be drawn for that piece. You have two ways to specify what to draw: one is that the piece tag can have a draw_ops tag inside it which lists a sequence of drawing operations in Metacity’s custom format. You might ask why we don’t use SVG; one answer is that SVG support wasn’t very strong when this format was designed, and another answer is that these days you can use SVG all you like; just include it as an image and Metacity will know what to do.

An alternative to including a draw_ops tag inside a piece tag is to add a draw_ops attribute to the piece tag. Then you can add a draw_ops tag at top level (inside the metacity_theme tag) with a name attribute, and Metacity will use that. This is useful if you use similar draw_ops over and over.

I’m not going to document draw_ops at present, because this is already very long. I will write it up later and link it from here.

The button tag tells Metacity how, but not where, to draw buttons. Buttons are drawn after all the pieces are finished, and the way to draw them is also given using draw_ops. You ought to provide buttons for all the possible kinds of button; if you don’t give one it won’t be drawn, which is unfortunate for the user who wants to use it:

  • left_left_background, left_middle_background, and left_right_background don’t represent buttons as such, but the background behind them, assuming there can be at most three buttons on the left. These days there can be more, so the extra ones also use left_middle_background.
  • right_left_background, right_middle_background, and right_right_background similarly.
  • close, minimize, maximize are the obvious original three buttons.
  • menu is the menu button you can click to get a list of actions you can perform on the window.
  • shade, above, stick are similar to the original buttons but only allowed in version 2
  • unshade, unabove, unstick are the toggled versions of these buttons. Again, version 2 only. It is not immediately apparent to me how the toggled version of maximize is generated, though I suppose I must have known at some point.

Update: The reason there are toggled versions of shade, above, and stick, and not maximize, is that by the time you get this far you’ve probably already decided whether you’re drawing a maximised window. So if you are drawing a maximised window, you can make the button called “maximize” look how you want the restore button to be; otherwise, make it look like you want the maximise button to be.

For each button tag you should also set a “state” attribute; this time the state is either normal (the way you see it most of the time), pressed, or prelight (this makes the buttons subtly light up when you hover over them). You only really need “normal”, but the others are good to have too.

The “geometry” attribute of a frame_style tag is the name of a…

Geometry

The geometry tag defines the sizes of things around the window. It is important, but not easy to explain, and again this file has gone on too long. I’ll write it up later.

Other things which lie around a file

The most important other thing in a theme file is the metadata held in the info tag. This contains a set of tags each of which contains some text explaining something about the theme itself, in a sort of Dublin Core sort of way. (Next time around, we should probably use the actual Dublin Core.) The tags are name, author, copyright, date, and description.

Version 1 of the format had a menu_icon tag at top level, which let themes specify the icons beside options in the menu you get from the menu icon. This has become redundant; the icons are taken from the icon theme! The tag can still be used in all formats, but does nothing and is deprecated.

Version 2 of the format has a fallback tag at top level, which let the theme specify what icon a window should be considered to have if it doesn’t provide an icon of its own. This should also be taken from the icon theme, if anyone fancies fixing it, and the tag should also then be deprecated. It shouldn’t be hard.

When you’re working on a theme

When you’re editing a theme, you can view it without using it on the whole desktop using
metacity-theme-viewer YourThemeName

and view it on the whole desktop using
gconftool --type=string --set /apps/metacity/general/theme YourThemeName

Whenever you change the selected theme in GConf, Metacity will load the newly-chosen theme. This is how control-center does it. But when you change a theme, as you’re working on it, you might want to ask Metacity to reload the theme which is currently used on the whole desktop to reflect your changes. You can do this using the little-known metacity-message program, with the command metacity-message reload-theme. This works by sending the ClientMessage _METACITY_RELOAD_THEME_MESSAGE to the root window, in case you’re interested.

Once you’re done with your theme, consider submitting it to the art.gnome.org site, or the gnome-look site.

The future

Please feel free to link to this so people don’t have to keep asking the basic questions and can start asking the deeper ones. One of the important deeper ones is: where should we go in the future? Since this format is becoming something of a de facto standard between window managers, should we set up some kind of freedesktop.org standards discussion? Would it be useful to spin off Metacity’s theme parsing code into a separate, LGPL-licensed library so that other applications could use it more easily?

What would a version 3 of this format look like? Could we simplify the window / frame_style_set system? (I can imagine abolishing both, and being able to write <frame_style for="normal+unfocused+maximized">... and having Metacity assume it applied to all resize permissions and shadednesses.) Maybe we should try to do everything with SVG we can? Getting more wild and handwavey, is it worth keeping XML-like? Maybe if other window managers were dealing with the files, .ini-style files would be more universally useful? Or perhaps not. And then of course we need a decent graphical editor for it. I have a few ideas, but if anyone fancies jumping in…

Photo: “Cleaning Windows”, cc-by-nc-sa, by John Harvey.

2.23.21

What is it ?
============

Metacity is a simple compositing window manager that integrates nicely with GNOME 2.

What’s changed ?
================

Thanks to Robert Escriva, Iain Holmes, Matt Krai, Thomas Thurman, and Chris Wang for improvements in this version.

– Add shadow ability for menus and tooltips (Iain) (#517442) (GNOME bug 517524)
– Fix possible crashes in compositor (Iain) (GNOME bug 534569) (GNOME bug 528787)
– Major reorganisation of compositor code (Iain)
– Initial version of XRender backend for the compositor (Iain)
– New basic public API for compositor (Iain)
– Window decoration updates colour when GTK theme changes (Robert) (GNOME bug 511826)
– Minor code cleanup for pedantic compilers (Thomas)
– Further code cleanup for pedantic compilers (Matt) (GNOME bug 526049)
– The atom list appears only once in the code (Thomas) (GNOME bug 530843)
– Don’t attempt to read attributes of invalid windows (Chris) (GNOME bug 530485)

Translations
Khaled Hosny (ar), Gabor Kelemen (hu), Kjartan Maraas (nb), Tino Meinen (nl), Theppitak Karoonboonyanan (th)

Where can I get it ?
====================

As 780eddd5a57559c6255d7d2440f73114 bz2 or 75328c77f6de4e1c5ae638f3f0a4b0b6 gz.

Build systems and version control

In GNOME bug 532353, Elijah suggests switching Metacity to waf. Your thoughts on this are requested. I will build this into the test scripts whether or not we go with it in the long term.

Also, no work is getting done (or at least checked in) until the openssh débâcle is over and gone. Would this be a good excuse to move to bzr or git? Advocate please! I like bzr, but mainly because I already use it a lot and I love Python.

Bug hitlist, first week of May

Hooray, hooray, the first of May, Metacity unit and regression testing begins today. Okay, so it doesn’t scan as well as the original, but it’s almost as exciting. Well, perhaps. I (Thomas) am planning the framework at present, have something fairly solid in my head now, and will probably post something up here in the next few days when I have it planned out so everyone else can argue it :)

As well as this, here are the bugs on the front burner for me for this week: if you want something else fixed, talk to us about it (and send us patches!):

* GNOME bug 499996 (possibly aka Debian bug 443933 possibly aka Debian bug 460712)
* Launchpad bug 221144 (possibly aka Debian bug 476386) (may be related to the above, although perhaps not)
* Launchpad bug 216049 – restore to wrong workspace
* GNOME bug 468075 aka Launchpad bug 133541 – vertical maximisation ignores struts, apparent regression
* GNOME bug 528927 — something to do with _net_wm_state_demands_attention, details a little unclear
If you think it should be different, feel free to advocate below.

Are there distributions not using Launchpad which have a systematic way to link to upstream bugs that we could make use of for keeping people installed?

This is the first time we’ve used the new “bug hitlist” tag, which may become partly automated like Metacity Journal is. If you’re working on a bug in Metacity and you have an @gnome.org address, feel free to post bug hitlist entries; if you are and you don’t, feel free to comment to one of them and ask for one to be made or added to.

I shall post Metacity Journal tomorrow, I think, but I just wanted to acknowledge the particular good contributions that Santanu Chatterjee has been making on fixing problems with keyboard grabs during drag-and-drop.

Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported.