README 16.5 KB
Newer Older
1 2 3 4
The original codebase named "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.
rhp's avatar
rhp committed
5

6 7
Since then, it has been renamed mutter after a rebase on top of
clutter as a compositing manager.
Havoc Pennington's avatar
Havoc Pennington committed
8

9
COMPILING MUTTER
rhp's avatar
rhp committed
10 11
===

Havoc Pennington's avatar
Havoc Pennington committed
12 13
You need GTK+ 2.2.  For startup notification to work you need
libstartup-notification at
14
http://www.freedesktop.org/software/startup-notification/ or on the
15
GNOME ftp site.
16
You need Clutter 1.0. You need gobject-introspection 0.6.3.
rhp's avatar
rhp committed
17 18 19 20

REPORTING BUGS AND SUBMITTING PATCHES
===

Havoc Pennington's avatar
Havoc Pennington committed
21 22 23 24 25 26 27
Report new bugs on http://bugzilla.gnome.org. Please check for
duplicates, *especially* if you are reporting a feature request. 

Please do *not* add "me too!" or "yes I really want this!" comments to
feature requests in bugzilla. Please read
http://pobox.com/~hp/features.html prior to adding any kind of flame
about missing features or misfeatures.
rhp's avatar
rhp committed
28

29 30 31
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.
rhp's avatar
rhp committed
32

33
See the HACKING file for some notes on hacking Mutter.
rhp's avatar
rhp committed
34

35
MUTTER FEATURES
Havoc Pennington's avatar
Havoc Pennington committed
36 37
===

rhp's avatar
rhp committed
38 39 40
 - Uses GTK+ 2.0 for drawing window frames. This means colors, fonts, 
   etc. come from GTK+ theme.

Havoc Pennington's avatar
Havoc Pennington committed
41 42 43
 - Does not expose the concept of "window manager" to the user.  Some
   of the features in the GNOME control panel and other parts of the
   desktop happen to be implemented in metacity, such as changing your
44
   window border theme, or changing your window navigation shortcuts,
Havoc Pennington's avatar
Havoc Pennington committed
45 46 47 48 49 50 51 52 53
   but the user doesn't need to know this.

 - Includes only the window manager; does not try to be a desktop
   environment. The pager, configuration, etc. are all separate and
   modular. The "libwnck" library (which I also wrote) is available
   for writing metacity extensions, pagers, and so on. (But libwnck
   isn't metacity specific, or GNOME-dependent; it requires only GTK,
   and should work with KWin, fvwm2, and other EWMH-compliant WMs.)

Havoc Pennington's avatar
Havoc Pennington committed
54
 - Has a simple theme system and a couple of extra themes come with it.
55 56 57 58 59
   Change themes via gsettings:
     gsettings set org.gnome.desktop.wm.preferences theme Crux
     gsettings set org.gnome.desktop.wm.preferences theme Gorilla
     gsettings set org.gnome.desktop.wm.preferences theme Atlanta
     gsettings set org.gnome.desktop.wm.preferences theme Bright
60 61 62

   See theme-format.txt for docs on the theme format. Use 
   metacity-theme-viewer to preview themes.
Havoc Pennington's avatar
Havoc Pennington committed
63

64 65
 - Change number of workspaces via gsettings:
     gsettings set org.gnome.desktop.wm.preferences num-workspaces 5
Havoc Pennington's avatar
Havoc Pennington committed
66

67 68
   Can also change workspaces from GNOME 2 pager.

Havoc Pennington's avatar
Havoc Pennington committed
69
 - Change focus mode:
70 71 72
     gsettings set org.gnome.desktop.wm.preferences focus-mode mouse
     gsettings set org.gnome.desktop.wm.preferences focus-mode sloppy
     gsettings set org.gnome.desktop.wm.preferences focus-mode click
rhp's avatar
rhp committed
73

Havoc Pennington's avatar
Havoc Pennington committed
74
 - Global keybinding defaults include:   
75

Havoc Pennington's avatar
Havoc Pennington committed
76 77
    Alt-Tab                forward cycle window focus
    Alt-Shift-Tab          backward cycle focus
78 79
    Alt-Ctrl-Tab           forward cycle focus among panels
    Alt-Ctrl-Shift-Tab     backward cycle focus among panels
80
    Alt-Escape             cycle window focus without a popup thingy
Havoc Pennington's avatar
Havoc Pennington committed
81 82
    Ctrl-Alt-Left Arrow    previous workspace
    Ctrl-Alt-Right Arrow   next workspace
Havoc Pennington's avatar
Havoc Pennington committed
83
    Ctrl-Alt-D             minimize/unminimize all, to show desktop
rhp's avatar
rhp committed
84

85 86
   Change keybindings for example:

87
     gsettings set org.gnome.desktop.wm.keybindings switch-to-workspace-1 '[<Alt>F1]'
88
   
89
   Also try the GNOME keyboard shortcuts control panel.
Havoc Pennington's avatar
Havoc Pennington committed
90

rhp's avatar
rhp committed
91
 - Window keybindings:
92

rhp's avatar
rhp committed
93 94 95 96 97 98
    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.
rhp's avatar
rhp committed
99

rhp's avatar
rhp committed
100 101
    While moving, hold down Control to move slower, and 
      Shift to snap to edges.
rhp's avatar
rhp committed
102

rhp's avatar
rhp committed
103
    Choose Resize from menu, and nothing happens yet, but 
Havoc Pennington's avatar
Havoc Pennington committed
104
      eventually I might implement something.
rhp's avatar
rhp committed
105

Havoc Pennington's avatar
Havoc Pennington committed
106 107 108
    Keybindings for things like maximize window, vertical maximize,
    etc. can be bound, but may not all exist by default. See
    metacity.schemas.
109

rhp's avatar
rhp committed
110 111 112 113 114 115 116 117 118 119 120 121 122
 - 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.

Havoc Pennington's avatar
Havoc Pennington committed
123 124 125
    If you click anywhere on the frame with button 2 it lowers the 
     window.

rhp's avatar
rhp committed
126 127 128
    If you click anywhere on the frame with button 3 it shows the 
     window menu.

129 130 131
    If you hold down Super (windows key) and click inside a window, it
     will move the window (buttons 1 and 2) or show menu (button 3).
     Or you can configure a different modifier for this.
rhp's avatar
rhp committed
132

rhp's avatar
rhp committed
133 134
    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 
rhp's avatar
rhp committed
135 136
     a feature copied from Enlightenment.

rhp's avatar
rhp committed
137 138 139
    If you hold down Shift while moving a window, the window snaps
     to edges of other windows and the screen.

rhp's avatar
rhp committed
140 141
 - Session management:

142
    Mutter connects to the session manager and will set itself up to
rhp's avatar
rhp committed
143 144
     be respawned. It theoretically restores sizes/positions/workspace
     for session-aware applications.
rhp's avatar
rhp committed
145

146
 - Mutter implements much of the EWMH window manager specification
Rob Adams's avatar
Rob Adams committed
147
   from freedesktop.org, as well as the older ICCCM.  Please refer to
148
   the COMPLIANCE file for information on mutter compliance with
Rob Adams's avatar
Rob Adams committed
149
   these standards.
rhp's avatar
rhp committed
150

rhp's avatar
rhp committed
151 152 153
 - Uses Pango to render text, so has cool i18n capabilities. 
   Supports UTF-8 window titles and such.

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

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

Havoc Pennington's avatar
Havoc Pennington committed
161 162 163
 - considers the panel when placing windows and maximizing
   them.

Havoc Pennington's avatar
Havoc Pennington committed
164 165 166
 - 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
167
   ICCCM-compliant WM, you can run "mutter --replace" to replace it
Havoc Pennington's avatar
Havoc Pennington committed
168 169 170 171
   with Metacity.

 - does basic colormap handling

Havoc Pennington's avatar
Havoc Pennington committed
172 173
 - and much more! well, maybe not a lot more.

Havoc Pennington's avatar
Havoc Pennington committed
174 175 176
HOW TO ADD EXTERNAL FEATURES
===

177
You can write a mutter "plugin" such as a pager, window list, icon
Havoc Pennington's avatar
Havoc Pennington committed
178 179 180 181 182 183 184
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
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"
185
by Ross Burton, which add features to Mutter (or other
Havoc Pennington's avatar
Havoc Pennington committed
186 187
EWMH-compliant WMs).

188
MUTTER BUGS, NON-FEATURES, AND CAVEATS
rhp's avatar
rhp committed
189 190
===

Havoc Pennington's avatar
Havoc Pennington committed
191
See bugzilla: http://bugzilla.gnome.org/query.cgi
rhp's avatar
rhp committed
192

rhp's avatar
rhp committed
193 194 195 196 197
FAQ
===

Q: Will you add my feature?

Havoc Pennington's avatar
Havoc Pennington committed
198 199 200
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.
rhp's avatar
rhp committed
201 202

   If the only rationale for your feature is that other window
Havoc Pennington's avatar
Havoc Pennington committed
203 204 205 206
   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.
rhp's avatar
rhp committed
207

rhp's avatar
rhp committed
208
   This is part of a "no crackrock" policy, despite some exceptions
rhp's avatar
rhp committed
209
   I'm mildly embarrassed about. For example, multiple workspaces
Havoc Pennington's avatar
Havoc Pennington committed
210 211 212 213 214 215
   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.
rhp's avatar
rhp committed
216 217

   But don't think unlimited crack is OK just because I slipped up a
Havoc Pennington's avatar
Havoc Pennington committed
218
   little. No slippery slope here.
rhp's avatar
rhp committed
219 220

   Don't let this discourage patches and fixes - I love those. ;-)
Havoc Pennington's avatar
Havoc Pennington committed
221 222
   Just be prepared to hear the above objections if your patch adds
   some crack-ridden configuration option.
rhp's avatar
rhp committed
223

Havoc Pennington's avatar
Havoc Pennington committed
224
   http://pobox.com/~hp/free-software-ui.html
Havoc Pennington's avatar
Havoc Pennington committed
225
   http://pobox.com/~hp/features.html   
Havoc Pennington's avatar
Havoc Pennington committed
226

227
Q: Will Mutter be part of GNOME?
rhp's avatar
rhp committed
228

229 230
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. 
Havoc Pennington's avatar
Havoc Pennington committed
231

232
Q: Why does Mutter remember the workspace/position of some apps 
Havoc Pennington's avatar
Havoc Pennington committed
233
   but not others across logout/login?
rhp's avatar
rhp committed
234

235
A: Mutter only stores sizes/positions for apps that are session
Havoc Pennington's avatar
Havoc Pennington committed
236 237
   managed. As far as I can determine, there is no way to attempt to
   remember workspace/position for non-session-aware apps without
rhp's avatar
rhp committed
238 239 240 241 242 243 244
   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
rhp's avatar
rhp committed
245 246
   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
rhp's avatar
rhp committed
247 248 249
   place. And in fact I see a lot of bugs like this in window managers
   that try to handle non-session-aware apps.

250
   However, for session-aware apps, Mutter can tell that the
rhp's avatar
rhp committed
251 252 253 254 255 256 257 258 259 260 261
   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:
262 263
    http://www.fifi.org/doc/xspecs/xsmp.txt.gz
    http://www.fifi.org/doc/xspecs/SMlib.txt.gz
rhp's avatar
rhp committed
264

rhp's avatar
rhp committed
265 266 267
   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.
rhp's avatar
rhp committed
268 269 270 271 272 273 274 275

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.

276 277 278 279 280 281 282 283 284 285 286 287 288 289
   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.

Havoc Pennington's avatar
Havoc Pennington committed
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316
Q: Why is the panel always on top?

A: Because it's a better user interface, and until we made this not
   configurable a bunch of apps were not getting fixed (the app
   authors were just saying "put your panel on the bottom" instead of
   properly supporting fullscreen mode, and such).

   rationales.txt has the bugzilla URL for some flamefesting on this,
   if you want to go back and relive the glory.
   Read these and the bugzilla stuff before asking/commenting:
     http://pobox.com/~hp/free-software-ui.html
     http://pobox.com/~hp/features.html   

Q: Why is there no edge flipping?

A: This one is also in rationales.txt. Because "ouija board" UI, where
   you just move the mouse around and the computer guesses what you
   mean, has a lot of issues. This includes mouse focus, shade-hover
   mode, edge flipping, autoraise, etc. Metacity has mouse focus and
   autoraise as a compromise, but these features are all confusing for
   many users, and cause problems with accessibility, fitt's law, and
   so on.

   Read these and the bugzilla stuff before asking/commenting:
     http://pobox.com/~hp/free-software-ui.html
     http://pobox.com/~hp/features.html   

317
Q: Why does wireframe move/resize suck?
Havoc Pennington's avatar
Havoc Pennington committed
318

319
A: You can turn it on with the reduced_resources setting.
Havoc Pennington's avatar
Havoc Pennington committed
320

321
   But: it has low usability, and is a pain
Havoc Pennington's avatar
Havoc Pennington committed
322 323 324 325 326 327 328 329
   to implement, and there's no reason opaque move/resize should be a
   problem on any setup that can run a modern desktop worth a darn to
   begin with.

   Read these and the bugzilla stuff before asking/commenting:
     http://pobox.com/~hp/free-software-ui.html
     http://pobox.com/~hp/features.html   

Havoc Pennington's avatar
Havoc Pennington committed
330 331 332
   The reason we had to add wireframe anyway was broken 
   proprietary apps that can't handle lots of resize events.

Havoc Pennington's avatar
Havoc Pennington committed
333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401
Q: Why no XYZ?

A: You are probably getting the idea by now - check rationales.txt,
   query/search bugzilla, and read http://pobox.com/~hp/features.html
   and http://pobox.com/~hp/free-software-ui.html

   Then sit down and answer the question for yourself.  Is the feature
   good? What's the rationale for it? Answer "why" not just "why not."
   Justify in terms of users as a whole, not just users like
   yourself. How else can you solve the same problem? etc. If that
   leads you to a strong opinion, then please, post the rationale for
   discussion to an appropriate bugzilla bug, or to
   usability@gnome.org.

   Please don't just "me too!" on bugzilla bugs, please don't think
   flames will get you anywhere, and please don't repeat rationale
   that's already been offered.

Q: Your dumb web pages you made me read talk about solving problems in
   fundamental ways instead of adding preferences or workarounds.
   What are some examples where metacity has done this?

A: There are quite a few, though many opportunities remain.  Sometimes
   the real fix involves application changes. The metacity approach is
   that it's OK to require apps to change, though there are also
   plenty of workarounds in metacity for battles considered too hard
   to fight.

   Here are some examples:

   - fullscreen mode was introduced to allow position constraints,
     panel-on-top, and other such things to apply to normal windows
     while still allowing video players etc. to "just work"

   - "whether to include minimized windows in Alt+Tab" was solved 
     by putting minimized windows at the *end* of the tab order. 

   - Whether to pop up a feedback display during Alt+Tab was solved by
     having both Alt+Tab and Alt+Esc

   - Whether to have a "kill" feature was solved by automatically
     detecting and offering to kill stuck apps. Better, metacity
     actually does "kill -9" on the process, it doesn't just
     disconnect the process from the X server. You'll appreciate this
     if you ever did a "kill" on Netscape 4, and watched it keep
     eating 100% CPU even though the X server had booted it.

   - The workspaces vs. viewports mess was avoided by adding
     directional navigation and such to workspaces, see discussion
     earlier in this file.

   - Instead of configurable placement algorithms, there's just one 
     that works fairly well most of the time.

   - To avoid excess CPU use during opaque move/resize, we rate limit
     the updates to the application window's size.

   - Instead of configurable "show size of window while resizing,"
     it's only shown for windows where it matters, such as terminals.
     (Only use-case given for all windows is for web designers
     choosing their web browser size, but there are web sites and
     desktop backgrounds that do this for you.)

   - Using startup notification, applications open on the workspace
     where you launched them, not the active workspace when their
     window is opened.

   - and much more.

402
Q: I think mutter sucks.
Havoc Pennington's avatar
Havoc Pennington committed
403 404 405 406 407 408

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,
   interchangeable part in the desktop. libwnck-based apps such as the
   GNOME window list will work just fine with any EWMH-compliant WM.

rhp's avatar
rhp committed
409 410
Q: Did you spend a lot of time on this?

Havoc Pennington's avatar
Havoc Pennington committed
411
A: Originally the answer was no. Sadly the answer is now yes.
rhp's avatar
rhp committed
412 413 414 415 416

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

A: I have no comment on that.