1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
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.
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
|
