brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Remove outdated documentation

Browse Source 
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 2023-12-18 17:26:10 +01:00 committed by Marge Bot
parent 4f68713020
commit 86d61de5bd
5 changed files with 0 additions and 396 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
doc/code-overview.txt
View File

@ -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

46
doc/compositor-control.txt
View File

@ -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.

32
doc/dialogs.txt
View File

@ -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.

79
doc/rationales.txt
View File

@ -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

54
doc/strut-and-related-updating.txt
View File

@ -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.