Devil's Pie
===========

Copyright (C) 2002-4, Ross Burton <ross@burtonini.com>


A window-matching utility, inspired by Sawfish's "Matched Windows" option and
the lack such functionality in Metacity. Metacity lacking window matching is not
a bad thing -- Metacity is a lean window manager, and window manipulation does
not have to be a window manager task.

Devil's Pie can be configured to detect windows as they are created, and match
the window to a set of rules. If the window matches the rules, it can perform a
series of actions on that window. For example, I can make X-Chat appear on all
workspaces, and make a particular xterm not appear in the pager or task list.


Building
--------

To build devilspie, follow the usual configure ; make ; make install steps. If
this confuses you, read INSTALL. Packages are in Debian Sarge, and I build
Debian packages of the latest released version.  These are available from
http://www.burtonini.com/debian/

A .spec file is provided for RPM-based distributions, but I didn't write it and
don't support it.


Configuration
-------------

The default configuration file to read is ~/.devilspie.xml. However, if there
are arguments to devilspie then that file will be opened instead.

The format of this file is simple. It's a collection of 'flurbs'. Each flurb
contains one or several matchers and one or several actions. Each matcher or
action may contain one or several properties. You should have a look at the
included DTD for more details. The DTD will make creating valid files much
easier in SGML editors, such as XEmacs+psgml (this DTD is installed correctly on
Debian). A GUI builder is planned, if I can think of a good interface for it.

See devilspie-reference.html for a complete list of matchers and actions. This is
generated from the source so should be totally up to date. Unless otherwise
stated, all properties contain a tristate value which can either be TRUE, FALSE,
or UNSET.

There is a working example configuration file in sample-config.xml.


Running
-------

Just run devilspie as a normal user. The best way is to run it in your session
(for example in Desktop Preferences -> Advanced -> Sessions -> Startup
Programs).  If you don't wish to use ~/.devilspie.xml as the configuration file,
specify it as an argument (i.e. devilspie /home/share/devilspie-common.xml).


Architecture
------------

After the configuration file has been read and parsed, devilspie sits in a GLib
main loop waiting on libwnck to notify itself about window creation. When a
window is created, devilspie iterates through every "Flurb" (a set of matches
and actions) and executes every matcher. If they all return true, then all of
the actions are executed.

Matchers and Actions are GObjects, subclasses of DevilsPieMatcher and
DevilsPieAction. They must export any properties they support via GObject
properties.  I recommend using GOB to write these, as it makes it much easier.
When GOB supports it, the Matcher and Action classes will become pure
interfaces, but for now they are abstract classes.

Many properties use a tristate variable type called DevilsPieTriState, which
supports TRUE, FALSE, and UNSET. The declaration of this is a bit hacky at the
moment as GOB doesn't allow a .gob file without a class. I could be a real man
and write this class manually... but I'm lazy.
