Commit 51a64679 authored by Jon Nettleton's avatar Jon Nettleton Committed by Owen W. Taylor

Comprehensively rename to Mutter

Code:
All references in the code not related to themes, keybindings, or
GConf were changed from 'metacity' to 'mutter'. This includes, among other
things, strings, comments, the atoms used in the message protocol, and
the envvars used for debugging. The GConf schema file was reduced to
the 3 settings new to mutter.

The overall version was brought up to 2.27 to match current gnome.

Structure:
All files named '*metacity*' were renamed '*mutter*' with appropriate
changes in the automake system.  Files removed are
doc/creating_themes, src/themes, doc/metacity-theme.dtd,
metacity.doap.  These files will eventually end up in an external
gnome-wm-data module.

Installation location:
On the filesystem the mutter-plugindir was change from
$(libdir)/metacity/plugins/clutter to just $(libdir)/mutter/plugins.
The mutter-plugins.pc.in reflects these changes.

Note:
mutter.desktop.in and mutter-wm.desktop both continue to have
X-GNOME-WMSettingsModule=metacity set.  This allows
gnome-control-center to continue using libmetacity.so for
configuration.  This is fine since most the general keybindings and wm
settings are being read from /apps/metacity/* in gconf.
parent 9127993d
......@@ -12,7 +12,7 @@ The stable releases so far are 2.4.x, 2.6.x, 2.8.[01], 2.8.1.x, 2.8.5-,
Unstable branches are 2.3.x, 2.5.x, 2.8.2-4, 2.9.x, 2.11.x, 2.13.x,
2.15.x, 2.17.x.
COMPILING METACITY
COMPILING MUTTER
===
You need GTK+ 2.2. For startup notification to work you need
......@@ -20,6 +20,7 @@ libstartup-notification at
http://www.freedesktop.org/software/startup-notification/ or on the
GNOME ftp site. You also need GConf 1.2 (unless building a funky
extra-small embedded metacity with --disable-gconf, see below).
You need Clutter 0.9.3. You need gobject-introspection 0.6.3.
REPORTING BUGS AND SUBMITTING PATCHES
===
......@@ -36,47 +37,11 @@ Feel free to send patches too; Metacity is relatively small and
simple, so if you find a bug or want to add a feature it should be
pretty easy. Send me mail, or put the patch in bugzilla.
See the HACKING file for some notes on hacking Metacity.
See the HACKING file for some notes on hacking Mutter.
SHRINKING METACITY
MUTTER FEATURES
===
Not that metacity is huge, but a substantial amount of code is in
preferences handling, in static strings that aren't essential, and in
the theme engine.
You can strip about 70K from the metacity binary by compiling with
options such as:
--disable-gconf
--disable-sm
--disable-verbose
--disable-startup-notification
However the result is no good for desktop use, all prefs have to be
hardcoded in the binary, for example. If you wanted to make a really
small metacity, here's some additional stuff you might consider
implementing:
- add --disable-themes, which would replace theme.c and theme-parser.c
with a hardcoded implementation of the interface in theme.h,
should save about 80K. This should be fairly easy.
- add --disable-gtk, which would implement the interface in ui.h
without using GTK. This one is easier than you think because the
main part of the window manager doesn't use GTK directly, but is
still fairly hard to do. You would probably have to give up some
of the features, such as window menus, as menus are pretty complex
to implement well. So time may be better spent adding a GTK
configure script feature to build GTK with only a small core set of
functionality.
METACITY FEATURES
===
- Boring window manager for the adult in you. Many window managers
are like Marshmallow Froot Loops; Metacity is like Cheerios.
- Uses GTK+ 2.0 for drawing window frames. This means colors, fonts,
etc. come from GTK+ theme.
......@@ -132,8 +97,6 @@ METACITY FEATURES
Also try the GNOME keyboard shortcuts control panel, or
gconf-editor.
See metacity.schemas for all available bindings.
- Window keybindings:
Alt-space window menu
......@@ -185,13 +148,13 @@ METACITY FEATURES
- Session management:
Metacity connects to the session manager and will set itself up to
Mutter connects to the session manager and will set itself up to
be respawned. It theoretically restores sizes/positions/workspace
for session-aware applications.
- Metacity implements much of the EWMH window manager specification
- Mutter implements much of the EWMH window manager specification
from freedesktop.org, as well as the older ICCCM. Please refer to
the COMPLIANCE file for information on metacity compliance with
the COMPLIANCE file for information on mutter compliance with
these standards.
- Uses Pango to render text, so has cool i18n capabilities.
......@@ -210,7 +173,7 @@ METACITY FEATURES
- handles the window manager selection from the ICCCM. Will exit if
another WM claims it, and can claim it from another WM if you pass
the --replace argument. So if you're running another
ICCCM-compliant WM, you can run "metacity --replace" to replace it
ICCCM-compliant WM, you can run "mutter --replace" to replace it
with Metacity.
- does basic colormap handling
......@@ -220,7 +183,7 @@ METACITY FEATURES
HOW TO ADD EXTERNAL FEATURES
===
You can write a metacity "plugin" such as a pager, window list, icon
You can write a mutter "plugin" such as a pager, window list, icon
box, task menu, or even things like "window matching" using the
Extended Window Manager Hints. See http://www.freedesktop.org for the
EWMH specification. An easy-to-use library called "libwnck" is
......@@ -228,10 +191,10 @@ available that uses the EWMH and is specifically designed for writing
WM accessories.
You might be interested in existing accessories such as "Devil's Pie"
by Ross Burton, which add features to Metacity (or other
by Ross Burton, which add features to Mutter (or other
EWMH-compliant WMs).
METACITY BUGS, NON-FEATURES, AND CAVEATS
MUTTER BUGS, NON-FEATURES, AND CAVEATS
===
See bugzilla: http://bugzilla.gnome.org/query.cgi
......@@ -270,26 +233,15 @@ A: If it makes sense to turn on unconditionally, or is genuinely a
http://pobox.com/~hp/free-software-ui.html
http://pobox.com/~hp/features.html
Q: Will Metacity be part of GNOME?
A: It is officially part of GNOME as of GNOME 2.2. Prior to that,
it was unofficially shipped as the default GNOME WM by several
OS vendors.
Q: Is Metacity a Red Hat project?
Q: Will Mutter be part of GNOME?
A: Metacity's original creation was in no way funded, endorsed, or
encouraged by Red Hat, Inc. - I'm guessing Red Hat would not
consider "insufficient number of window managers for Linux" an
urgent problem. Just a wild guess though.
A: It is not officially part of GNOME as of GNOME 2.27. We are
hoping to have mutter officially included as of GNOME 2.28.
Now that metacity is the default WM however, Red Hat supports some
bugfixing and other work.
Q: Why does Metacity remember the workspace/position of some apps
Q: Why does Mutter remember the workspace/position of some apps
but not others across logout/login?
A: Metacity only stores sizes/positions for apps that are session
A: Mutter only stores sizes/positions for apps that are session
managed. As far as I can determine, there is no way to attempt to
remember workspace/position for non-session-aware apps without
causing a lot of weird effects.
......@@ -304,7 +256,7 @@ A: Metacity only stores sizes/positions for apps that are session
place. And in fact I see a lot of bugs like this in window managers
that try to handle non-session-aware apps.
However, for session-aware apps, Metacity can tell that the
However, for session-aware apps, Mutter can tell that the
application instance is from the session and thus restore it
reliably, assuming the app properly restores the windows it had
open on session save.
......@@ -456,7 +408,7 @@ A: There are quite a few, though many opportunities remain. Sometimes
- and much more.
Q: I think metacity sucks.
Q: I think mutter sucks.
A: Feel free to use any WM you like. The reason metacity follows the
ICCCM and EWMH specifications is that it makes metacity a modular,
......
......@@ -4,7 +4,7 @@
srcdir=`dirname $0`
test -z "$srcdir" && srcdir=.
PKG_NAME="metacity"
PKG_NAME="mutter"
REQUIRED_AUTOMAKE_VERSION=1.10
(test -f $srcdir/configure.in \
......
AC_PREREQ(2.50)
m4_define([metacity_major_version], [2])
m4_define([metacity_minor_version], [27])
m4_define([mutter_major_version], [2])
m4_define([mutter_minor_version], [27])
# Fibonacci sequence for micro version numbering:
# 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987
m4_define([metacity_micro_version], [0])
m4_define([mutter_version],[0.7])
m4_define([mutter_micro_version], [0])
m4_define([metacity_version],
[metacity_major_version.metacity_minor_version.metacity_micro_version~mutter_version])
m4_define([mutter_version],
[mutter_major_version.mutter_minor_version.mutter_micro_version])
m4_define([metacity_clutter_plugin_api_version], [2])
m4_define([mutter_plugin_api_version], [2])
AC_INIT([metacity], [metacity_version],
[http://bugzilla.gnome.org/enter_bug.cgi?product=metacity])
AC_INIT([mutter], [mutter_version],
[http://bugzilla.gnome.org/enter_bug.cgi?product=mutter])
AC_CONFIG_SRCDIR(src/core/display.c)
AC_CONFIG_HEADERS(config.h)
......@@ -21,22 +20,22 @@ AC_CONFIG_HEADERS(config.h)
AM_INIT_AUTOMAKE
AM_MAINTAINER_MODE
METACITY_MAJOR_VERSION=metacity_major_version
METACITY_MINOR_VERSION=metacity_minor_version
METACITY_MICRO_VERSION=metacity_micro_version
METACITY_CLUTTER_PLUGIN_API_VERSION=metacity_clutter_plugin_api_version
AC_SUBST(METACITY_MAJOR_VERSION)
AC_SUBST(METACITY_MINOR_VERSION)
AC_SUBST(METACITY_MICRO_VERSION)
AC_SUBST(METACITY_CLUTTER_PLUGIN_API_VERSION)
MUTTER_MAJOR_VERSION=mutter_major_version
MUTTER_MINOR_VERSION=mutter_minor_version
MUTTER_MICRO_VERSION=mutter_micro_version
MUTTER_PLUGIN_API_VERSION=mutter_plugin_api_version
AC_SUBST(MUTTER_MAJOR_VERSION)
AC_SUBST(MUTTER_MINOR_VERSION)
AC_SUBST(MUTTER_MICRO_VERSION)
AC_SUBST(MUTTER_PLUGIN_API_VERSION)
MUTTER_PLUGIN_DIR="$libdir/$PACKAGE/plugins/clutter"
MUTTER_PLUGIN_DIR="$libdir/$PACKAGE/plugins"
AC_SUBST(MUTTER_PLUGIN_DIR)
# Honor aclocal flags
AC_SUBST(ACLOCAL_AMFLAGS, "\${ACLOCAL_FLAGS}")
GETTEXT_PACKAGE=metacity
GETTEXT_PACKAGE=mutter
AC_SUBST(GETTEXT_PACKAGE)
AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE,"$GETTEXT_PACKAGE",[Name of default gettext domain])
......@@ -123,7 +122,7 @@ if test "x$GCC" = "xyes"; then
fi
changequote([,])dnl
METACITY_PC_MODULES='gtk+-2.0 >= 2.10.0 pango >= 1.2.0'
MUTTER_PC_MODULES='gtk+-2.0 >= 2.10.0 pango >= 1.2.0'
AC_ARG_ENABLE(gconf,
AC_HELP_STRING([--disable-gconf],
......@@ -132,12 +131,12 @@ AC_ARG_ENABLE(gconf,
if test x$enable_gconf = xyes; then
AC_DEFINE(HAVE_GCONF,1,[Build with gconf support])
METACITY_PC_MODULES="$METACITY_PC_MODULES gconf-2.0 >= 1.2.0"
MUTTER_PC_MODULES="$MUTTER_PC_MODULES gconf-2.0 >= 1.2.0"
fi
AC_ARG_ENABLE(verbose-mode,
AC_HELP_STRING([--disable-verbose-mode],
[disable metacity's ability to do verbose logging, for embedded/size-sensitive custom builds]),,
[disable mutter's ability to do verbose logging, for embedded/size-sensitive custom builds]),,
enable_verbose_mode=yes)
if test x$enable_verbose_mode = xyes; then
......@@ -146,42 +145,42 @@ fi
AC_ARG_ENABLE(sm,
AC_HELP_STRING([--disable-sm],
[disable metacity's session management support, for embedded/size-sensitive custom non-GNOME builds]),,
[disable mutter's session management support, for embedded/size-sensitive custom non-GNOME builds]),,
enable_sm=auto)
AC_ARG_ENABLE(startup-notification,
AC_HELP_STRING([--disable-startup-notification],
[disable metacity's startup notification support, for embedded/size-sensitive custom non-GNOME builds]),,
[disable mutter's startup notification support, for embedded/size-sensitive custom non-GNOME builds]),,
enable_startup_notification=auto)
AC_ARG_ENABLE(compositor,
AC_HELP_STRING([--disable-compositor],
[disable metacity's compositing manager]),,
[disable mutter's compositing manager]),,
enable_compositor=auto)
AC_ARG_WITH(clutter,
AC_HELP_STRING([--with-clutter],
[Use clutter for compositing]),,
AC_ARG_ENABLE(clutter,
AC_HELP_STRING([--without-clutter],
[disable the use of clutter for compositing]),,
with_clutter=auto)
AC_ARG_WITH(introspection,
AC_HELP_STRING([--with-introspection],
[Use GObject introspection]),,
AC_ARG_ENABLE(introspection,
AC_HELP_STRING([--without-introspection],
[disable the use of GObject introspection]),,
with_introspection=auto)
AC_ARG_ENABLE(xsync,
AC_HELP_STRING([--disable-xsync],
[disable metacity's use of the XSync extension]),,
[disable mutter's use of the XSync extension]),,
enable_xsync=auto)
AC_ARG_ENABLE(render,
AC_HELP_STRING([--disable-render],
[disable metacity's use of the RENDER extension]),,
[disable mutter's use of the RENDER extension]),,
enable_render=auto)
AC_ARG_ENABLE(shape,
AC_HELP_STRING([--disable-shape],
[disable metacity's use of the shaped window extension]),,
[disable mutter's use of the shaped window extension]),,
enable_shape=auto)
## try definining HAVE_BACKTRACE
......@@ -193,8 +192,8 @@ AM_GLIB_GNU_GETTEXT
# GOptionEntry requires glib-2.6.0
PKG_CHECK_MODULES(ALL, glib-2.0 >= 2.6.0)
# gtk_window_set_icon_name requires gtk2+-2.60
PKG_CHECK_MODULES(METACITY_MESSAGE, gtk+-2.0 >= 2.6.0)
PKG_CHECK_MODULES(METACITY_WINDOW_DEMO, gtk+-2.0 >= 2.6.0)
PKG_CHECK_MODULES(MUTTER_MESSAGE, gtk+-2.0 >= 2.6.0)
PKG_CHECK_MODULES(MUTTER_WINDOW_DEMO, gtk+-2.0 >= 2.6.0)
if $PKG_CONFIG --atleast-version 1.2.0 pangoxft; then
echo "pangoxft found"
......@@ -226,7 +225,7 @@ fi
if test x$have_startup_notification = xyes; then
echo "Building with libstartup-notification"
METACITY_PC_MODULES="$METACITY_PC_MODULES libstartup-notification-1.0 >= $STARTUP_NOTIFICATION_VERSION"
MUTTER_PC_MODULES="$MUTTER_PC_MODULES libstartup-notification-1.0 >= $STARTUP_NOTIFICATION_VERSION"
AC_DEFINE(HAVE_STARTUP_NOTIFICATION, , [Building with startup notification support])
else
echo "Building without libstartup-notification"
......@@ -249,9 +248,10 @@ fi
if test x$with_clutter = xyes; then
have_xcomposite=yes
have_clutter=yes
echo "CompositeExt support and Clutter forced on"
elif test x$with_clutter = xauto; then
have_clutter=no
echo "Building clutter compositing manager by default now."
have_xcomposite=yes
have_clutter=yes
else
have_clutter=no
fi
......@@ -268,7 +268,7 @@ if test x$have_xcomposite = xyes; then
fi
if test x$have_xcomposite = xyes; then
METACITY_PC_MODULES="$METACITY_PC_MODULES xcomposite >= $XCOMPOSITE_VERSION xfixes xrender xdamage"
MUTTER_PC_MODULES="$MUTTER_PC_MODULES xcomposite >= $XCOMPOSITE_VERSION xfixes xrender xdamage"
AC_DEFINE(HAVE_COMPOSITE_EXTENSIONS, 1, [Building with compositing manager support])
echo "Building with compositing manager"
......@@ -300,7 +300,7 @@ if test x$have_xcomposite = xno; then
if test x$have_xrender = xyes; then
echo "Building with Render"
METACITY_PC_MODULES="$METACITY_PC_MODULES xrender >= $XRENDER_VERSION"
MUTTER_PC_MODULES="$MUTTER_PC_MODULES xrender >= $XRENDER_VERSION"
fi
fi ## have_composite
......@@ -311,17 +311,17 @@ fi
CLUTTER_PACKAGE=clutter-0.9
AC_SUBST(CLUTTER_PACKAGE)
if test x$have_clutter = xyes; then
METACITY_PC_MODULES="$METACITY_PC_MODULES $CLUTTER_PACKAGE "
MUTTER_PC_MODULES="$MUTTER_PC_MODULES $CLUTTER_PACKAGE "
PKG_CHECK_MODULES(CLUTTER, $CLUTTER_PACKAGE)
AC_DEFINE(WITH_CLUTTER, , [Building with Clutter compositor])
dnl Check for the clutter-glx-texture-pixmap header
metacity_save_cppflags="$CPPFLAGS"
mutter_save_cppflags="$CPPFLAGS"
CPPFLAGS="$CPPFLAGS $CLUTTER_CFLAGS"
AC_CHECK_HEADER([clutter/glx/clutter-glx-texture-pixmap.h],
[have_glx_texture_pixmap=yes],
[have_glx_texture_pixmap=no])
CPPFLAGS="$metacity_save_cppflags"
CPPFLAGS="$mutter_save_cppflags"
if test x$have_glx_texture_pixmap = xyes; then
AC_DEFINE(HAVE_GLX_TEXTURE_PIXMAP, ,
......@@ -332,7 +332,7 @@ fi
if test x$with_introspection != xno; then
PKG_CHECK_MODULES(INTROSPECTION, gobject-introspection-1.0, have_introspection=yes, have_introspection=no)
if test x$have_introspection=xyes; then
METACITY_PC_MODULES="$METACITY_PC_MODULES gobject-introspection-1.0"
MUTTER_PC_MODULES="$MUTTER_PC_MODULES gobject-introspection-1.0"
AC_DEFINE(HAVE_INTROSPECTION, 1, [Define if GObject introspection is available])
G_IR_SCANNER=`$PKG_CONFIG --variable=g_ir_scanner gobject-introspection-1.0`
AC_SUBST(G_IR_SCANNER)
......@@ -358,23 +358,23 @@ if $PKG_CONFIG xcursor; then
if test x$have_xcursor = xyes; then
echo "Building with Xcursor"
METACITY_PC_MODULES="$METACITY_PC_MODULES xcursor"
MUTTER_PC_MODULES="$MUTTER_PC_MODULES xcursor"
AC_DEFINE(HAVE_XCURSOR, , [Building with Xcursor support])
fi
PKG_CHECK_MODULES(METACITY, $METACITY_PC_MODULES)
PKG_CHECK_MODULES(MUTTER, $MUTTER_PC_MODULES)
AC_PATH_XTRA
ALL_X_LIBS="$X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS"
# Check for Xinerama extension (Solaris impl or Xfree impl)
metacity_save_cppflags="$CPPFLAGS"
mutter_save_cppflags="$CPPFLAGS"
CPPFLAGS="$CPPFLAGS $X_CFLAGS"
AC_ARG_ENABLE(xinerama,
AC_HELP_STRING([--disable-xinerama],
[disable metacity's use of the Xinerama extension]),
[disable mutter's use of the Xinerama extension]),
try_xinerama=$enable_xinerama,try_xinerama=yes)
use_solaris_xinerama=no
......@@ -420,7 +420,7 @@ if test "${try_xinerama}" != no; then
esac
fi
CPPFLAGS="$metacity_save_cppflags"
CPPFLAGS="$mutter_save_cppflags"
SHAPE_LIBS=
found_shape=no
......@@ -491,21 +491,21 @@ if test "x$found_xsync" = "xyes"; then
AC_DEFINE(HAVE_XSYNC, , [Have the Xsync extension library])
fi
METACITY_LIBS="$METACITY_LIBS $XSYNC_LIBS $RANDR_LIBS $SHAPE_LIBS $X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS -lm"
METACITY_MESSAGE_LIBS="$METACITY_MESSAGE_LIBS $X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS"
METACITY_WINDOW_DEMO_LIBS="$METACITY_WINDOW_DEMO_LIBS $X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS"
METACITY_PROPS_LIBS="$METACITY_PROPS_LIBS $X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS"
MUTTER_LIBS="$MUTTER_LIBS $XSYNC_LIBS $RANDR_LIBS $SHAPE_LIBS $X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS -lm"
MUTTER_MESSAGE_LIBS="$MUTTER_MESSAGE_LIBS $X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS"
MUTTER_WINDOW_DEMO_LIBS="$MUTTER_WINDOW_DEMO_LIBS $X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS"
MUTTER_PROPS_LIBS="$MUTTER_PROPS_LIBS $X_LIBS $X_PRE_LIBS -lX11 $X_EXTRA_LIBS"
found_sm=no
case "$METACITY_LIBS" in
case "$MUTTER_LIBS" in
*-lSM*)
found_sm=yes
;;
*)
AC_CHECK_LIB(SM, SmcSaveYourselfDone,
[AC_CHECK_HEADERS(X11/SM/SMlib.h,
METACITY_LIBS="-lSM -lICE $METACITY_LIBS" found_sm=yes)],
, $METACITY_LIBS)
MUTTER_LIBS="-lSM -lICE $MUTTER_LIBS" found_sm=yes)],
, $MUTTER_LIBS)
;;
esac
......@@ -572,14 +572,12 @@ GNOME_DOC_INIT([0.8.0])
AC_CONFIG_FILES([
Makefile
doc/Makefile
doc/creating_themes/Makefile
doc/man/Makefile
src/Makefile
src/wm-tester/Makefile
src/libmetacity-private.pc
src/metacity-plugins.pc
src/libmutter-private.pc
src/mutter-plugins.pc
src/tools/Makefile
src/themes/Makefile
src/compositor/mutter/plugins/Makefile
po/Makefile.in
])
......@@ -596,14 +594,14 @@ fi
if test x$enable_verbose_mode = xno; then
echo "*** WARNING WARNING WARNING WARNING WARNING"
echo "*** Building without verbose mode"
echo "*** This means there's no way to debug metacity problems."
echo "*** Please build normal desktop versions of metacity"
echo "*** This means there's no way to debug mutter problems."
echo "*** Please build normal desktop versions of mutter"
echo "*** with verbose mode enabled so users can use it when they report bugs."
fi
dnl ==========================================================================
echo "
metacity-$VERSION:
mutter-$VERSION:
prefix: ${prefix}
source code location: ${srcdir}
......@@ -624,12 +622,12 @@ metacity-$VERSION:
Clutter: ${have_clutter}
"
METACITY_MINOR_VERSION=metacity_minor_version
if test $(( $(echo $METACITY_MINOR_VERSION) %2)) == "1"; then
stable_version=$(( ($METACITY_MINOR_VERSION / 2) * 2))
echo "This is the UNSTABLE branch of metacity"
MUTTER_MINOR_VERSION=mutter_minor_version
if test $(( $(echo $MUTTER_MINOR_VERSION) %2)) == "1"; then
stable_version=$(( ($MUTTER_MINOR_VERSION / 2) * 2))
echo "This is the UNSTABLE branch of mutter"
echo -n "Use 2.$stable_version.x for stable "
echo "(gnome-2-$stable_version branch in Subversion)"
else
echo "This is the stable branch of metacity"
echo "This is the stable branch of mutter"
fi
SUBDIRS = man creating_themes
SUBDIRS = man
EXTRA_DIST=theme-format.txt metacity-theme.dtd dialogs.txt code-overview.txt \
EXTRA_DIST=theme-format.txt dialogs.txt code-overview.txt \
how-to-get-focus-right.txt
......@@ -42,5 +42,5 @@ options you can set are:
menus zooming, dialogues being semi-transparent, and so on. Try it
and see whether you like it.
If you have any problems, ask on metacity-devel-list@gnome.org, or
If you have any problems, ask on mutter-devel-list@gnome.org, or
#gnome-hackers on gimpnet, or come and find me (tthurman at gnome) and ask.
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://docbook.org/docbook/xml/4.5/docbookx.dtd" [
]>
<book id="index">
<bookinfo>
<title>Understanding Metacity Themes</title>
<authorgroup>
<author>
<firstname>Thomas</firstname>
<surname>Thurman</surname>
</author>
</authorgroup>
<abstract>
<para>
We very much appreciate any reports of inaccuracies or other errors in
this document. Contributions are also most welcome. Post your
suggestions, critiques or addenda to the <ulink
url="mailto:tthurman@gnome.org">team</ulink>.</para>
</abstract>
<copyright>
<year>2008</year>
<holder>Thomas Thurman</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
</para>
</legalnotice>
</bookinfo>
<chapter id="sec-introduction">
<title>Introduction</title>
<para>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.</para>
<para>GNOME lets you theme a bunch of different things, but we're only talking about <literal>window border</literal> themes here, which some people call Metacity themes; <ulink url="http://en.wikipedia.org/wiki/Metacity#Themes">Wikipedia begins a sentence</ulink> with &quot;Despite the incomplete state of Metacity theme development documentation&quot;, and though there <emphasis>is</emphasis> <ulink url="http://svn.gnome.org/viewvc/metacity/trunk/doc/theme-format.txt?view=markup">documentation in the source</ulink>, apparently not many people find it, and it's written more for programmers than theme designers. Glynn Foster also wrote <ulink url="http://developer.gnome.org/doc/tutorials/metacity/metacity-themes.html">a very good introduction to Metacity themes</ulink> (<ulink url="http://home.arcor.de/rybaczyk/documents/tutorials/metacity/metacity-themes.de.html">[de]</ulink>) six years ago, but things have changed a little since then. <ulink url="http://lists.freedesktop.org/archives/compiz/2006-September/000445.html">Metacity themes can also be used by Compiz</ulink>, and perhaps by other window managers for all I know.</para>
<para>So, a Metacity theme is a set of instructions about how to &quot;decorate&quot; (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:</para>
<para>
<variablelist>
<varlistentry>
<term>state:</term><listitem><para>Every window must be in exactly one of these states: <literal>normal</literal>, <literal>dialog</literal>, <literal>modal dialog</literal> (i.e. a dialogue which means you can't interact with the rest of the program while it's up), <literal>menu</literal> (torn off from the main application, not that people do that much these days), <literal>utility</literal> (that is, palettes and toolboxes and things), and <literal>border</literal>. 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.</para></listitem>
</varlistentry>
<varlistentry>
<term>focused</term><listitem><para>Every window is either the active window (which X people call &quot;focused&quot;), or it isn't.</para></listitem>
</varlistentry>
<varlistentry>
<term>maximized</term><listitem><para>Every window is either (fully) maximised (horizontal and vertical only don't count), or it isn't.</para></listitem>
</varlistentry>
<varlistentry>
<term>shaded</term><listitem><para>Every window is either rolled up to show just its titlebar (which techies call &quot;shaded&quot; for some reason I can't fathom), or it isn't.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
<itemizedlist>
<listitem><para><emphasis>If a window is not fully maximised and not shaded,</emphasis> it either allows horizontal resizing, or it doesn't.</para></listitem>
<listitem><para><emphasis>If a window is not fully maximised and not shaded,</emphasis> it either allows vertical resizing, or it doesn't.</para></listitem>
</itemizedlist>
</para>
</chapter>
<chapter>
<title>What's in the file</title>
<para>The files must be called either</para>
<para>
<itemizedlist>
<listitem><para>~/.themes/<varname>N</varname>/metacity-1/metacity-theme-<varname>V</varname>.xml
for a theme used only by you, or</para></listitem>
<listitem><para>/usr/share/themes/<varname>N</varname>/metacity-1/metacity-theme-<varname>V</varname>.xml
for a theme installed for all users.</para></listitem>
</itemizedlist>
</para>
<para>where <varname>N</varname> is the name of the theme and <varname>V</varname> is the version of the format. Version 2, <ulink url="http://svn.gnome.org/viewvc/metacity?view=revision&amp;revision=2973">introduced in October 2006</ulink>, 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; <ulink url="http://bugzilla.gnome.org/show_bug.cgi?id=482165">new features</ulink> can't be added without introducing a new version number, which is why improvements come out rarely and in large clumps. <literal>metacity-1</literal> in the names is a fossil and doesn't mean version 1 of anything.</para>
<para>The metacity-theme-V.xml files are <ulink url="http://blogs.gnome.org/tthurman/2008/02/14/gmarkup/">GMarkup files</ulink>, 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 <ulink url="http://svn.gnome.org/viewvc/metacity/trunk/src/themes/Atlanta/metacity-theme-1.xml?view=markup">the current version of &quot;Atlanta&quot;</ulink>, one of the simplest themes, but even that is quite complicated-looking at first.</para>
<para>So, let's talk about what actually goes inside the files. As in any XML file, &lt;!-<!-- x -->- &#8230; <!-- x -->&gt; are comments. At its most basic, it would go:</para>
<para>
<programlisting>
&lt;metacity_theme&gt;
&lt;!-<!-- x -->- Helper stuff: -<!-- x -->-&gt;
&lt;info &#8230;&gt; &lt;!-<!-- x -->- to be explained -<!-- x -->-&gt;
&lt;constant &#8230;&gt; &lt;!-<!-- x -->- maybe; to be explained -<!-- x -->-&gt;
&lt;draw_ops &#8230;&gt; &lt;!-<!-- x -->- maybe; to be explained -<!-- x -->-&gt;
&lt;!-<!-- x -->- Things we build the top level onto: -<!-- x -->-&gt;
&lt;frame_geometry &#8230;&gt; &lt;!-<!-- x -->- to be explained -<!-- x -->-&gt;
&lt;frame_style &#8230;&gt; &lt;!-<!-- x -->- to be explained -<!-- x -->-&gt;
&lt;frame_style_set &#8230;&gt; &lt;!-<!-- x -->- to be explained -<!-- x -->-&gt;
&lt;!-<!-- x -->- And the top level: -<!-- x -->-&gt;
&lt;window type=&quot;normal&quot; style_set=&quot;&#8230;&quot; /&gt;
&lt;window type=&quot;dialog&quot; style_set=&quot;&#8230;&quot; /&gt;
&lt;window type=&quot;modal_dialog&quot; style_set=&quot;&#8230;&quot; /&gt;
&lt;window type=&quot;menu&quot; style_set=&quot;&#8230;&quot; /&gt;
&lt;window type=&quot;utility&quot; style_set=&quot;&#8230;&quot; /&gt;
&lt;window type=&quot;border&quot; style_set=&quot;&#8230;&quot; /&gt;
&lt;/metacity_theme&gt;
</programlisting>
</para>
</chapter>
<chapter>
<title>Matching windows</title>
<para>
<variablelist>
<varlistentry>
<term>window</term><listitem><para>You see that at the top level we have a list of &lt;window&gt; 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.</para></listitem>
</varlistentry>
<varlistentry>
<term>frame_style_set:</term><listitem><para>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:</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
<programlisting>
&lt;frame_style_set&gt;
&lt;frame focus=&quot;F&quot; state=&quot;S&quot; resize=&quot;R&quot; style=&quot;N&quot;/&gt;
&lt;frame&#8230; /&gt;