From 13918cea25645ed2229dde968829b220d2df3f65 Mon Sep 17 00:00:00 2001 From: Thomas Thurman Date: Sun, 13 Jan 2008 16:32:56 +0000 Subject: [PATCH] Commenting. Commenting, and fixing existing comments. 2008-01-13 Thomas Thurman * src/core/bell.c: Commenting. * src/core/main.c: Commenting, and fixing existing comments. svn path=/trunk/; revision=3518 --- ChangeLog | 5 ++ src/core/bell.c | 158 +++++++++++++++++++++++++++++++++++++++++++++++- src/core/main.c | 34 ++++++++++- 3 files changed, 193 insertions(+), 4 deletions(-) diff --git a/ChangeLog b/ChangeLog index 1b7256048..b1e957b0d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-01-13 Thomas Thurman + + * src/core/bell.c: Commenting. + * src/core/main.c: Commenting, and fixing existing comments. + 2008-01-12 Thomas Thurman * src/core/main.c: Refactor repeated lines in main() to diff --git a/src/core/bell.c b/src/core/bell.c index 6e1f701da..fbca75c5e 100644 --- a/src/core/bell.c +++ b/src/core/bell.c @@ -22,11 +22,57 @@ * 02111-1307, USA. */ +/** + * \file core/bell.c Ring the bell or flash the screen + * + * Sometimes, X programs "ring the bell", whatever that means. Metacity lets + * the user configure the bell to be audible or visible (aka visual), and + * if it's visual it can be configured to be frame-flash or fullscreen-flash. + * We never get told about audible bells; X handles them just fine by itself. + * + * Visual bells come in at meta_bell_notify(), which checks we are actually + * in visual mode and calls through to meta_bell_visual_notify(). That + * function then checks what kind of visual flash you like, and calls either + * meta_bell_flash_fullscreen()-- which calls meta_bell_flash_screen() to do + * its work-- or meta_bell_flash_frame(), which flashes the focussed window + * using meta_bell_flash_window_frame(), unless there is no such window, in + * which case it flashes the screen instead. meta_bell_flash_window_frame() + * flashes the frame and calls meta_bell_unflash_frame() as a timeout to + * remove the flash. + * + * The visual bell was the result of a discussion in Bugzilla here: + * . + * + * Several of the functions in this file are ifdeffed out entirely if we are + * found not to have the XKB extension, which is required to do these clever + * things with bells; some others are entirely no-ops in that case. + * + * \bug Static functions should not be called meta_*. + */ + #include #include "bell.h" #include "screen.h" #include "prefs.h" +/** + * Flashes one entire screen. This is done by making a window the size of the + * whole screen (or reusing the old one, if it's still around), mapping it, + * painting it white and then black, and then unmapping it. We set saveunder so + * that all the windows behind it come back immediately. + * + * Unlike frame flashes, we don't do fullscreen flashes with a timeout; rather, + * we do them in one go, because we don't have to rely on the theme code + * redrawing the frame for us in order to do the flash. + * + * \param display The display which owns the screen (rather redundant) + * \param screen The screen to flash + * + * \bug The way I read it, this appears not to do the flash + * the first time we flash a particular display. Am I wrong? + * + * \bug This appears to destroy our current XSync status. + */ static void meta_bell_flash_screen (MetaDisplay *display, MetaScreen *screen) @@ -89,6 +135,16 @@ meta_bell_flash_screen (MetaDisplay *display, XFlush (display->xdisplay); } +/** + * Flashes one screen, or all screens, in response to a bell event. + * If the event is on a particular window, flash the screen that + * window is on. Otherwise, flash every screen on this display. + * + * If the configure script found we had no XKB, this does not exist. + * + * \param display The display the event came in on + * \param xkb_ev The bell event + */ #ifdef HAVE_XKB static void meta_bell_flash_fullscreen (MetaDisplay *display, @@ -116,6 +172,20 @@ meta_bell_flash_fullscreen (MetaDisplay *display, } } +/** + * Makes a frame be not flashed; this is the timeout half of + * meta_frame_flash(). This is done simply by clearing the flash flag and + * queuing a redraw of the frame. + * + * If the configure script found we had no XKB, this does not exist. + * + * \param data The frame to unflash, cast to a gpointer so it can go into + * a callback function. + * \return Always FALSE, so we don't get called again. + * + * \bug This is the parallel to meta_bell_flash_window_frame(), so it should + * really be called meta_bell_unflash_window_frame(). + */ static gboolean meta_bell_unflash_frame (gpointer data) { @@ -125,6 +195,17 @@ meta_bell_unflash_frame (gpointer data) return FALSE; } +/** + * Makes a frame flash and then return to normal shortly afterwards. + * This is done by setting a flag so that the theme + * code will temporarily draw the frame as focussed if it's unfocussed and + * vice versa, and then queueing a redraw. Lastly, we create a timeout so + * that the flag can be unset and the frame re-redrawn. + * + * If the configure script found we had no XKB, this does not exist. + * + * \param window The window to flash + */ static void meta_bell_flash_window_frame (MetaWindow *window) { @@ -135,6 +216,13 @@ meta_bell_flash_window_frame (MetaWindow *window) meta_bell_unflash_frame, window->frame, NULL); } +/** + * Flashes the frame of the focussed window. If there is no focussed window, + * flashes the screen. + * + * \param display The display the bell event came in on + * \param xkb_ev The bell event we just received + */ static void meta_bell_flash_frame (MetaDisplay *display, XkbAnyEvent *xkb_ev) @@ -158,6 +246,17 @@ meta_bell_flash_frame (MetaDisplay *display, } } +/** + * Gives the user some kind of visual bell substitute, in response to a + * bell event. What this is depends on the "visual bell type" pref. + * + * If the configure script found we had no XKB, this does not exist. + * + * \param display The display the bell event came in on + * \param xkb_ev The bell event we just received + * + * \bug This should be merged with meta_bell_notify(). + */ static void meta_bell_visual_notify (MetaDisplay *display, XkbAnyEvent *xkb_ev) @@ -176,6 +275,16 @@ meta_bell_visual_notify (MetaDisplay *display, } } +/** + * Gives the user some kind of visual bell; in fact, this is our response + * to any kind of bell request, but we set it up so that we only get + * notified about visual bells, and X deals with audible ones. + * + * If the configure script found we had no XKB, this does not exist. + * + * \param display The display the bell event came in on + * \param xkb_ev The bell event we just received + */ void meta_bell_notify (MetaDisplay *display, XkbAnyEvent *xkb_ev) @@ -184,8 +293,17 @@ meta_bell_notify (MetaDisplay *display, if (meta_prefs_get_visual_bell ()) meta_bell_visual_notify (display, xkb_ev); } -#endif +#endif /* HAVE_XKB */ +/** + * Turns the bell to audible or visual. This tells X what to do, but + * not Metacity; you will need to set the "visual bell" pref for that. + * + * If the configure script found we had no XKB, this is a no-op. + * + * \param display The display we're configuring + * \param audible True for an audible bell, false for a visual bell + */ void meta_bell_set_audible (MetaDisplay *display, gboolean audible) { @@ -197,6 +315,27 @@ meta_bell_set_audible (MetaDisplay *display, gboolean audible) #endif } +/** + * Initialises the bell subsystem. This involves intialising + * XKB (which, despite being a keyboard extension, is the + * place to look for bell notifications), then asking it + * to send us bell notifications, and then also switching + * off the audible bell if we're using a visual one ourselves. + * + * Unlike most X extensions we use, we only initialise XKB here + * (rather than in main()). It's possible that XKB is not + * installed at all, but if that was known at build time + * we will have HAVE_XKB undefined, which will cause this + * function to be a no-op. + * + * \param display The display which is opening + * + * \bug There is a line of code that's never run that tells + * XKB to reset the bell status after we quit. Bill H said + * () + * that XFree86's implementation is broken so we shouldn't + * call it, but that was in 2002. Is it working now? + */ gboolean meta_bell_init (MetaDisplay *display) { @@ -238,6 +377,15 @@ meta_bell_init (MetaDisplay *display) return FALSE; } +/** + * Shuts down the bell subsystem. + * + * \param display The display which is closing + * + * \bug This is never called! If we had XkbSetAutoResetControls + * enabled in meta_bell_init(), this wouldn't be a problem, but + * we don't. + */ void meta_bell_shutdown (MetaDisplay *display) { @@ -250,6 +398,14 @@ meta_bell_shutdown (MetaDisplay *display) #endif } +/** + * Deals with a frame being destroyed. This is important because if we're + * using a visual bell, we might be flashing the edges of the frame, and + * so we'd have a timeout function waiting ready to un-flash them. If the + * frame's going away, we can tell the timeout not to bother. + * + * \param frame The frame which is being destroyed + */ void meta_bell_notify_frame_destroy (MetaFrame *frame) { diff --git a/src/core/main.c b/src/core/main.c index 48954551e..365d7d4f7 100644 --- a/src/core/main.c +++ b/src/core/main.c @@ -29,6 +29,17 @@ * kick everything off and then close down Metacity when it's time to go. */ +/** + * \mainpage Metacity - a boring window manager for the adult in you + * + * Many window managers are like Marshmallow Froot Loops; Metacity + * is like Cheerios. + * + * The best way to get a handle on how the whole system fits together + * is discussed in doc/code-overview.txt; if you're looking for functions + * to investigate, read main(), meta_display_open(), and event_callback(). + */ + #include #include "main.h" #include "util.h" @@ -74,6 +85,12 @@ static void prefs_changed_callback (MetaPreference pref, /** * Prints log messages. If Metacity was compiled with backtrace support, * also prints a backtrace (see meta_print_backtrace()). + * + * \param log_domain the domain the error occurred in (we ignore this) + * \param log_level the log level so that we can filter out less + * important messages + * \param message the message to log + * \param user_data arbitrary data (we ignore this) */ static void log_handler (const gchar *log_domain, @@ -185,7 +202,7 @@ meta_print_self_identity (void) /** * The set of possible options that can be set on Metacity's * command line. This type exists so that meta_parse_options() can - * return an instance of it. + * write to an instance of it. */ typedef struct { @@ -205,6 +222,10 @@ typedef struct * The strange call signature has to be written like it is so * that g_option_context_parse() gets a chance to modify argc and * argv. + * + * \param argc Pointer to the number of arguments Metacity was given + * \param argv Pointer to the array of arguments Metacity was given + * \param meta_args The result of parsing the arguments. **/ static void meta_parse_options (int *argc, char ***argv, @@ -271,8 +292,7 @@ meta_parse_options (int *argc, char ***argv, } /** - * Helper function that selects - * which display Metacity should use. It first tries to use + * Selects which display Metacity should use. It first tries to use * display_name as the display. If display_name is NULL then * try to use the environment variable METACITY_DISPLAY. If that * also is NULL, use the default - :0.0 @@ -295,6 +315,9 @@ void meta_select_display (gchar *display_name) * environment variables, sets up the screen, hands control off to * GTK, and cleans up afterwards. * + * \param argc Number of arguments (as usual) + * \param argv Array of arguments (as usual) + * * \bug It's a bit long. It would be good to split it out into separate * functions. */ @@ -503,6 +526,8 @@ main (int argc, char **argv) * the user with no window manager. We generally do this only if, for example, * the session manager asks us to; we assume the session manager knows what * it's talking about. + * + * \param code The success or failure code to return to the calling process. */ void meta_quit (MetaExitCode code) @@ -531,6 +556,9 @@ meta_restart (void) * * \bug Why are these particular prefs handled in main.c and not others? * Should they be? + * + * \param pref Which preference has changed + * \param pref Arbitrary data (which we ignore) */ static void prefs_changed_callback (MetaPreference pref,