1Metacity is not a meta-City as in an urban center, but rather
2Meta-ness as in the state of being meta. i.e. metacity : meta as
3opacity : opaque. Also it may have something to do with the Meta key
4on UNIX keyboards.
5
6The first release of Metacity was version 2.3. Metacity has no need for
7your petty hangups about version numbers.
8
9The stable releases so far are 2.4.x, 2.6.x, 2.8.[01], 2.8.1.x, 2.8.5-,
102.10.x, 2.12.x, 2.14.x, 2.16.x.
11
12Unstable branches are 2.3.x, 2.5.x, 2.8.2-4, 2.9.x, 2.11.x, 2.13.x,
132.15.x, 2.17.x.
14
15COMPILING MUFFIN
16===
17
18You need GTK+ 2.2. For startup notification to work you need
19libstartup-notification at
20http://www.freedesktop.org/software/startup-notification/ or on the
21GNOME ftp site.
22You need Clutter 1.0. You need gobject-introspection 0.6.3.
23
24REPORTING BUGS AND SUBMITTING PATCHES
25===
26
27Report new bugs on http://bugzilla.gnome.org. Please check for
28duplicates, *especially* if you are reporting a feature request.
29
30Please do *not* add "me too!" or "yes I really want this!" comments to
31feature requests in bugzilla. Please read
32http://pobox.com/~hp/features.html prior to adding any kind of flame
33about missing features or misfeatures.
34
35Feel free to send patches too; Metacity is relatively small and
36simple, so if you find a bug or want to add a feature it should be
37pretty easy. Send me mail, or put the patch in bugzilla.
38
39See the HACKING file for some notes on hacking Muffin.
40
41MUFFIN FEATURES
42===
43
44 - Uses GTK+ 2.0 for drawing window frames. This means colors, fonts,
45 etc. come from GTK+ theme.
46
47 - Does not expose the concept of "window manager" to the user. Some
48 of the features in the GNOME control panel and other parts of the
49 desktop happen to be implemented in metacity, such as changing your
50 window border theme, or changing your window navigation shortcuts,
51 but the user doesn't need to know this.
52
53 - Includes only the window manager; does not try to be a desktop
54 environment. The pager, configuration, etc. are all separate and
55 modular. The "libwnck" library (which I also wrote) is available
56 for writing metacity extensions, pagers, and so on. (But libwnck
57 isn't metacity specific, or GNOME-dependent; it requires only GTK,
58 and should work with KWin, fvwm2, and other EWMH-compliant WMs.)
59
60 - Has a simple theme system and a couple of extra themes come with it.
61 Change themes via gsettings:
62 gsettings set org.cinnamon.desktop.wm.preferences theme Crux
63 gsettings set org.cinnamon.desktop.wm.preferences theme Gorilla
64 gsettings set org.cinnamon.desktop.wm.preferences theme Atlanta
65 gsettings set org.cinnamon.desktop.wm.preferences theme Bright
66
67 See theme-format.txt for docs on the theme format. Use
68 metacity-theme-viewer to preview themes.
69
70 - Change number of workspaces via gsettings:
71 gsettings set org.cinnamon.desktop.wm.preferences num-workspaces 5
72
73 Can also change workspaces from GNOME 2 pager.
74
75 - Change focus mode:
76 gsettings set org.cinnamon.desktop.wm.preferences focus-mode mouse
77 gsettings set org.cinnamon.desktop.wm.preferences focus-mode sloppy
78 gsettings set org.cinnamon.desktop.wm.preferences focus-mode click
79
80 - Global keybinding defaults include:
81
82 Alt-Tab forward cycle window focus
83 Alt-Shift-Tab backward cycle focus
84 Alt-Ctrl-Tab forward cycle focus among panels
85 Alt-Ctrl-Shift-Tab backward cycle focus among panels
86 Alt-Escape cycle window focus without a popup thingy
87 Ctrl-Alt-Left Arrow previous workspace
88 Ctrl-Alt-Right Arrow next workspace
89 Ctrl-Alt-D minimize/unminimize all, to show desktop
90
91 Change keybindings for example:
92
93 gsettings set org.cinnamon.desktop.wm.keybindings switch-to-workspace-1 '[<Alt>F1]'
94
95 Also try the GNOME keyboard shortcuts control panel.
96
97 - Window keybindings:
98
99 Alt-space window menu
100
101 Mnemonics work in the menu. That is, Alt-space then underlined
102 letter in the menu item works.
103
104 Choose Move from menu, and arrow keys to move the window.
105
106 While moving, hold down Control to move slower, and
107 Shift to snap to edges.
108
109 Choose Resize from menu, and nothing happens yet, but
110 eventually I might implement something.
111
112 Keybindings for things like maximize window, vertical maximize,
113 etc. can be bound, but may not all exist by default. See
114 metacity.schemas.
115
116 - Window mouse bindings:
117
118 Clicking anywhere on frame with button 1 will raise/focus window
119
120 If you click a window control, such as the close button, then the
121 control will activate on button release if you are still over it
122 on release (as with most GUI toolkits)
123
124 If you click and drag borders with button 1 it resizes the window
125
126 If you click and drag the titlebar with button 1 it moves the
127 window.
128
129 If you click anywhere on the frame with button 2 it lowers the
130 window.
131
132 If you click anywhere on the frame with button 3 it shows the
133 window menu.
134
135 If you hold down Super (windows key) and click inside a window, it
136 will move the window (buttons 1 and 2) or show menu (button 3).
137 Or you can configure a different modifier for this.
138
139 If you pick up a window with button 1 and then switch workspaces
140 the window will come with you to the new workspace, this is
141 a feature copied from Enlightenment.
142
143 If you hold down Shift while moving a window, the window snaps
144 to edges of other windows and the screen.
145
146 - Session management:
147
148 Muffin connects to the session manager and will set itself up to
149 be respawned. It theoretically restores sizes/positions/workspace
150 for session-aware applications.
151
152 - Muffin implements much of the EWMH window manager specification
153 from freedesktop.org, as well as the older ICCCM. Please refer to
154 the COMPLIANCE file for information on muffin compliance with
155 these standards.
156
157 - Uses Pango to render text, so has cool i18n capabilities.
158 Supports UTF-8 window titles and such.
159
160 - There are simple animations for actions such as minimization,
161 to help users see what is happening. Should probably
162 have a few more of these and make them nicer.
163
164 - if you have the proper X setup, set the GDK_USE_XFT=1
165 environment variable to get antialiased window titles.
166
167 - considers the panel when placing windows and maximizing
168 them.
169
170 - handles the window manager selection from the ICCCM. Will exit if
171 another WM claims it, and can claim it from another WM if you pass
172 the --replace argument. So if you're running another
173 ICCCM-compliant WM, you can run "muffin --replace" to replace it
174 with Metacity.
175
176 - does basic colormap handling
177
178 - and much more! well, maybe not a lot more.
179
180HOW TO ADD EXTERNAL FEATURES
181===
182
183You can write a muffin "plugin" such as a pager, window list, icon
184box, task menu, or even things like "window matching" using the
185Extended Window Manager Hints. See http://www.freedesktop.org for the
186EWMH specification. An easy-to-use library called "libwnck" is
187available that uses the EWMH and is specifically designed for writing
188WM accessories.
189
190You might be interested in existing accessories such as "Devil's Pie"
191by Ross Burton, which add features to Muffin (or other
192EWMH-compliant WMs).
193
194MUFFIN BUGS, NON-FEATURES, AND CAVEATS
195===
196
197See bugzilla: http://bugzilla.gnome.org/query.cgi
198
199FAQ
200===
201
202Q: Will you add my feature?
203
204A: If it makes sense to turn on unconditionally, or is genuinely a
205 harmless preference that I would not be embarrassed to put in a
206 simple, uncluttered, user-friendly configuration dialog.
207
208 If the only rationale for your feature is that other window
209 managers have it, or that you are personally used to it, or
210 something like that, then I will not be impressed. Metacity is
211 firmly in the "choose good defaults" camp rather than the "offer 6
212 equally broken ways to do it, and let the user pick one" camp.
213
214 This is part of a "no crackrock" policy, despite some exceptions
215 I'm mildly embarrassed about. For example, multiple workspaces
216 probably constitute crackrock, they confuse most users and really
217 are not that useful if you have a decent tasklist and so on. But I
218 am too used to them to turn them off. Or alternatively
219 iconification/tasklist is crack, and workspaces/pager are good. But
220 having both is certainly a bit wrong. Sloppy focus is probably
221 crackrock too.
222
223 But don't think unlimited crack is OK just because I slipped up a
224 little. No slippery slope here.
225
226 Don't let this discourage patches and fixes - I love those. ;-)
227 Just be prepared to hear the above objections if your patch adds
228 some crack-ridden configuration option.
229
230 http://pobox.com/~hp/free-software-ui.html
231 http://pobox.com/~hp/features.html
232
233Q: Will Muffin be part of GNOME?
234
235A: It is not officially part of GNOME as of GNOME 2.27. We are
236 hoping to have muffin officially included as of GNOME 2.28.
237
238Q: Why does Muffin remember the workspace/position of some apps
239 but not others across logout/login?
240
241A: Muffin only stores sizes/positions for apps that are session
242 managed. As far as I can determine, there is no way to attempt to
243 remember workspace/position for non-session-aware apps without
244 causing a lot of weird effects.
245
246 The reason is that you don't know which non-SM-aware apps were
247 launched by the session. When you initially log in, Metacity sees a
248 bunch of new windows appear. But it can't distinguish between
249 windows that were stored in your session, or windows you just
250 launched after logging in. If Metacity tried to guess that a window
251 was from the session, it could e.g. end up maximizing a dialog, or
252 put a window you just launched on another desktop or in a weird
253 place. And in fact I see a lot of bugs like this in window managers
254 that try to handle non-session-aware apps.
255
256 However, for session-aware apps, Muffin can tell that the
257 application instance is from the session and thus restore it
258 reliably, assuming the app properly restores the windows it had
259 open on session save.
260
261 So the correct way to fix the situation is to make apps
262 session-aware. libSM has come with X for years, it's very
263 standardized, it's shared by GNOME and KDE - even twm is
264 session-aware. So anyone who won't take a patch to add SM is more
265 archaic than twm - and you should flame them. ;-)
266
267 Docs on session management:
268 http://www.fifi.org/doc/xspecs/xsmp.txt.gz
269 http://www.fifi.org/doc/xspecs/SMlib.txt.gz
270
271 See also the ICCCM section on SM. For GNOME apps, use the
272 GnomeClient object. For a simple example of using libSM directly,
273 twm/session.c in the twm source code is pretty easy to understand.
274
275Q: How about adding viewports in addition to workspaces?
276
277A: I could conceivably be convinced to use viewports _instead_ of
278 workspaces, though currently I'm not thinking that. But I don't
279 think it makes any sense to have both; it's just confusing. They
280 are functionally equivalent.
281
282 You may think this means that you won't have certain keybindings,
283 or something like that. This is a misconception. The only
284 _fundamental_ difference between viewports and workspaces is that
285 with viewports, windows can "overlap" and appear partially on
286 one and partially on another. All other differences that
287 traditionally exist in other window managers are accidental -
288 the features commonly associated with viewports can be implemented
289 for workspaces, and vice versa.
290
291 So I don't want to have two kinds of
292 workspace/desktop/viewport/whatever, but I'm willing to add
293 features traditionally associated with either kind if those
294 features make sense.
295
296Q: Why is the panel always on top?
297
298A: Because it's a better user interface, and until we made this not
299 configurable a bunch of apps were not getting fixed (the app
300 authors were just saying "put your panel on the bottom" instead of
301 properly supporting fullscreen mode, and such).
302
303 rationales.txt has the bugzilla URL for some flamefesting on this,
304 if you want to go back and relive the glory.
305 Read these and the bugzilla stuff before asking/commenting:
306 http://pobox.com/~hp/free-software-ui.html
307 http://pobox.com/~hp/features.html
308
309Q: Why is there no edge flipping?
310
311A: This one is also in rationales.txt. Because "ouija board" UI, where
312 you just move the mouse around and the computer guesses what you
313 mean, has a lot of issues. This includes mouse focus, shade-hover
314 mode, edge flipping, autoraise, etc. Metacity has mouse focus and
315 autoraise as a compromise, but these features are all confusing for
316 many users, and cause problems with accessibility, fitt's law, and
317 so on.
318
319 Read these and the bugzilla stuff before asking/commenting:
320 http://pobox.com/~hp/free-software-ui.html
321 http://pobox.com/~hp/features.html
322
323Q: Why does wireframe move/resize suck?
324
325A: You can turn it on with the reduced_resources setting.
326
327 But: it has low usability, and is a pain
328 to implement, and there's no reason opaque move/resize should be a
329 problem on any setup that can run a modern desktop worth a darn to
330 begin with.
331
332 Read these and the bugzilla stuff before asking/commenting:
333 http://pobox.com/~hp/free-software-ui.html
334 http://pobox.com/~hp/features.html
335
336 The reason we had to add wireframe anyway was broken
337 proprietary apps that can't handle lots of resize events.
338
339Q: Why no XYZ?
340
341A: You are probably getting the idea by now - check rationales.txt,
342 query/search bugzilla, and read http://pobox.com/~hp/features.html
343 and http://pobox.com/~hp/free-software-ui.html
344
345 Then sit down and answer the question for yourself. Is the feature
346 good? What's the rationale for it? Answer "why" not just "why not."
347 Justify in terms of users as a whole, not just users like
348 yourself. How else can you solve the same problem? etc. If that
349 leads you to a strong opinion, then please, post the rationale for
350 discussion to an appropriate bugzilla bug, or to
351 usability@gnome.org.
352
353 Please don't just "me too!" on bugzilla bugs, please don't think
354 flames will get you anywhere, and please don't repeat rationale
355 that's already been offered.
356
357Q: Your dumb web pages you made me read talk about solving problems in
358 fundamental ways instead of adding preferences or workarounds.
359 What are some examples where metacity has done this?
360
361A: There are quite a few, though many opportunities remain. Sometimes
362 the real fix involves application changes. The metacity approach is
363 that it's OK to require apps to change, though there are also
364 plenty of workarounds in metacity for battles considered too hard
365 to fight.
366
367 Here are some examples:
368
369 - fullscreen mode was introduced to allow position constraints,
370 panel-on-top, and other such things to apply to normal windows
371 while still allowing video players etc. to "just work"
372
373 - "whether to include minimized windows in Alt+Tab" was solved
374 by putting minimized windows at the *end* of the tab order.
375
376 - Whether to pop up a feedback display during Alt+Tab was solved by
377 having both Alt+Tab and Alt+Esc
378
379 - Whether to have a "kill" feature was solved by automatically
380 detecting and offering to kill stuck apps. Better, metacity
381 actually does "kill -9" on the process, it doesn't just
382 disconnect the process from the X server. You'll appreciate this
383 if you ever did a "kill" on Netscape 4, and watched it keep
384 eating 100% CPU even though the X server had booted it.
385
386 - The workspaces vs. viewports mess was avoided by adding
387 directional navigation and such to workspaces, see discussion
388 earlier in this file.
389
390 - Instead of configurable placement algorithms, there's just one
391 that works fairly well most of the time.
392
393 - To avoid excess CPU use during opaque move/resize, we rate limit
394 the updates to the application window's size.
395
396 - Instead of configurable "show size of window while resizing,"
397 it's only shown for windows where it matters, such as terminals.
398 (Only use-case given for all windows is for web designers
399 choosing their web browser size, but there are web sites and
400 desktop backgrounds that do this for you.)
401
402 - Using startup notification, applications open on the workspace
403 where you launched them, not the active workspace when their
404 window is opened.
405
406 - and much more.
407
408Q: I think muffin sucks.
409
410A: Feel free to use any WM you like. The reason metacity follows the
411 ICCCM and EWMH specifications is that it makes metacity a modular,
412 interchangeable part in the desktop. libwnck-based apps such as the
413 GNOME window list will work just fine with any EWMH-compliant WM.
414
415Q: Did you spend a lot of time on this?
416
417A: Originally the answer was no. Sadly the answer is now yes.
418
419Q: How can you claim that you are anti-crack, while still
420 writing a window manager?
421
422A: I have no comment on that.
423