metacity r3518 - in trunk: . src/core

[tthurman svn gnome org]

Author: tthurman
Date: Sun Jan 13 16:32:56 2008
New Revision: 3518
URL: http://svn.gnome.org/viewvc/metacity?rev=3518&view=rev

Log:
2008-01-13  Thomas Thurman  <tthurman gnome org>
        * src/core/bell.c: Commenting.
        * src/core/main.c: Commenting, and fixing existing comments.


Modified:
   trunk/ChangeLog
   trunk/src/core/bell.c
   trunk/src/core/main.c

Modified: trunk/src/core/bell.c
==============================================================================
--- trunk/src/core/bell.c	(original)
+++ trunk/src/core/bell.c	Sun Jan 13 16:32:56 2008
@@ -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:
+ * <http://bugzilla.gnome.org/show_bug.cgi?id=99886>.
+ *
+ * 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 <config.h>
 #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 @@
   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 @@
     }
 }
 
+/**
+ * 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 @@
   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_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 @@
     }
 }
 
+/**
+ * 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 @@
     }
 }
 
+/**
+ * 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 @@
   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 @@
 #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
+ * (<http://bugzilla.gnome.org/show_bug.cgi?id=99886#c12>)
+ * 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 @@
   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 @@
 #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)
 {

Modified: trunk/src/core/main.c
==============================================================================
--- trunk/src/core/main.c	(original)
+++ trunk/src/core/main.c	Sun Jan 13 16:32:56 2008
@@ -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 <config.h>
 #include "main.h"
 #include "util.h"
@@ -74,6 +85,12 @@
 /**
  * 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 @@
 /**
  * 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 @@
  * 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 @@
 }
 
 /**
- * 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 @@
  * 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 @@
  * 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 @@
  *
  * \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,