How Metacity's Window History Works:
------------------------------------

Metacity saves window position and state between window appearances.
Thus, if an application is started and the user in unhappy with the
way the window is positioned, Metacity will remember where the user
has moved this window if it appears again, even if the user has logged
out.

Window history is stored in ~/.metacity/window_history using a simple
XML format.  This is a sample of the format:
 
The file format is:
<metacity_history>
  <window class="XTerm" name="xterm" title="/foo/bar" role="blah" type="normal" num="0" updated="1039026079">
    <geometry x="100" y="100" width="200" height="200" gravity="northwest"/>
    <sticky/>
    <maximized/>
  </window>
  <window save_id="Some String" updated="1039026093">
    <fullscreen/>
  </window>
  :
</metacity_session>

Metacity loads this file once during initialization right after it
opens the display.  The file is written out as Metacity is exiting.

Window history is not consulted or updated on windows which exist when
Metacity is starting.

The attributes "class", "name", "role", and "num" are all used to
generate a unique string to track the life of the window.  Of all the
attributes, "num" is the only portion generated by Metacity to insure
the strings are unique.  The others are obtained from the window
itself.

If a window has the property _NET_WM_GEOMETRY_SAVE_ID set with a
string, Metacity will instead track changes to the window using this
string and will not perform the auto-numbering.  This means that an
application should prevent multiple windows appearing with the same
_NET_WM_GEOMETRY_SAVE_ID string set, or Metacity will recall the
position only of the last moved window with that string.

If a window has the property _NET_WM_GEOMETRY_SAVE_ID set with an
empty string, Metacity will not remember the position of this window
at all.  This is useful if the application wants to handle all
placement of it's windows itself.

Metacity uses a straightforward algorithm to determine the "num"
attribute.

When a window is mapped, it is given a number of -1 which means
undefined.  During placement, the list of windows on the current
workspace is scanned for windows with similar class/name/role
characteristics.  (Scan for windows like that with num 0, 1, 2, 3,
etc.)  Assign num to the next open slot.  Check the history for an
entry matching class/name/role/num and retrieve the saved position
of the window, if any.  

If a match is found, scan the list of windows to make sure no window
is already in the stored position.  If it is, fall back to other
placement routines.  (Currently, First fit placement, then cascade.)

If a match is not found, fall back to other placement routines.

When a window is moved, check the list of similar windows and try to
find a lower number which isn't allocated currently.  Update the saved
state with the new window position.

We try to find a smaller window number for this reason:

   - Open 3 calculators.  Move them around and then close the first
     two.  Use the third for a while and move it to a nice spot.
     Close the final calculator.  Where should the calculator start if
     you open a new one now?  It should start where you last left the
     final calculator before you closed it.

Window state like stickiness, window size, maximization, and full
screen mode are all saved and restored as well, although they are
saved only for windows which have been moved first.



