diff --git a/doc/code-overview.txt b/doc/code-overview.txt deleted file mode 100644 index 4a3be2ca8..000000000 --- a/doc/code-overview.txt +++ /dev/null @@ -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 diff --git a/doc/compositor-control.txt b/doc/compositor-control.txt deleted file mode 100644 index 1253cc3d6..000000000 --- a/doc/compositor-control.txt +++ /dev/null @@ -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 . - -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. diff --git a/doc/dialogs.txt b/doc/dialogs.txt deleted file mode 100644 index 1a28e6abf..000000000 --- a/doc/dialogs.txt +++ /dev/null @@ -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. diff --git a/doc/rationales.txt b/doc/rationales.txt deleted file mode 100644 index 600d2d5a2..000000000 --- a/doc/rationales.txt +++ /dev/null @@ -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 diff --git a/doc/strut-and-related-updating.txt b/doc/strut-and-related-updating.txt deleted file mode 100644 index a00cee4b2..000000000 --- a/doc/strut-and-related-updating.txt +++ /dev/null @@ -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 _strut - - Just max the amount of the strut with the all__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.