mutter/doc/code-overview.txt

This is not meant to be comprehensive by any means.  Rather it is
meant as just a brief overview of some of the bigger structures and
files, with guides for a variety of task categories providing places
to start looking in the code and things to look for.

Overview
  Jobs of various files
  Major data structures and their relationships
  Getting started -- where to look


Jobs of various files
  src/window.c is where all the guts of the window manager live. This is
  basically the only remotely scary file.

  src/frames.c is the GtkWidget that handles drawing window frames.

  src/core.h defines the interface used by the GTK portion of the window
  manager to talk to the other portions. There's some cruft in here that's
  unused, since nearly all window operations have moved out of this file so
  frameless apps can have window operations.

  src/ui.h defines the interface the plain Xlib portion of the window
  manager uses to talk to the GTK portion.

  src/theme.c and src/theme-parser.c have the theme system; this is
  well-modularized from the rest of the code, since the theme viewer app
  links to these files in addition to the WM itself.

Major data structures and their relationships
  Major structs have a "Meta" prefix, thus MetaDisplay, MetaScreen,
  MetaWindow, etc.  This serves as a way of namespacing in C.  It also has
  the side effect of avoiding conflicts with common names that X already
  uses such as Display, Screen, Window, etc.  Note that when I refer to a
  display below, I'm meaning a MetaDisplay and not a Display.

  Don't confuse displays and screens.  While Metacity can run with multiple
  displays, it is kind of useless since you might as well just run two
  copies of Metacity.  However, having multiple screens per display is
  useful and increasingly common (known as "multiscreen" and "xinerama"
  setups, where users make use of more than one monitor).  You should
  basically think of a display as a combination of one or more monitors
  with a single keyboard (...and usually only one mouse).

  There is also a significant difference between multiscreen and xinerama
  as well.  Basically, each MetaScreen is a root window (root node in the
  tree of windows).  With Xinerama, a single root window appears to span
  multiple monitors, whereas with multiscreen a root window is confined to
  a single monitor.  To re-emphasize the distinction between a display and
  a screen, the pointer and keyboard are shared between all root windows
  for a given display.

  The display keeps track of a lot of various global quantities, but in
  particular has a compositor and a list (GList) of screens.

  A compositor is an opaque structure (only defined in compositor.c),
  meaning that you'll only reference the API for it.  It handles (or will
  handle) cool stuff with the new X extensions, such as smooth resizing and
  alpha transparency.

  A screen keeps track of a number of quantities as well, in particular a
  stack and a list of workspaces.

  A stack is basically a list of windows, and the depth order they have
  relative to each other (which thus determines which windows are on top
  and which are obscured).

  A workspace mostly contains a list of windows for the workspace, but also
  has a few other quantities as well (a list of struts which are areas
  where windows should not be placed and an mru_list or "most recently used
  window list").

  A window has a huge list of quantities for keeping track of things about
  a window on the screen.  (We want to avoid making this list larger
  because the memory for all these quantities is per window.)  One item in
  particular that a window has, though, is a frame.

  A frame is the decorations that surround the window (i.e. the titlebar and
  the minimize and close buttons and the part that you can use to resize),
  and contains a handful of variables related to that, but no other major
  structures.

Getting started -- where to look
  Getting started on developing free software projects can often be like
  being dropped off in a town that is unknown to you and being told to make
  a map, when various road and building signs are missing or fading.  To
  try to alleviate that initial difficulty in orientation, below I list a
  variety of general task categories with file, function, variable, and x
  property names that may be useful to fixing bugs or writing features that
  fall within that category.

  First, though, it's useful to note that most event and message passing
  goes through display.c:event_callback(), so that's often a good place to
  start reading for general familiarity with the code (actually, I'd
  suggest skipping down to the first switch statement within that
  function).  Of course, not all events go through that function, as there
  are a few other places that handle events too such as frames.c.

  Anyway, without further ado, here are the categories and (hopefully)
  useful things to look at for each:

    Focus issues (i.e. issues with which window is active):
      doc/how-to-get-focus-right.txt
      meta_workspace_focus_default_window
      _NET_ACTIVE_WINDOW
      _NET_WM_USER_TIME
      meta_window_focus
      meta_display_(set_input|focus_the_no)_focus_window
      XSetInputFocus (only for purposes of understanding how X focus/input works)
      CurrentTime (mostly, you should just think "Bad; don't use it")

    Compositor stuff (X extension for eye candy like transparency):
      compositor.c
      The luminocity module in CVS

    Window depth (i.e. stacking or lowering/raising) issues:
      stack.c
      _NET_CLIENT_LIST_STACKING
      transient_for
      WM_TRANSIENT_FOR
      meta_window_(raise|lower)
      _NET_WM_WINDOW_TYPE
      _NET_WM_MOUSE_ACTION/_NET_WM_TAKE_ACTIVITY? (aren't yet in EWMH)

    Window placement issues:
      place.c
      constraints.c
      _NET_WM_STRUT
      WM_SIZE_HINTS

    Moving and resizing issues:
      constraints.c
      update_move
      update_resize
      meta_window_handle_mouse_grab_op_event
      _NET_MOVERESIZE_WINDOW
      _NET_WM_STRUT

    Drag and drop issues:
      the XDND protocol (see http://www.newplanetsoftware.com/xdnd/ and
        http://freedesktop.org/Standards/XDND)
      _NET_WM_MOUSE_ACTION/_NET_WM_TAKE_ACTIVITY (aren't yet in EWMH)
      A general pointer: what causes the difficulty here is that when the
        application receives a mouse click to start a drag, it does a grab
        so that the window manager doesn't get any further events; thus
        correcting things require standards so that applications and window
        managers can collaborate correctly

    Theme issues: ???
      doc/theme-format.txt
      theme.c
      theme-parser.c
      (ui.c, core.c, frames.c, frame.c?  I dunno...)

    Session management issues: ???
      session.c
      http://www.x.org/X11R6.8.1/doc/SM/xsmp.pdf ?
      http://www.x.org/X11R6.8.1/doc/SM/SMlib.pdf ?
      meta_window_apply_session_info

    Tasklist and Workspace switcher issues:
      window-props.c
      various functions in screen.c (especially ones using XChangeProperty)
      xprops.c
      The libwnck module in cvs
      meta_window_client_message
      Lots of the EWMH

    Window and workspace selection/changing issues:
      tabpopup.c
      keybindings.c, functions: *_workspace*, *_tab_*
      meta_screen_ensure_*_popup
      display.c, functions: *_tab*

    Key and mouse binding actions:
      keybindings.c
      meta_frames_button_(press|release)_event
      display.c: event_callback, but only the (Key|Button)_(Press|Release) cases

    Xinerama and multiscreen: ???
      In general, just search for Xinerama, but in particular see
      screen.c
      window.c
      place.c
      constraints.c