August 2008 – …for the adult in you

Doxygen

Here’s a really easy way of getting involved with Metacity which doesn’t even involve being able to compile it, can be carried out even if you only have a basic knowledge of C, and will teach you something about the way the system works and get you credit in the release notes.

A goal of mine for 2.26 is to see all the functions documented. I’d like to see every function begin with a comment saying what it does, what its parameters are, and what its return value is. And you can figure this out by reading the code– or if you can’t, you can read more of the code to find out, or come here and ask. And really, if you can’t figure it out, that’s nothing to be ashamed of– it shows we really needed the comment.

In my opinion, the system used by Doxygen, which is similar to that used by Javadoc, does everything we need in a reasonable way, and for a few months I have been adding documentation comments to functions all over the place– I think bell.c is a good example of the style, though I’ve learned a few new things about the Doxygen system since then that I’d like to modify. You can see some of the results here. However, there’s a lot left to do, and I could probably be spending my Metacity time better by fixing bugs, since I know the system pretty well by now, and this is something that can largely be done by people who are learning it (given that they’re supplying patches which will be checked for quality by someone who knows what they’re doing).

If you want to help work on this, sort out here which module you’d like to help work on, so we don’t have two people working on the same place. If you don’t know, I can suggest something. I’ll make a bug sometime so patches can be attached. It’s far more important that nonstatic functions are documented than static ones. Oh, and don’t forget to start block comments with a slash followed by two stars.

Photo credit: Terence T.S. Tam, cc-by-nc-sa.

2.25.0

Thanks to Patrick Niklaus, Ted Percival, Eric Piel, Akira TAGOH, and Thomas Thurman for improvements in this version.

Fix memory allocation problem in struts (Eric) (probably fixes GNOME bug 468075)
Ensure windows which start maximised know where to jump back to, so they don’t warp to other screens (Ted) (GNOME bug 504692)
Icons for windows which are uncooperative enough not to provide an icon are taken from the theme, not built in (Patrick) (GNOME bug 524343)
Added manual page for metacity-message (Akira, from Debian downstream)
Added header comments to some files (Thomas)

Translations: Khaled Hosny (ar), Petr Kovar (cs), Ilkka Tuohela (fi), Duarte Loreto (pt), Djavan Fagundes (pt_BR)

This is the first release from trunk after the branch for the new stable release.

Two points of note, in the hiatus of the Metacity Journal:

The release script numbered the NEWS entry as 2.25.1. I don’t know why (except that the release script is often unhappy around branch time, which is why we will be moving to moap sometime soon). I have numbered it back to 2.25.0 in trunk, but the version on the download site still has the misnumbered version. I don’t know if it’s worth doing a whole new unstable release just for this one thing. Perhaps we should skip 2.25.1 because of this.
The fix Patrick supplied in GNOME bug 524343 is correct, but we are missing a name to use from the icon theme. Rodney Dawes gives some suggestions on that bug. Other discussion is welcome there too.

Photo: St Albans Abbey, (c) thtstudios, cc-by-nc-nd.

2.23.144

Thanks to Ted Percival and Eric Piel for improvements in this version.

Fix memory allocation problem in struts (Eric) (probably fixes GNOME bug 468075)
Ensure windows which start maximised know where to jump back to, so they don’t warp to other screens (Ted) (GNOME bug 504692)

Translations: Khaled Hosny (ar), Petr Kovar (cs), Ilkka Tuohela (fi), Ignacio Casal Quinteiro (gl), Duarte Loreto (pt), Djavan Fagundes (pt_BR)
This release is for the GNOME 2.23 release tonight, which will form the first beta of GNOME 2.24. The 2.23 branch enters UI freeze tonight. Release notes are forthcoming.

Communicating with Metacity

Quite often people ask whether Metacity can talk to you across D-BUS, or something similar. It can’t. There is no need for this, because you can do pretty much anything you want using X messages. In particular, you can use messages from the EWMH specification to perform pretty much any task you might want, and there are some additional Metacity-specific ones (such as an instruction to change the theme).

If you want to play with a client which can send these messages, I recommend wmctrl. Try installing it (it’s in most distros, I think), and then playing with it to see how you can

switch desktops
bring a window to a desktop
resize a window
maximise a window
minimise all windows
list all windows
rename a window
… and so on.

Read its source for all the details; it’s quite clearly laid out.

Constraints

When a window changes position or size, there are rules of thumb about how it should happen. The trouble is that sometimes in real life these rules of thumb are contradictory, and we need a way to decide between them. This all used to be done in an ad-hoc way, but in 2005 Elijah swooped in and made one much more elegant system out of the chaos. In this system, every rule of thumb is represented by a constraint. There are currently nine of these, and going from most to least important they are:

constrain_partially_onscreen: “Some part of every window must appear on the screen.”
constrain_titlebar_visible: “Generally, some part of every window’s titlebar should always appear on the screen.”
constrain_size_limits: “If the application has requested that its window should not grow bigger or smaller than some size, we should honour that.”
constrain_fullscreen: “A fullscreen window should take up the entire xinerama area.”
constrain_maximization: “A maximised window should take up the full screen.”
constrain_size_increments: “If the application has requested that its window’s size should only be a multiple of some number, we should honour that.”
constrain_fully_onscreen: “It’s nice if the whole of the window appears on the screen at once.” (This rule doesn’t apply if it’s you, the user, moving the window about; you’re presumed to know where you want the window.)
constrain_to_single_xinerama: “It’s nice if a window appears on a single xinerama monitor.”
constrain_aspect_ratio: “If the application asks to have a window of a particular aspect ratio (say, square, or φ), it’s nice if we honour that.”

Every one of these constraints is represented by a C function which takes arguments of the window in question, a flag to say whether it’s allowed to modify the window, and some other things. The return result is ignored if the function wasn’t allowed to modify the window. But in read-only mode, it must return false only if it could never be satisfied with the window as it is. If it returns true, the function either thinks the window is all right as it is, or believes itself capable of changing the window until it’s satisfactory.

In order to enforce constraints, first of all we call all the constraint functions, permitting them to make changes, and ignoring whether they say they were satisfied. Then when they’re done, we call them all again in read-only mode; if any of them tells us it can’t be satisfied, then clearly there’s an inconsistent set of things we’re wanting here. (Perhaps we should also have a constraint called constraint_i_want_a_pony.) So we go round again, but we lower our expectations a little by taking away a group of the least important constraints, to see whether that helps us gain unanimity. If not, we go round again with the next most trivial group removed, and so on.

If you want to know more, you should read Elijah’s overview of constraints and then consider diving into the code. Some current bugs concern constraints, so it would be good for people to try to get their heads around them.

Photo credit: Amit Gupta, cc-by-nc.

Branch for stable 2.24

Metacity has been branched for stable 2.24. Hacking will continue in trunk as 2.25.x. This doesn’t mean that what’s in the 2.24 branch will necessarily be exactly what will ship; it does mean that what’s in the 2.24 branch is considered stable and changes which affect stability won’t affect it.

New features in trunk will not be backported to 2.24, but bugfixes will be.

Further 2.23 releases will be from the 2.24 branch and not trunk.

jhbuild has been updated (thanks, uws.)

If you don’t understand any of this, it doesn’t matter.

The one where we argue about themes a lot

The Metacity theme format has been roughly the same for six years now. Many people are quite happy with it as it is, but we fairly regularly get people coming along and asking why it can’t do this or that and how they can make it do so. The trouble is that changing the theme format is a fairly large upheaval, and not something we’d like to do much. Recently, two ideas have been put forward to change all that by making it not our problem to change the format if some newfangled idea comes about that we don’t support already.

It’s GTK’s problem. Metacity doesn’t draw borders at all any more. This makes us a much more lightweight window manager, because all we’d have to do is keep out of people’s way and manage windows. It also means that the toolkit can interact more easily with the borders, leading to fun stuff like these Tango experiments. (Of course, this is a source of OOH SHINY, which gets people writing about GNOME more than anything else.) Or as alex-weej points out, we could do things like this using standard libraries. Downsides: non-GTK applications have a bit of a problem; we would obviously still need to figure out what we’re doing about window border theme file formats; all this will need a lot of coordination between people from different projects. However, it does have the seeds of great awesomeness within it.
It’s librsvg’s problem. Make a new file format where everything is based on SVG files. Feed these into librsvg, substituting results of expressions as appropriate. There you have a simple format which can do anything librsvg can do, and keeps on growing as librsvg keeps growing. (This is all possible; I’ve done a little bit of test work here.) Allow no other instructions but a set of SVGs (I have the way to do this in my head if anyone’s interested, but I won’t bother writing this down if this is going to be a blind alley). Add a script which can take out an SVG so you can edit it with Inkscape. Disadvantages: it’s an evolution, not a revolution; it’s slower than the current system in tests (though I haven’t tried to optimise it); it doesn’t let us do all the fun stuff the other option does.
Both.
Neither.

Your thoughts, Gentle Readers, both on the pros and cons of each and of the best choice? I shall be updating the post with your ideas, with attributions.

Photo: © swizzled, cc-by-nc-sa

Update: See desrt’s mockup inspired in part by this entry.

Reminding us

Two of you emailed me out of the blue today to remind me that GNOME bug 504692 has an unreviewed patch on it that you’d like looked at before the next unstable release. Thank you! This is a very good way of reminding me of such things, and I think that holds true for most maintainers: we get dozens of pieces of email a day from Bugzilla, and a personal note is a bit of a stronger push.

(That said, don’t overdo it; I’m drowning in email as it is.)

The patch needs me to set up dual screens to test it. There was a joke earlier that there needed to be a collection to buy me a second screen, since all Metacity development is done on a laptop; I have now been lent a second screen. However, for the next couple of days I’ll be unusually busy in the world of non-GNOME software, and then I need to figure out how to get Xinerama and so on working on the new setup. I shall, of course, keep you up to date with extreme punctiliousness.

Thanks for being such a friendly and helpful bunch of users.

2.23.89: this is just for the unstable release tomorrow

2.23.89
=======

Thanks to Thomas Thurman for improvements in this version.

– Added DOAP file. (Thomas)
[here, if you want to see]

Translations
Khaled Hosny (ar), Luca Ferretti (it), Takeshi AIHANA (ja), Wouter
Bolsterlee (nl), Vladimir Melo (pt_BR), Daniel Nylander (sv)

There has actually been a whole lot of work going on, just not much of it in trunk at present.

Thought experiments: plugins

Recently, Markus Weißbacher raised GNOME bug 545627 to ask for a new menu option which suspended a window’s owning process. Now, it’s not particularly difficult to do this, and to some people (presumably Markus, at least) it’s useful, but there are hundreds of things we could put on the window menu, and if we put them all on, it would end up looking like a restaurant menu with hundreds of choices (especially with sub-menus– you know, biryani linking to chicken biryani, prawn biryani, and so on, vindaloo to lamb vindaloo, and… sorry, I got kind of distracted there). This is nice if you know what you’re doing, but it does rather terrify the users, and if you know you want one out of a small number of things every day it might be faster for you to pick from a cut-down lunch menu. Do excuse me; I like this analogy, and there might be barfi at the end of it.

We could provide code for all the hundred-odd options, and then let the user choose between them in a vast gconf directory of doom, and that would solve the problem of having to show them all for everyone. But Metacity is supposed to be a lightweight window manager, and including all that extra code will make us even less lightweight than we are. For the same reason, the solution is not to embed a Scheme interpreter so people can write plugins for all the menu options they want. Nor are we going to have something like Firefox’s plugin system where the extensions handling each menu option would run in-process, rendering a previously stable window manager more brittle than a poppadom… sorry, distracted again.

So suppose we wanted to let users add options to the Metacity window menu in some kind of configuration file (ah! then we could let libwnck read the same file!), or a place in gconf, and to invoke something out of process when the user chose one of them. I see three ways to proceed:

Fork and exec something. This is an extremely simple and nicely general solution, though the mechanics of figuring out what information is passed to the exec’d process needs some thought. We already do something like this for certain keybindings, so perhaps we can just generalise that.
X messages to the root window which are then picked up by a daemon. Not a bad idea, and in fact we do a lot of things this way already (many of them undocumented– ooh, an idea for a forthcoming post). This does require either one daemon to be running all the time, which means if it crashes nothing will respond, or a bunch of them, which is a bit of a resource hog.
D-Bus. This has the great advantage over X messages that if the handler isn’t running the bus will start it, and the handler can do its work and then softly and silently vanish away without ever hanging around as a daemon.

As well as adding new menu operations, this could be used to add new operations on that annual blister, middle-click and double-click on the titlebar. Perhaps the idea could even be used to add new button actions, although adding new types of buttons with the current theme version is generally impossible, because all themes must describe all types of buttons and all types of buttons must be described by all themes.

Translation work would need to be carefully coordinated with such a system, too, especially if we started moving existing actions (which are all already translated) out of the code and into the list.

So, anyway, this was my thought experiment for the day. I’m not necessarily going to do anything about it, or at least not now, but I thought it might be a simple way for people to get what they wanted without the risk of messing up the world for everyone else.

Photo by Lakesidey. cc-by-nc-sa.