docs: Remove outdated documentation
The value of those documents is questionable. They mostly refer to the X11 complications and have not been updated for a long time. Let's just get rid of them. Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3465>
This commit is contained in:
Sebastian Wick
Marge Bot
parent
4f68713020
commit
86d61de5bd
@ -1,185 +0,0 @@
|
|||||||
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-drag.c
|
|
||||||
_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
|
|
||||||
@ -1,46 +0,0 @@
|
|||||||
The compositor is the box of tricks inside the window manager which performs
|
|
||||||
special effects on the windows on your screen. Metacity's compositor is
|
|
||||||
under development. Your help is requested in finding and fixing bugs. This
|
|
||||||
document tells you how to configure Metacity so that you can use compositing.
|
|
||||||
|
|
||||||
To turn the compositor on initially, you need to pass --enable-compositor to
|
|
||||||
the configure script. This will introduce a dependence on libcm, which you
|
|
||||||
can get from <URL:http://ftp.gnome.org/pub/GNOME/sources/libcm/>.
|
|
||||||
|
|
||||||
When Metacity is compiled, you will need to turn the compositor on in gconf
|
|
||||||
for it to have any effect. You will find the boolean switch at
|
|
||||||
|
|
||||||
/apps/metacity/general/compositing_manager
|
|
||||||
|
|
||||||
When that's done, you can set some environment variables before you launch
|
|
||||||
Metacity to influence how the compositor works. These will eventually become
|
|
||||||
configuration options or gconf options when they grow up. Define them to any
|
|
||||||
value to turn them on; leave them undefined to turn them off. Currently the
|
|
||||||
options you can set are:
|
|
||||||
|
|
||||||
LIBCM_DIRECT
|
|
||||||
|
|
||||||
If this is set, the compositor will bypass the X server and do all its
|
|
||||||
work directly with the hardware. I know of no reason you would want to
|
|
||||||
do so, but perhaps you do.
|
|
||||||
|
|
||||||
LIBCM_TFP
|
|
||||||
|
|
||||||
If this is set ("tfp mode"), the compositor will feel free to use the
|
|
||||||
texture_from_pixmap extension; if this is not set ("non-tfp mode"), the
|
|
||||||
compositor will use a workaround. Many drivers require non-tfp mode in
|
|
||||||
order to work, and will paint all windows clear blue or clear white
|
|
||||||
without it. Thanks to Travis Watkins for suggesting this switch; he
|
|
||||||
cautions that some games or video players may require tfp mode.
|
|
||||||
|
|
||||||
METACITY_BLING
|
|
||||||
|
|
||||||
This turns on several pretty but non-essential animations (dialogues
|
|
||||||
fracturing and exploding, minimisations doing a shrinkydink effect,
|
|
||||||
and so on). If it is not set, the standard non-GL animations are
|
|
||||||
retained. This affects only window event animations; it doesn't change
|
|
||||||
menus zooming, dialogues being semi-transparent, and so on. Try it
|
|
||||||
and see whether you like it.
|
|
||||||
|
|
||||||
If you have any problems, ask on mutter-devel-list@gnome.org, or
|
|
||||||
#gnome-hackers on gimpnet, or come and find me (tthurman at gnome) and ask.
|
|
||||||
@ -1,32 +0,0 @@
|
|||||||
Dialogs which have no transient parent or root window being
|
|
||||||
their tranisent parent are the ones which will be visible in
|
|
||||||
the tasklist.
|
|
||||||
|
|
||||||
All such dialogs will be *always* on top of the window
|
|
||||||
group i.e they would transients for the whole group.
|
|
||||||
|
|
||||||
|
|
||||||
1) Modal dialogs
|
|
||||||
|
|
||||||
|
|
||||||
* If you wish to open another window from a modal dialog
|
|
||||||
|
|
||||||
open *only* a modal dialog and set it's transient parent.
|
|
||||||
|
|
||||||
|
|
||||||
2) Normal dialog
|
|
||||||
|
|
||||||
|
|
||||||
without transient parent
|
|
||||||
|
|
||||||
* If you wish to open another window from a normal dialog
|
|
||||||
|
|
||||||
open either a normal dialog or a modal dialog only.
|
|
||||||
Set the transient parent for the child dialog if you do not
|
|
||||||
want them to be transient for all the other windows in the group.
|
|
||||||
|
|
||||||
with transient parent
|
|
||||||
|
|
||||||
* If you wish to open another window from a normal dialog
|
|
||||||
|
|
||||||
you could open any type of window.
|
|
||||||
@ -1,79 +0,0 @@
|
|||||||
|
|
||||||
History
|
|
||||||
====
|
|
||||||
|
|
||||||
Focus issues:
|
|
||||||
see doc/how-to-get-focus-right.txt
|
|
||||||
|
|
||||||
Keep panel always on top:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=81551
|
|
||||||
|
|
||||||
Edge flipping:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=82917
|
|
||||||
|
|
||||||
Opaque resize:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=92618
|
|
||||||
|
|
||||||
Alt+click to move/resize:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=101151
|
|
||||||
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=80918
|
|
||||||
|
|
||||||
minimized windows in Alt+tab:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=89416
|
|
||||||
|
|
||||||
dialogs above entire app group:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=88926
|
|
||||||
|
|
||||||
display window size/position:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=85213
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=106645
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=130821
|
|
||||||
|
|
||||||
configure click actions, alt+click:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=83210
|
|
||||||
|
|
||||||
system modal dialogs:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=83357
|
|
||||||
|
|
||||||
workspace wrapping:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=89315
|
|
||||||
|
|
||||||
raise windows on click:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=326156
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=86108
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=115072
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=115753
|
|
||||||
|
|
||||||
Pointer warping:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=134353
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=134352
|
|
||||||
(Think about tasklist & window selector too; this would be a very bad idea)
|
|
||||||
|
|
||||||
|
|
||||||
Bugs for easy dupe-finding that seem to be hard to find otherwise:
|
|
||||||
===
|
|
||||||
Applications opening in wrong workspace:
|
|
||||||
http://bugzilla.gnome.org/show_bug.cgi?id=160687
|
|
||||||
|
|
||||||
|
|
||||||
Tracking bugs
|
|
||||||
====
|
|
||||||
|
|
||||||
revise theme format: http://bugzilla.gnome.org/show_bug.cgi?id=102547
|
|
||||||
session management: http://bugzilla.gnome.org/show_bug.cgi?id=107063
|
|
||||||
focus-stealing-prevention: http://bugzilla.gnome.org/show_bug.cgi?id=149028
|
|
||||||
other focus bugs: http://bugzilla.gnome.org/show_bug.cgi?id=155450
|
|
||||||
drag-and-drop: http://bugzilla.gnome.org/show_bug.cgi?id=155451
|
|
||||||
raising/stacking: http://bugzilla.gnome.org/show_bug.cgi?id=155452
|
|
||||||
tasklist/workspace switcher: http://bugzilla.gnome.org/show_bug.cgi?id=155453
|
|
||||||
window/workspace selection: http://bugzilla.gnome.org/show_bug.cgi?id=155456
|
|
||||||
key/mouse-binding actions: http://bugzilla.gnome.org/show_bug.cgi?id=155457
|
|
||||||
moving/resizing (constraints): http://bugzilla.gnome.org/show_bug.cgi?id=155458
|
|
||||||
window placement: http://bugzilla.gnome.org/show_bug.cgi?id=155460
|
|
||||||
logout/system-monitor keys: http://bugzilla.gnome.org/show_bug.cgi?id=155462
|
|
||||||
modal dialogs: http://bugzilla.gnome.org/show_bug.cgi?id=164841
|
|
||||||
multi-head sans xinerama: http://bugzilla.gnome.org/show_bug.cgi?id=324772
|
|
||||||
xinerama: http://bugzilla.gnome.org/show_bug.cgi?id=324773
|
|
||||||
output-only windows: http://bugzilla.gnome.org/show_bug.cgi?id=340584
|
|
||||||
allowed actions/window-type: http://bugzilla.gnome.org/show_bug.cgi?id=340682
|
|
||||||
EWMH/ICCCM compliance: http://bugzilla.gnome.org/show_bug.cgi?id=340691
|
|
||||||
@ -1,54 +0,0 @@
|
|||||||
How updates happen for struts, workareas, and screen/xinerama regions/edges:
|
|
||||||
One of three things causes meta_window_update_struts to be called
|
|
||||||
(a) initial window map (window.c:meta_window_new_with_attrs())
|
|
||||||
(b) update of _net_wm_strut* properties (window.c:process_property_notify())
|
|
||||||
(c) screen resizes (e.g. via xrandr; from screen.c:meta_screen_resize_func())
|
|
||||||
meta_window_update_struts (MetaWindow *window)
|
|
||||||
- Gets new list of struts from window properties
|
|
||||||
- Makes sure window doesn't single-handedly fill the screen
|
|
||||||
- records new struts if different and calls invalidate_work_areas()
|
|
||||||
invalidate_work_areas ()
|
|
||||||
- Calls meta_workspace_invalidate_work_area() for each workspace it's on
|
|
||||||
meta_workspace_invalidate_work_area()
|
|
||||||
- Cleans out all strut lists
|
|
||||||
- queues all windows for resizing
|
|
||||||
- Calls meta_screen_queue_workarea_recalc (workspace->screen);
|
|
||||||
meta_screen_queue_workarea_recalc()
|
|
||||||
- Adds set_work_area_idle_func() as an idle handler
|
|
||||||
|
|
||||||
set_work_area_idle_func()
|
|
||||||
- Calls set_work_area_hint()
|
|
||||||
set_work_area_hint()
|
|
||||||
- Calls meta_workspace_get_work_area_all_xineramas()
|
|
||||||
- Sets _NET_WORKAREA property
|
|
||||||
meta_workspace_get_work_area_all_xineramas()
|
|
||||||
- Calls ensure_work_areas_validated()
|
|
||||||
ensure_work_areas_validated()
|
|
||||||
- Loops over xineramas
|
|
||||||
- Loops over windows, then struts:
|
|
||||||
- Adds struts to list first time through xinerama loop
|
|
||||||
- Find the amount of the strut on the given xinerama for <dir>_strut
|
|
||||||
- Just max the amount of the strut with the all_<dir>_strut
|
|
||||||
- Makes sure there's a non-empty xinerama workarea
|
|
||||||
- Record the xinerama workarea
|
|
||||||
- Make sure there's a non-empty screen workarea
|
|
||||||
- Record the screen workarea
|
|
||||||
- Cache the spanning rects for the screen and xinerama regions
|
|
||||||
- Cache the screen and xinerama edges
|
|
||||||
|
|
||||||
Alternatively to all the above, if the idle function for the screen
|
|
||||||
has not yet fired, constraints.c:setup_constraint_info() can call
|
|
||||||
either workspace.c:meta_workspace_get_onscreen_region() or
|
|
||||||
workspace.c:meta_workspace_get_onxinerama_region() which in turn
|
|
||||||
call workspace.c:ensure_work_areas_validated().
|
|
||||||
|
|
||||||
Meaning of related functions that might be difficult to tell apart:
|
|
||||||
screen.c:meta_screen_get_current_xinerama ()
|
|
||||||
- Finds out which xinerama the mouse is on with an XQueryPointer
|
|
||||||
window.c:meta_window_get_work_area_current_xinerama()
|
|
||||||
window.c:meta_window_get_work_area_for_xinerama()
|
|
||||||
window.c:meta_window_get_work_area_all_xineramas ()
|
|
||||||
- All three are for finding the intersection of workareas across
|
|
||||||
multiple workspaces so that placement of windows can be
|
|
||||||
determined in such a way that they remain in the workarea for
|
|
||||||
all workspaces that they are on.
|
|
||||||
Loading…
Reference in New Issue
Block a user