Diffstat (limited to 'doc/code-overview.txt')
1 files changed, 185 insertions, 0 deletions
diff --git a/doc/code-overview.txt b/doc/code-overview.txt
new file mode 100644
@@ -0,0 +1,185 @@
+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.
+ 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
+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):
+ 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):
+ The luminocity module in CVS
+ Window depth (i.e. stacking or lowering/raising) issues:
+ _NET_WM_MOUSE_ACTION/_NET_WM_TAKE_ACTIVITY? (aren't yet in EWMH)
+ Window placement issues:
+ Moving and resizing issues:
+ Drag and drop issues:
+ the XDND protocol (see http://www.newplanetsoftware.com/xdnd/ and
+ _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: ???
+ (ui.c, core.c, frames.c, frame.c? I dunno...)
+ Session management issues: ???
+ http://www.x.org/X11R6.8.1/doc/SM/xsmp.pdf ?
+ http://www.x.org/X11R6.8.1/doc/SM/SMlib.pdf ?
+ Tasklist and Workspace switcher issues:
+ various functions in screen.c (especially ones using XChangeProperty)
+ The libwnck module in cvs
+ Lots of the EWMH
+ Window and workspace selection/changing issues:
+ keybindings.c, functions: *_workspace*, *_tab_*
+ display.c, functions: *_tab*
+ Key and mouse binding actions:
+ 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