mutter/README

Metacity is not a meta-City as in an urban center, but rather
Meta-ness as in the state of being meta. i.e. metacity : meta as
opacity : opaque. Also it may have something to do with the Meta key
on UNIX keyboards.

The first release of Metacity was version 2.3. Metacity has no need for
your petty hangups about version numbers.

COMPILING METACITY
===

You need GTK+ 2.0, ideally the latest in the 2.0.x series.

REPORTING BUGS AND SUBMITTING PATCHES
===

Report new bugs on http://bugzilla.gnome.org.

Feel free to send patches too; Metacity is really 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.

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.

 - Has a simple theme system and a couple of extra themes come with it.
   Change themes via gconf-editor or gconftool:
     gconftool-2 --type=string --set /apps/metacity/general/theme Crux
     gconftool-2 --type=string --set /apps/metacity/general/theme Gorilla
     gconftool-2 --type=string --set /apps/metacity/general/theme Atlanta
     gconftool-2 --type=string --set /apps/metacity/general/theme Bright

   See theme-format.txt for docs on the theme format. Use 
   metacity-theme-viewer to preview themes.

 - Change number of workspaces via gconf-editor or gconftool:
     gconftool-2 --type=int --set /apps/metacity/general/num_workspaces 5

   Can also change workspaces from GNOME 2 pager.

 - Change focus mode:
     gconftool-2 --type=string --set /apps/metacity/general/focus_mode mouse
     gconftool-2 --type=string --set /apps/metacity/general/focus_mode sloppy
     gconftool-2 --type=string --set /apps/metacity/general/focus_mode click

 - Global keybindings:
    Alt-F1 to Alt-F6       switch workspaces
    Alt-1  to Alt-6        switch workspaces
    Alt-Tab                forward cycle window focus
    Alt-Shift-Tab          backward cycle focus
    Alt-Ctrl-Tab           forward cycle focus among panels
    Alt-Ctrl-Shift-Tab     backward cycle focus among panels
    Alt-Escape             focus previous window
    Ctrl-Alt-Left Arrow    previous workspace
    Ctrl-Alt-Right Arrow   next workspace
    Ctrl-Alt-D             minimize/unminimize all, to show desktop

 - Window keybindings:
    Alt-space         window menu

    Mnemonics work in the menu. That is, Alt-space then underlined
    letter in the menu item works.

    Choose Move from menu, and arrow keys to move the window.

    While moving, hold down Control to move slower, and 
      Shift to snap to edges.

    Choose Resize from menu, and nothing happens yet, but 
      eventually I might implement something.

 - Window mouse bindings:

    Clicking anywhere on frame with button 1 will raise/focus window
    
    If you click a window control, such as the close button, then the 
     control will activate on button release if you are still over it
     on release (as with most GUI toolkits)

    If you click and drag borders with button 1 it resizes the window
    
    If you click and drag the titlebar with button 1 it moves the 
     window.

    If you click anywhere on the frame with button 3 it shows the 
     window menu.

    If you hold down Alt and click inside a window, it will move the 
     window (buttons 1 and 2) or show menu (button 3).

    If you pick up a window with button 1 and then switch workspaces
     the window will come with you to the new workspace, this is 
     a feature copied from Enlightenment.

    If you hold down Shift while moving a window, the window snaps
     to edges of other windows and the screen.

 - Session management:

    Metacity 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 new window manager spec from
   freedesktop.org, and much of the ICCCM. But then there are 
   parts of each that it doesn't implement, just because I haven't
   yet.

 - Uses Pango to render text, so has cool i18n capabilities. 
   Supports UTF-8 window titles and such.

 - There are simple animations for actions such as minimization, 
   to help users see what is happening. Should probably 
   have a few more of these and make them nicer.

 - if you have the proper X setup, set the GDK_USE_XFT=1 
   environment variable to get antialiased window titles.

 - considers the panel when placing windows and maximizing
   them.

METACITY BUGS, NON-FEATURES, AND CAVEATS
===

 - If you want keybindings which are not the ones mentioned above
   as features, you have to edit keybindings.c and recompile.

 - Some of the default keybindings (notable Alt+number) are total
   crackrock. This is just because I like those keybindings and 
   things aren't configurable yet. Once bindings are configurable
   the dumb defaults will go away.

 - You need an EWMH-spec compliant pager/tasklist to be able 
   to navigate graphically; this does NOT include GNOME 1.x, 
   but should include GNOME 2 and KDE 3.

 - Metacity turns off its keybindings for Emacs, because I use 
   Alt-space in Emacs, and getting a window menu annoys me.
   This is a broken feature that will go away when keybindings are 
   configurable.

 - I haven't even read the ICCCM section about colormaps. So if you 
   have an 8-bit display you are probably screwed.

 - Metacity doesn't properly claim the window manager selection
   as described in the ICCCM. But then, most other window managers
   don't handle this correctly either.

 - There are probably other ICCCM-compliance issues.

 - Window placement is always cascade for now; I want to implement 
   "first fit, falling back to cascade if no fit." 
   (Configurable placement algorithms are stupid though, don't 
   send me patches for any bogus ones. Let's just pick a good one.)

 - Should Metacity support flipping in right-to-left locales?
   I don't know what window managers look like in a right-to-left
   locale. I assume the window titles should be right-justified;
   should the window controls also be flipped?

 - Resize menu item doesn't do anything. It's intended to enter
   resize-with-the-keyboard mode, similar to Move menu item.

 - In GNOME 1.x, if you switch from sawfish to metacity without
   restarting X, the panel often ends up buried behind the Nautilus
   desktop window.

   What happens is that the panel detects Sawfish has gone away, and
   turns on override redirect mode because no GNOME-aware WM is
   running (i.e. it goes into "ignore the window manager" mode). But
   the panel doesn't notice that Metacity has appeared and is
   (partially) GNOME-compliant. So Metacity doesn't see the override
   redirect panel, and leaves it behind the Nautilus desktop. I'm not
   sure whether Metacity or the panel is to blame for this.

   (To debug - use "xwininfo" on the panel, if override redirect is
    "Yes" then Metacity won't have any awareness of a window and can't
    properly stack it above the desktop. If override redirect is "No"
    then Metacity can see the panel and handle it properly. Look at
    xstuff.c:xstuff_is_compliant_wm() in the panel to get started on
    how the panel deals with this.)

 - In GNOME 1.x, If you have "put panel below other windows" turned on
   in panel Global Preferences, Miscellaneous tab, you need to change
   this to "Put panel on top of other windows." That's because
   Metacity uses semantic categories, not the legacy layer system in
   the GNOME spec. It treats things in the legacy "dock" layer as
   semantic type dock, but if you have the panel set to be in another
   layer, Metacity will think it's a normal window.

   You can diagnose this problem because Metacity will put panels in 
   the wrong place, and Alt+rightclick will let you perform operations
   like minimize/maximize, and Alt+leftclick will let you move the panel.
   If Metacity has detected that the panel is a panel, then none of 
   this will be enabled.

   I put a patch in the CVS version of the panel to fix this by 
   setting the new non-legacy type hint, but a panel with that 
   patch hasn't been released yet.

FAQ
===

Q: Will you add my feature?

A: If it makes sense to turn on unconditionally,
   or is genuinely a harmless preference that I would not 
   be embarrassed to put in a simple, uncluttered, user-friendly
   configuration dialog.

   If the only rationale for your feature is that other window
   managers have it, or that you are personally used to it, or something
   like that, then I will not be impressed. Metacity is firmly in the
   "choose good defaults" camp rather than the "offer 6 equally broken
   ways to do it, and let the user pick one" camp.

   This is part of a "no crackrock" policy, despite some exceptions
   I'm mildly embarrassed about. For example, multiple workspaces
   probably constitute crackrock, they confuse most users
   and really are not that useful if you have a decent tasklist and 
   so on. But I am too used to them to turn them off.
   Or alternatively iconification/tasklist is crack, and workspaces/pager
   are good. But having both is certainly a bit wrong.
   Sloppy focus is probably crackrock too. Oh, and my Alt-1 thru Alt-6
   keybindings are definitely on crack.

   But don't think unlimited crack is OK just because I slipped up a
   little. No slippery slope here.   

   Don't let this discourage patches and fixes - I love those. ;-)
   Just be prepared to hear the above objections if your patch
   adds some crack-ridden configuration option.

Q: Will Metacity be part of GNOME?

A: Many people are now asking for this, though it was not the original 
   plan - Metacity started out as sort of an experiment. 

   A decision hasn't really been made but the issue will probably 
   be raised shortly after the GNOME 2 release.

Q: Is Metacity a Red Hat project?

A: Metacity is 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.
 
Q: Why does Metacity remember the workspace/position of some apps 
   but not others?

A: Metacity 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.

   The reason is that you don't know which non-SM-aware apps were
   launched by the session. When you initially log in, Metacity sees a
   bunch of new windows appear. But it can't distinguish between
   windows that were stored in your session, or windows you just
   launched after logging in. If Metacity tried to guess that a window
   was from the session, it could e.g. end up maximizing a dialog, or
   put a window you just launched on another desktop or in a weird
   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
   application instance is from the session and thus restore it
   reliably, assuming the app properly restores the windows it had 
   open on session save.
   
   So the correct way to fix the situation is to make apps
   session-aware. libSM has come with X for years, it's very
   standardized, it's shared by GNOME and KDE - even twm is
   session-aware. So anyone who won't take a patch to add SM is more
   archaic than twm - and you should flame them. ;-)

   Docs on session management:
    ftp://ftp.x.org/pub/R6.4/xc/doc/hardcopy/SM/xsmp.PS.gz
    ftp://ftp.x.org:21/pub/R6.4/xc/doc/hardcopy/SM/SMlib.PS.gz

   See also the ICCCM section on SM. For GNOME apps, use the
   GnomeClient object. For a simple example of using libSM directly,
   twm/session.c in the twm source code is pretty easy to understand.

Q: How about adding viewports in addition to workspaces?

A: I could conceivably be convinced to use viewports _instead_ of
   workspaces, though currently I'm not thinking that. But I don't
   think it makes any sense to have both; it's just confusing. They
   are functionally equivalent.

   You may think this means that you won't have certain keybindings, 
   or something like that. This is a misconception. The only 
   _fundamental_ difference between viewports and workspaces is that 
   with viewports, windows can "overlap" and appear partially on 
   one and partially on another. All other differences that
   traditionally exist in other window managers are accidental - 
   the features commonly associated with viewports can be implemented
   for workspaces, and vice versa.

   So I don't want to have two kinds of
   workspace/desktop/viewport/whatever, but I'm willing to add
   features traditionally associated with either kind if those
   features make sense.

Q: Did you spend a lot of time on this?

A: Originally the answer was no. Sadly the answer is now yes.
   Still, it's only 12,000 lines of code.

Q: How can you claim that you are anti-crack, while still 
   writing a window manager?

A: I have no comment on that.